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

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

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

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

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

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

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

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

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

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

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

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

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

  • Когда ссылка обрабатывается в виджетах веб-действий, это глубокая ссылка в параметре запроса continueUrl .
  • Когда ссылка обрабатывается в приложении напрямую, это параметр запроса continueUrl в глубокой ссылке динамической ссылки.
iOS ({bundleId: строка}|не определено) Устанавливает идентификатор пакета. Это попытается открыть ссылку в приложении Apple, если оно установлено. Приложение должно быть зарегистрировано в консоли.
android ({packageName: string, installApp:boolean|undefined, MinimumVersion: string|undefined}|undefined) Устанавливает имя пакета Android. Это попытается открыть ссылку в приложении Android, если оно установлено. Если installApp , он указывает, следует ли устанавливать приложение Android, если устройство поддерживает его, а приложение еще не установлено. Если это поле предоставлено без packageName , выдается ошибка, объясняющая, что packageName должно быть предоставлено вместе с этим полем. Если minimumVersion и установлена ​​более старая версия приложения, пользователь перенаправляется в Play Store для обновления приложения. Приложение Android должно быть зарегистрировано в консоли.
handleCodeInApp (логическое значение | не определено) Будет ли ссылка действия электронной почты сначала открыта в мобильном приложении или в веб-ссылке. Значение по умолчанию — ложь. Если установлено значение true, ссылка на код действия будет отправлена ​​как универсальная ссылка или ссылка на приложение Android и будет открыта приложением, если оно установлено. В ложном случае код сначала будет отправлен в веб-виджет, а затем при продолжении будет перенаправлен в приложение, если оно установлено.
dynamicLinkDomain (строка|не определено) Устанавливает домен динамической ссылки (или поддомен), который будет использоваться для текущей ссылки, если она должна быть открыта с использованием динамических ссылок Firebase. Поскольку для каждого проекта можно настроить несколько доменов динамической ссылки, в этом поле можно явно выбрать один из них. Если ничего не указано, по умолчанию используется самый старый домен.

В следующем примере показано, как отправить ссылку для подтверждения по электронной почте, которая сначала откроется в мобильном приложении как динамическая ссылка Firebase (приложение Apple com.example.ios или приложение Android com.example.android , где приложение будет установлено, если оно еще не установлено, и минимальная версия 12). Ссылка на контент будет содержать полезную нагрузку URL-адреса продолжения https://www.example.com/checkout?cartId=1234 . Используемый домен динамической ссылки — coolapp.page.link , который необходимо настроить для использования с динамическими ссылками Firebase.

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',
  },
  // FDL custom domain.
  dynamicLinkDomain: 'coolapp.page.link',
};

Ява

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