Передача состояния в действиях с электронной почтой

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

Это может быть очень полезно в следующих распространенных ситуациях:

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

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

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

Возможность передавать состояние через URL продолжения – это мощная функция, предоставляемая Firebase Auth, которая может значительно повысить удобство для пользователей.

Передача состояния URL продолжения в действиях с электронной почтой

Чтобы безопасно передать URL продолжения, добавьте домен для URL в качестве авторизованного домена:

  1. В консоли Firebase выберите Безопасность > Аутентификация > вкладка Настройки.

  2. В разделе Авторизованные домены нажмите Добавить домен и добавьте URL.

При отправке письма для сброса пароля или письма с подтверждением необходимо указать экземпляр firebase.auth.ActionCodeSettings. Этот интерфейс принимает следующие параметры:

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

Устанавливает ссылку (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 (boolean|undefined) Будет ли ссылка для действия в электронном письме сначала открываться в мобильном приложении или в интернете. По умолчанию присваивается значение false. Если задано значение true, ссылка на код действия будет отправлена как универсальная ссылка или ссылка на приложение для Android и будет открыта приложением, если оно установлено. Если значение параметра false, код сначала будет отправлен в веб-виджет, а затем, если приложение установлено, при нажатии кнопки "Продолжить" произойдет перенаправление в приложение.
linkDomain (string|undefined) Если для проекта определены специальные домены ссылок Hosting, укажите, какой из них нужно использовать, когда ссылка открывается в определенном мобильном приложении. В противном случае автоматически выбирается домен по умолчанию (например, PROJECT_ID.firebaseapp.com).
dynamicLinkDomain (string|undefined) Поддержка прекращена. Не указывайте этот параметр.

В примере ниже показано, как отправить ссылку для подтверждения адреса электронной почты, которая сначала откроется в мобильном приложении, используя пользовательский домен Hostingcustom-domain.com. Ссылка на контент будет содержать полезную нагрузку URL продолжения https://www.example.com/?email=user@example.com.

const actionCodeSettings = {
  url: 'https://www.example.com/?email=' + firebase.auth().currentUser.email,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
  },
  handleCodeInApp: true,
  // Specify a custom Hosting link domain to use. The domain must be
  // configured in Firebase Hosting and owned by the project.
  linkDomain: "custom-domain.com"
};
firebase.auth().currentUser.sendEmailVerification(actionCodeSettings)
  .then(function() {
    // Verification email sent.
  })
  .catch(function(error) {
    // Error occurred. Inspect error.code.
  });

Firebase Authentication использует Firebase Hosting при отправке ссылки, которая должна открываться в мобильном приложении. Чтобы использовать эту функцию, в консоли Firebase нужно настроить ссылки на хостинг.

  1. Настройка приложений для Android:

    1. Если вы планируете обрабатывать эти ссылки в приложении для Android, название пакета приложения необходимо указать в настройках проекта консоли Firebase. Кроме того, необходимо указать SHA-1 и SHA-256 сертификата приложения.
    2. Вам также потребуется настроить фильтр интентов для ссылки на контент в файле AndroidManifest.xml.
    3. Подробнее о том, как получать ссылки на хостинговые приложения для Android…

  2. Настройка приложений для iOS:

    1. Если вы планируете обрабатывать эти ссылки в приложении для iOS, вам нужно будет настроить домен ссылки Hosting как связанный домен в возможностях приложения.
    2. Подробнее о том, как получать ссылки на размещенный контент для iOS…

Как обрабатывать действия с электронной почтой в веб-приложении

Вы можете указать, хотите ли вы сначала обработать ссылку с кодом действия из веб-приложения, а затем перенаправить пользователя на другую веб-страницу или в мобильное приложение (если оно доступно). Для этого в объекте firebase.auth.ActionCodeSettings нужно задать для параметра handleCodeInApp значение false. Идентификатор пакета iOS или название пакета Android не являются обязательными, но если вы их укажете, пользователь сможет вернуться в приложение после того, как введет код подтверждения из письма.

Здесь используется URL, настроенный в разделе шаблонов действий с электронной почтой. Для всех проектов по умолчанию предоставляется одна квота. Подробнее о том, как настроить обработчик действий с электронной почтой, рассказывается в статье Как настроить обработчики электронной почты.

В этом случае ссылка в параметре запроса continueUrl будет ссылкой на хостинг, полезная нагрузка которой – это URL, указанный в объекте ActionCodeSettings.

При обработке действий с электронной почтой, например подтверждения адреса электронной почты, код действия из параметра запроса oobCode необходимо извлечь из ссылки на контент и применить с помощью applyActionCode, чтобы изменение вступило в силу (например, чтобы адрес электронной почты был подтвержден).

Как обрабатывать действия с электронной почтой в мобильном приложении

Вы можете указать, нужно ли сначала обрабатывать ссылку с кодом действия в мобильном приложении, если оно установлено. Если на ссылку нажимают на устройстве, которое не поддерживает мобильное приложение, она открывается на веб-странице. Для этого в объекте firebase.auth.ActionCodeSettings нужно задать для параметра handleCodeInApp значение true. Вам также потребуется указать название пакета Android или идентификатор пакета iOS.

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

В этом случае ссылка на мобильное приложение, отправленная пользователю, будет ссылкой Hosting, полезная нагрузка которой представляет собой URL кода действия, настроенный в консоли, с параметрами запроса oobCode, mode, apiKey и continueUrl. Последний будет исходным значением URL, указанным в объекте ActionCodeSettings. Код действия можно применить непосредственно из мобильного приложения, как и в случае с веб-интерфейсом, описанным в разделе Как настроить обработчики электронной почты.

При обработке действий с электронной почтой, например подтверждения адреса электронной почты, код действия из параметра запроса oobCode необходимо извлечь из ссылки на контент и применить с помощью applyActionCode, чтобы изменение вступило в силу (например, чтобы адрес электронной почты был подтвержден).