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

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

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

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

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

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

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

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

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

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

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

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

Метод Описание
setUrl(String url)

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

  • Когда ссылка обрабатывается в виджетах веб-действий, она становится ссылкой на контент в параметре запроса continueUrl.
  • Если ссылка обрабатывается непосредственно в приложении, это параметр запроса continueUrl в ссылке на контент из ссылки Hosting.
setIOSBundleId(String iOSBundleId) Устанавливает идентификатор пакета iOS, чтобы Firebase Authentication мог определить, нужно ли создавать ссылку только для сайта или мобильную ссылку, которая открывается на устройстве Apple.
setAndroidPackageName(String androidPackageName, boolean installIfNotAvailable, String minimumVersion) Устанавливает название пакета Android, чтобы Firebase Authentication мог определить, нужно ли создавать ссылку только для сайта или мобильную ссылку, которая открывается на устройстве Android.
setHandleCodeInApp(boolean status) Будет ли ссылка для действия в электронном письме сначала открываться в мобильном приложении или в интернете. По умолчанию присваивается значение false. Если задано значение true, ссылка на код действия будет отправлена как универсальная ссылка или ссылка на приложение Android и будет открыта приложением, если оно установлено. Если значение параметра false, код сначала будет отправлен в веб-виджет, а затем, если приложение установлено, при нажатии кнопки "Продолжить" произойдет перенаправление в приложение.
setLinkDomain(String customDomain) Если для проекта определены специальные домены ссылок Hosting, укажите, какой из них нужно использовать, когда ссылка открывается в определенном мобильном приложении. В противном случае автоматически выбирается домен по умолчанию (например, PROJECT_ID.firebaseapp.com).
setDynamicLinkDomain(String dynamicLinkDomain) Поддержка прекращена. Не указывайте этот параметр.

В примере ниже показано, как отправить ссылку для подтверждения адреса электронной почты, которая сначала откроется в мобильном приложении. Ссылка на контент будет содержать полезную нагрузку URL продолжения http://www.example.com/verify?uid=1234.

Kotlin

val auth = Firebase.auth
val user = auth.currentUser!!

val url = "http://www.example.com/verify?uid=" + user.uid
val actionCodeSettings = ActionCodeSettings.newBuilder()
    .setUrl(url)
    .setIOSBundleId("com.example.ios")
    // The default for this is populated with the current android package name.
    .setAndroidPackageName("com.example.android", false, null)
    .build()

user.sendEmailVerification(actionCodeSettings)
    .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            Log.d(TAG, "Email sent.")
        }
    }

Java

FirebaseAuth auth = FirebaseAuth.getInstance();
FirebaseUser user = auth.getCurrentUser();

String url = "http://www.example.com/verify?uid=" + user.getUid();
ActionCodeSettings actionCodeSettings = ActionCodeSettings.newBuilder()
        .setUrl(url)
        .setIOSBundleId("com.example.ios")
        // The default for this is populated with the current android package name.
        .setAndroidPackageName("com.example.android", false, null)
        .build();

user.sendEmailVerification(actionCodeSettings)
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                if (task.isSuccessful()) {
                    Log.d(TAG, "Email sent.");
                }
            }
        });

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…

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

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

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

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

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

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

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

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

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

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