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

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

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

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

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

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

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

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

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

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

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

Параметр	Тип	Описание
url	нить	Устанавливает ссылку (URL-адрес состояния/продолжения), которая имеет разные значения в разных контекстах: Когда ссылка обрабатывается в виджетах веб-действий, это глубокая ссылка в параметре запроса continueUrl . Если ссылка обрабатывается непосредственно в приложении, это параметр запроса continueUrl в глубокой ссылке динамической ссылки.
iOS	({bundleId: строка}|не определено)	Устанавливает идентификатор пакета. Будет предпринята попытка открыть ссылку в приложении Apple, если оно установлено. Приложение необходимо зарегистрировать в консоли.
android	({packageName: строка, installApp:boolean|не определено, минимальная версия: строка|не определено}|не определено)	Устанавливает имя пакета 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 = '[e-mail]';
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 = "[e-mail]";
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 = '[e-mail]'
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 := "[e-mail]"
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 = "[e-mail]";
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 = '[e-mail]';
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 = "[e-mail]";
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 = '[e-mail]'
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 := "[e-mail]"
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 = "[e-mail]";
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 = '[e-mail]';
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 = "[e-mail]";
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 = '[e-mail]'
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 := "[e-mail]"
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 = "[e-mail]";
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 с помощью ссылок электронной почты . Это поможет предоставить информацию о том, как завершить вход после того, как пользователь щелкнет ссылку и будет перенаправлен обратно в приложение.