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

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

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

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

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

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

Инициализировать ActionCodeSettings

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

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

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

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

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

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

  • Когда ссылка обрабатывается в виджетах веб-действий, это глубокая ссылка в параметре запроса continueUrl .
  • Когда ссылка обрабатывается в приложении напрямую, это параметр запроса continueUrl в глубинной ссылке ссылки Hosting .
iOS ({bundleId: string}|не определено) Устанавливает идентификатор пакета iOS, чтобы помочь Firebase Authentication определить, следует ли создавать веб-ссылку или мобильную ссылку, открываемую на устройстве Apple.
android ({packageName: string, installApp:boolean|не определено, minimumVersion: string|не определено}|не определено) Задает имя пакета 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',
};

Ява

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();

Питон

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",
}

С#

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",
    DynamicLinkDomain = "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.
  });

Ява

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());
}

Питон

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)

С#

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.
  });

Ява

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());
}

Питон

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)

С#

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.
  });

Ява

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());
}

Питон

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)

С#

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 с помощью ссылок электронной почты . Это поможет предоставить информацию о том, как завершить вход после того, как пользователь нажмет на ссылку и будет перенаправлен обратно в приложение.