Создание ссылок на действия по электронной почте

Мобильным приложениям иногда необходимо взаимодействовать с пользователями и побуждать их к выполнению определенных действий, отправляя электронные письма.

SDK клиента Firebase позволяют отправлять пользователям электронные письма со ссылками для сброса пароля, подтверждения адреса электронной почты и входа в систему на основе электронной почты. Эти шаблонные письма отправляются Google и имеют ограниченные возможности настройки.

Если вы хотите использовать собственные шаблоны электронных писем и собственную службу доставки, на этой странице объясняется, как с помощью Firebase Admin SDK программно генерировать ссылки для действий в описанных выше сценариях, которые вы можете включить в электронные письма, отправляемые вашим пользователям.

Это дает следующие преимущества:

  • Настраивайте шаблоны электронных писем. Это включает в себя возможность добавления новых стилей и фирменной символики, изменения текста и логотипов, обращения к пользователям по имени вместо полного имени и так далее.
  • Применяйте разные шаблоны в зависимости от контекста. Например, если пользователь подтверждает свой адрес электронной почты для подписки на новостную рассылку, контекст может потребоваться указать в содержимом письма. Другой пример — вход по ссылке из электронного письма: в одном случае это может быть инициировано тем же пользователем, или приглашением от другого пользователя. В этом случае контекст необходимо будет включить в письмо.
  • Локализуйте персонализированные шаблоны электронных писем.
  • Возможность генерировать ссылку из защищенной серверной среды.
  • Возможность настраивать способ открытия ссылки — через мобильное приложение или браузер, а также способ передачи дополнительной информации о состоянии и т.д.
  • Возможность настраивать домен мобильной ссылки, используемый для сценариев мобильного приложения при создании ссылки-действия в электронном письме.

Инициализация настроек кода действия

Прежде чем создавать ссылки для отправки электронных писем, может потребоваться инициализировать экземпляр ActionCodeSettings .

ActionCodeSettings позволяют передавать дополнительное состояние через URL-адрес продолжения, доступный после того, как пользователь щелкнет ссылку в электронном письме. Это также дает пользователю возможность вернуться в приложение после завершения действия. Кроме того, вы можете указать, следует ли обрабатывать ссылку в электронном письме непосредственно из мобильного приложения после его установки или из браузера.

Для ссылок, предназначенных для открытия через мобильное приложение, вам потребуется выполнить ряд действий, чтобы ваше мобильное приложение распознало эти ссылки. Обратитесь к инструкциям по настройке мобильных ссылок для действий в электронной почте.

Для инициализации экземпляра ActionCodeSettings предоставьте следующие данные:

Параметр Тип Описание
url нить

Задает ссылку (URL состояния/продолжения), которая имеет различное значение в разных контекстах:

  • Когда ссылка обрабатывается в виджетах веб-действий, это и есть глубокая ссылка в параметре запроса continueUrl .
  • Когда ссылка обрабатывается непосредственно в приложении, это параметр запроса continueUrl в прямой ссылке Hosting .
iOS ({bundleId: string}|undefined) Устанавливает идентификатор пакета iOS, чтобы помочь Firebase Authentication определить, следует ли создавать веб-ссылку или мобильную ссылку, открываемую на устройстве Apple.
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) Задает имя пакета Android, чтобы помочь Firebase Authentication определить, следует ли создавать веб-ссылку или мобильную ссылку, открываемую на устройстве Android.
handleCodeInApp (логическое значение|неопределенное значение) Определяет, будет ли ссылка в электронном письме сначала открываться в мобильном приложении или по веб-ссылке. По умолчанию — false. Если установлено значение true, ссылка с кодом действия будет отправлена ​​как универсальная ссылка или ссылка на приложение Android и будет открыта приложением, если оно установлено. В случае значения false код будет сначала отправлен в веб-виджет, а затем при продолжении будет перенаправлен в приложение, если оно установлено.
linkDomain (строка|неопределено) При определении пользовательских доменов для ссылок хостинга для проекта укажите, какой из них следует использовать при открытии ссылки указанным мобильным приложением. В противном случае автоматически выбирается домен по умолчанию (например, PROJECT_ID .firebaseapp.com ).
dynamicLinkDomain (строка|неопределено) Устарело. Не указывайте этот параметр.

Следующий пример иллюстрирует, как отправить ссылку для подтверждения по электронной почте, которая сначала откроется в мобильном приложении. Эта прямая ссылка будет содержать URL-адрес для продолжения https://www.example.com/checkout?cartId=1234 . В качестве домена для Hosting используется custom-domain.com , который необходимо настроить для работы с Firebase Hosting .

Node.js 

const actionCodeSettings = {
  // URL you want to redirect back to. The domain (www.example.com) for
  // this URL must be whitelisted in the Firebase Console.
  url: 'https://www.example.com/checkout?cartId=1234',
  // This must be true for email link sign-in.
  handleCodeInApp: true,
  iOS: {
    bundleId: 'com.example.ios',
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12',
  },
  // The domain must be configured in Firebase Hosting and owned by the project.
  linkDomain: 'custom-domain.com',
};

Java 

ActionCodeSettings actionCodeSettings = ActionCodeSettings.builder()
    .setUrl("https://www.example.com/checkout?cartId=1234")
    .setHandleCodeInApp(true)
    .setIosBundleId("com.example.ios")
    .setAndroidPackageName("com.example.android")
    .setAndroidInstallApp(true)
    .setAndroidMinimumVersion("12")
    .setDynamicLinkDomain("coolapp.page.link")
    .build();

Python 

action_code_settings = auth.ActionCodeSettings(
    url='https://www.example.com/checkout?cartId=1234',
    handle_code_in_app=True,
    ios_bundle_id='com.example.ios',
    android_package_name='com.example.android',
    android_install_app=True,
    android_minimum_version='12',
    dynamic_link_domain='coolapp.page.link',
)

Идти 

actionCodeSettings := &auth.ActionCodeSettings{
	URL:                   "https://www.example.com/checkout?cartId=1234",
	HandleCodeInApp:       true,
	IOSBundleID:           "com.example.ios",
	AndroidPackageName:    "com.example.android",
	AndroidInstallApp:     true,
	AndroidMinimumVersion: "12",
	DynamicLinkDomain:     "coolapp.page.link",
}

C# 

var actionCodeSettings = new ActionCodeSettings()
{
    Url = "https://www.example.com/checkout?cartId=1234",
    HandleCodeInApp = true,
    IosBundleId = "com.example.ios",
    AndroidPackageName = "com.example.android",
    AndroidInstallApp = true,
    AndroidMinimumVersion = "12",
    LinkDomain = "coolapp.page.link",
};

Для получения более подробной информации см. раздел «Передача состояния в действиях электронной почты» .

Сгенерировать ссылку для сброса пароля по электронной почте

Для создания ссылки для сброса пароля укажите адрес электронной почты существующего пользователя и, при необходимости, объект ActionCodeSettings . Операция завершится отправкой ссылки по электронной почте. Используемый адрес электронной почты должен принадлежать существующему пользователю.

Node.js 

// Admin SDK API to generate the password reset link.
const userEmail = 'user@example.com';
getAuth()
  .generatePasswordResetLink(userEmail, actionCodeSettings)
  .then((link) => {
    // Construct password reset email template, embed the link and send
    // using custom SMTP server.
    return sendCustomPasswordResetEmail(userEmail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java 

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generatePasswordResetLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python 

email = 'user@example.com'
link = auth.generate_password_reset_link(email, action_code_settings)
# Construct password reset email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Идти 

email := "user@example.com"
link, err := client.PasswordResetLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct password reset template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C# 

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GeneratePasswordResetLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

После генерации ссылки ее можно вставить в созданное вами электронное письмо для сброса пароля, а затем отправить соответствующему пользователю по электронной почте, используя собственный SMTP-сервер.

Если вы используете не стандартную страницу сброса пароля и создаете собственный обработчик событий, см. раздел «Создание пользовательских обработчиков действий электронной почты» .

Сгенерировать ссылку для подтверждения электронной почты

Для генерации ссылки для подтверждения электронной почты укажите неподтвержденный адрес электронной почты существующего пользователя и необязательный объект ActionCodeSettings . Операция завершится отправкой ссылки на подтверждение электронной почты. Используемый адрес электронной почты должен принадлежать существующему пользователю.

Node.js 

// Admin SDK API to generate the email verification link.
const useremail = 'user@example.com';
getAuth()
  .generateEmailVerificationLink(useremail, actionCodeSettings)
  .then((link) => {
    // Construct email verification template, embed the link and send
    // using custom SMTP server.
    return sendCustomVerificationEmail(useremail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java 

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateEmailVerificationLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python 

email = 'user@example.com'
link = auth.generate_email_verification_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Идти 

email := "user@example.com"
link, err := client.EmailVerificationLinkWithSettings(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct email verification template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C# 

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateEmailVerificationLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

После генерации ссылки ее можно вставить в пользовательское письмо для подтверждения, а затем отправить соответствующему пользователю по электронной почте, используя собственный SMTP-сервер.

Если вы используете не стандартную страницу подтверждения электронной почты и создаете собственный обработчик событий, см. раздел «Создание пользовательских обработчиков действий электронной почты» .

Сгенерировать ссылку для входа в систему по электронной почте

Прежде чем вы сможете аутентифицировать пользователей с помощью входа по ссылке из электронной почты, вам необходимо включить эту функцию для вашего проекта Firebase.

Для генерации ссылки для входа в систему укажите адрес электронной почты пользователя и объект ActionCodeSettings . Объект ActionCodeSettings необходим в данном случае, чтобы указать, куда следует вернуть пользователя после нажатия на ссылку для завершения входа в систему. Операция завершится отправкой ссылки на адрес электронной почты.

В отличие от сброса пароля и подтверждения электронной почты, используемый адрес электронной почты не обязательно должен принадлежать существующему пользователю, поскольку эта операция может использоваться для регистрации новых пользователей в вашем приложении по ссылке из электронного письма.

Node.js 

// Admin SDK API to generate the sign in with email link.
const useremail = 'user@example.com';
getAuth()
  .generateSignInWithEmailLink(useremail, actionCodeSettings)
  .then((link) => {
    // Construct sign-in with email link template, embed the link and
    // send using custom SMTP server.
    return sendSignInEmail(useremail, displayName, link);
  })
  .catch((error) => {
    // Some error occurred.
  });

Java 

String email = "user@example.com";
try {
  String link = FirebaseAuth.getInstance().generateSignInWithEmailLink(
      email, actionCodeSettings);
  // Construct email verification template, embed the link and send
  // using custom SMTP server.
  sendCustomEmail(email, displayName, link);
} catch (FirebaseAuthException e) {
  System.out.println("Error generating email link: " + e.getMessage());
}

Python 

email = 'user@example.com'
link = auth.generate_sign_in_with_email_link(email, action_code_settings)
# Construct email from a template embedding the link, and send
# using a custom SMTP server.
send_custom_email(email, link)

Идти 

email := "user@example.com"
link, err := client.EmailSignInLink(ctx, email, actionCodeSettings)
if err != nil {
	log.Fatalf("error generating email link: %v\n", err)
}

// Construct sign-in with email link template, embed the link and send
// using custom SMTP server.
sendCustomEmail(email, displayName, link)

C# 

var email = "user@example.com";
var link = await FirebaseAuth.DefaultInstance.GenerateSignInWithEmailLinkAsync(
    email, actionCodeSettings);
// Construct email verification template, embed the link and send
// using custom SMTP server.
SendCustomEmail(email, displayName, link);

После генерации ссылки ее можно вставить в пользовательское электронное письмо для входа в систему, а затем отправить соответствующему пользователю по электронной почте, используя собственный SMTP-сервер.

Узнайте больше об аутентификации пользователей в Firebase с помощью ссылок из электронных писем . Это поможет предоставить информацию о том, как завершить вход в систему после того, как пользователь перейдет по ссылке и будет перенаправлен обратно в приложение.