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

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

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

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

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

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

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

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

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

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

方法 说明
setUrl(String url)

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

  • 当在 Web 操作 widget 中处理链接时，此参数是 continueUrl 查询参数中的深层链接。
  • 当直接在应用中处理链接时，此参数是动态链接的深层链接中的 continueUrl 查询参数。
setIOSBundleId(String iOSBundleId) 设置 iOS 软件包 ID。如果用户已安装相关 iOS 应用，设置此参数将尝试在该应用中打开链接。需要在控制台中注册该 iOS 应用。
setAndroidPackageName(String androidPackageName, boolean installIfNotAvailable, String minimumVersion) 设置 Android 软件包名称。如果用户已安装相关 Android 应用，设置此参数将尝试在该应用中打开链接。如果 installIfNotAvailable 设为 true，则此参数表明应安装相关 Android 应用（如果设备支持该应用且该应用尚未安装）。如果指定了 minimumVersion，且用户安装了相关应用的较旧版本，则系统会将用户转至 Play 商店以升级该应用。需要在控制台中注册该 Android 应用。
setHandleCodeInApp(boolean status) 决定电子邮件操作链接是先在移动应用中还是先在网页链接中打开。默认值为 false。当设置为 true 时，操作代码链接将以通用链接或 Android 应用链接的形式发送；如果用户已安装应用，该链接将在应用中打开。如果设置为 false，则系统会先将代码发送到 Web widget，然后在接续时重定向到应用（如果已安装应用）。
setDynamicLinkDomain(String dynamicLinkDomain) 如果要使用 Firebase Dynamic Links 动态链接打开当前链接，此参数可设置要用于当前链接的动态链接网域（或子网域）。由于可以为每个项目配置多个动态链接网域，因此该字段用于明确选择一个动态链接网域。如果未提供动态链接网域，则默认使用第一个网域。

以下示例说明了如何发送先在移动应用（iOS 应用 com.example.ios 或 Android 应用 com.example.android）中作为 Firebase Dynamic Links 动态链接打开的电子邮件验证链接。深层链接中将包含接续网址载荷 https://www.example.com/?email=user@example.com。

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 Auth 会使用 Firebase Dynamic Links。如需使用此功能，您需要在 Firebase 控制台中配置 Dynamic Links。

  1. 启用 Firebase Dynamic Links：

    1. 在 Firebase 控制台中，打开 Dynamic Links 部分。

    2. 如果您尚未接受 Dynamic Links 条款，并且也未创建 Dynamic Links 网域，请立即完成这些操作。

      如果您已经创建了 Dynamic Links 网域，请记下此网域。Dynamic Links 网域通常采用如下格式：

      example.page.link

      配置 Apple 或 Android 应用以拦截传入链接时，您需要用到此值。

  2. 配置 Android 应用：

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

  3. 配置 iOS 应用：

    1. 如果您计划在 iOS 应用中处理这些链接，则需要在 Firebase 控制台项目设置中指定 iOS 软件包 ID。此外，您还需要指定 App Store ID 和 Apple Developer Team ID。
    2. 您还需要在应用功能中将 FDL 通用链接网域配置为关联网域。
    3. 如果您计划将应用分发到 iOS 8 及更低版本，则需要将 iOS 软件包 ID 设置为传入网址的自定义方案。
    4. 如需了解详情，请参阅接收 iOS 动态链接的说明。

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

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

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

在此情况下，continueUrl 查询参数中的链接将是一个 FDL 链接，其载荷为 ActionCodeSettings 对象中指定的 URL。尽管您可以在应用中拦截并处理传入链接，而无需任何其他依赖项，但我们仍建议使用 FDL 客户端库解析深层链接。

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

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

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

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

在此情况下，发送给用户的移动应用链接将为 FDL 链接，其载荷是在控制台中配置且包含查询参数 oobCode、mode、apiKey 和 continueUrl 的操作代码网址。后者将是在 ActionCodeSettings 对象中指定的原始 URL。尽管您可以在应用中拦截并处理传入链接，而无需任何其他依赖项，但我们仍建议使用 FDL 客户端库解析深层链接。操作代码可以直接在移动应用中应用，与在 Web 流程中的处理方式类似（参见自定义电子邮件处理程序部分）。

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