在电子邮件操作中传递状态

发送用于重设密码或验证用户邮箱的电子邮件操作时，您可以通过“接续网址”传递状态。这样用户可以在操作完成后返回应用。此外，如果用户安装了移动应用，您可以指定是否直接从移动应用（而不是网页）处理电子邮件操作链接。

此功能非常适合用于以下常见情况：

  • 当前未登录的用户可能在尝试访问需要登录才能访问的内容。但是，用户可能已经忘记了自己的密码，因此触发了重设密码流程。在流程结束时，用户期望能回到原来尝试访问的应用部分。

  • 应用可能只允许已通过验证的账号访问。例如，简报可能要求用户在订阅之前验证其电子邮件地址。用户将会完成电子邮件验证流程，并期望会回到应用以完成订阅。

  • 在其他情况下，用户可能是在其移动设备上启动此流程，并期望在验证之后会回到自己的移动应用（而不是浏览器）。

通过接续网址传递状态是 Firebase Auth 提供的一项强大功能，可以显著提升用户体验。

在电子邮件操作中传递接续网址的状态

为了安全地传递接续网址，需要在 Firebase 控制台中将网址对应的网域列入白名单。如果还没有将相应网域列入白名单，您可在 Authentication 部分将该网域添加到 Sign-in method（登录方法）标签页下的已获授权的网域列表中来实现此目的。

发送密码重设电子邮件或验证电子邮件时，需要提供 ActionCodeSettings 实例。该实例可通过关联的 ActionCodeSettings.Builder 类创建，其中包含以下方法：

方法 说明
setUrl(String url)

设置在不同场景中具有不同含义的链接（状态/接续网址）：

  • 当在 Web 操作 widget 中处理链接时，此参数是 continueUrl 查询参数中的深层链接。
  • 当直接在应用中处理链接时，此参数是 Hosting 链接的深层链接中的 continueUrl 查询参数。
setIOSBundleId(String iOSBundleId) 设置 iOS 软件包 ID，以帮助 Firebase Authentication 确定是否应创建在 Apple 设备上打开的网站专属链接或移动链接
setAndroidPackageName(String androidPackageName, boolean installIfNotAvailable, String minimumVersion) 设置 Android 软件包名称，以帮助 Firebase Authentication 确定是否应创建在 Android 设备上打开的网站专属链接或移动链接
setHandleCodeInApp(boolean status) 决定电子邮件操作链接是优先在移动应用中打开还是优先作为网页链接打开。默认值为 false。当设置为 true 时，操作代码链接将以通用链接或 Android 应用链接的形式发送；如果用户已安装应用，该链接将在应用中打开。如果设置为 false，则系统会先将代码发送到 Web widget，然后在接续时重定向到应用（如果已安装应用）。
setLinkDomain(String customDomain) 如果为项目定义了自定义 Hosting 链接网域，请指定在通过指定的移动应用打开链接时应使用哪个网域。否则，系统会自动选择默认网域（例如 PROJECT_ID.firebaseapp.com）。
setDynamicLinkDomain(String dynamicLinkDomain) 已弃用。请勿指定此参数。

以下示例说明了如何发送先在移动应用中打开的电子邮件验证链接。深层链接将包含接续网址载荷 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.")
        }
    }

MainActivity.kt

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

MainActivity.java

在发送要在移动应用中打开的链接时，Firebase Authentication 会使用 Firebase Hosting。如需使用此功能，您需要在 Firebase 控制台中配置 Hosting 链接。

  1. 配置 Android 应用：

    1. 如果您计划在 Android 应用中处理这些链接，则需要在 Firebase 控制台项目设置中指定应用的软件包名称。此外，您还需要提供应用证书的 SHA-1 和 SHA-256。
    2. 您还需要在 AndroidManifest.xml 文件中为深层链接配置 intent 过滤器。
    3. 如需了解详情，请参阅接收 Android Hosting 链接的说明。

  2. 配置 iOS 应用：

    1. 如果您计划在 iOS 应用中处理这些链接，则需要在应用功能中将 Hosting 链接网域配置为关联网域。
    2. 如需了解详情，请参阅接收 iOS Hosting 链接的说明。

在 Web 应用中处理电子邮件操作

您可以指定是否要先在 Web 应用中处理操作代码链接，然后在成功完成后再重定向到另一个网页或移动应用（如果已安装移动应用）。可以通过调用 ActionCodeSettings.Builder 对象中的 setHandleCodeInApp(false) 方法做到这一点。尽管在这种情况下不强制要求您提供 iOS 软件包 ID 或 Android 软件包名称，但提供这些信息将允许用户在完成电子邮件操作代码流程后重定向回指定的应用。

此处使用的网址是在电子邮件操作模板部分配置的网址。所有项目都预配有一个默认网址。请参阅自定义电子邮件处理程序，详细了解如何对电子邮件操作处理程序进行自定义。

在此情况下，continueUrl 查询参数中的链接将是一个 Hosting 链接，其载荷为 ActionCodeSettings 对象中指定的 URL。

处理邮箱验证等电子邮件操作时，需要解析深层链接的 oobCode 查询参数中的操作代码，然后通过 applyActionCode 应用此操作代码以使更改生效，也就是让邮箱得到验证。

在移动应用中处理电子邮件操作

您可以指定是否要先在移动应用中处理操作代码链接（如果已安装移动应用）。如果用户在不支持该移动应用的设备中点击链接，则链接会改为在网页中打开。可以通过调用 ActionCodeSettings.Builder 对象中的 setHandleCodeInApp(true) 方法做到这一点。您还需要指定移动应用的 Android 软件包名称或 iOS 软件包 ID。

如果没有任何可供使用的移动应用，此处使用的后备网址是在电子邮件操作模板部分配置的网址。所有项目都配置有一个默认网址。请参阅自定义电子邮件处理程序，详细了解如何对电子邮件操作处理程序进行自定义。

在此情况下，发送给用户的移动应用链接将为 Hosting 链接，其载荷是在控制台中配置且包含查询参数 oobCode、mode、apiKey 和 continueUrl 的操作代码网址。后者将是在 ActionCodeSettings 对象中指定的原始 URL。操作代码可以直接在移动应用中应用，与在网页流程中的处理方式类似（参见自定义电子邮件处理程序部分）。

处理邮箱验证等电子邮件操作时，需要解析深层链接的 oobCode 查询参数中的操作代码，然后通过 applyActionCode 应用此操作代码以使更改生效，也就是让邮箱得到验证。