查看 2022 年 Google I/O 大会上介绍的 Firebase 新动态。了解详情

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

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

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

当前未登录的用户可能在尝试访问需要登录才能访问的内容。但是，用户可能已经忘记了自己的密码，因此触发了重设密码流程。在流程结束时，用户期望能回到原来尝试访问的应用部分。
应用可能只允许已通过验证的账号访问。例如，简报应用可能要求用户在订阅之前验证其电子邮件地址。用户将会完成电子邮件验证流程，并希望返回应用以完成订阅。
一般而言，当用户在 Apple 应用中开始密码重设或电子邮件验证流程时，他们希望在应用内完成相应流程；通过接续网址传递状态使得这一点成为可能。

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

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

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

发送密码重设电子邮件或验证电子邮件时，需要提供 ActionCodeSettings 实例。该接口接受以下参数：

参数	类型	说明
`url`	字符串	设置在不同上下文中具有不同含义的链接（状态/接续网址）：当在 Web 操作 widget 中处理链接时，此参数是 `continueUrl` 查询参数中的深层链接。当直接在应用中处理链接时，此参数是动态链接的深层链接中的 `continueUrl` 查询参数。
`iOSBundleId`	字符串	设置软件包 ID。如果用户已安装相关 Apple 应用，设置此参数将尝试在该应用中打开链接。需要在控制台中注册该应用。如果未提供软件包 ID，此字段的值将设为应用主软件包的 ID。
`androidPackageName`	字符串	设置 Android 软件包名称。如果用户已安装相关 Android 应用，设置此参数将尝试在该应用中打开链接。
`androidInstallApp`	布尔值	指定是否要安装相关 Android 应用（如果设备支持该应用，且该应用尚未安装）。如果提供此字段时未提供 packageName，系统将抛出一个错误，提示 packageName 必须与此字段一起提供。
`androidMinimumVersion`	字符串	此流程支持的应用的最低版本。如果指定了 minimumVersion，且用户安装了相关应用的较旧版本，则系统会将用户转至 Play 商店以升级该应用。需要在控制台中注册该 Android 应用。
`handleCodeInApp`	布尔值	决定电子邮件操作链接是优先在移动应用中打开还是优先作为网页链接打开。默认值为 false。当设置为 true 时，操作代码链接将以通用链接或 Android 应用链接的形式发送；如果用户已安装应用，该链接将在应用中打开。如果设置为 false，则系统会先将代码发送到 Web widget，然后在接续时重定向到应用（如果已安装应用）。
`dynamicLinkDomain`	字符串	如果要使用 Firebase Dynamic Links 打开当前链接，此参数可设置要用于当前链接的动态链接网域（或子网域）。由于可以为每个项目配置多个动态链接网域，因此该字段用于明确选择一个动态链接网域。如果未提供动态链接网域，则默认使用第一个网域。

下面的示例阐述了如何发送一个电子邮件验证链接，该链接会作为 Firebase 动态链接（使用自定义动态链接网域 example.page.link）先在移动应用中打开（iOS 应用 com.example.ios 或 Android 应用 com.example.android；如果相应应用尚未安装，则将安装应用，且最低版本为 12）。深层链接将包含接续网址载荷 https://www.example.com/?email=user@example.com。

final user = FirebaseAuth.instance.currentUser;

final actionCodeSettings = ActionCodeSettings(
  url: "http://www.example.com/verify?email=${user?.email}",
  iOSBundleId: "com.example.ios",
  androidPackageName: "com.example.android",
);

await user?.sendEmailVerification(actionCodeSettings);

配置 Firebase Dynamic Links

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

启用 Firebase Dynamic Links：
1. 在 Firebase 控制台中，打开 Dynamic Links 部分。
2. 如果您尚未接受 Dynamic Links 条款，并且也未创建动态链接网域，请立即完成这些操作。
3. 如果您已经创建了动态链接网域，请记下此网域。动态链接网域通常采用如下格式：
```
example.page.link
```
4. 配置 Apple 或 Android 应用以拦截传入链接时，您需要用到此值。
配置 Android 应用：
1. 如果您计划在 Android 应用中处理这些链接，则需要在 Firebase 控制台项目设置中指定 Android 软件包名称。此外，您还需要提供应用证书的 SHA-1 和 SHA-256。
2. 您还需要在 AndroidManifest.xml 文件中为深层链接配置 Intent 过滤条件。
3. 如需了解详情，请参阅接收 Android 动态链接的说明。
配置 Apple 应用：
1. 如果您计划在应用中处理这些链接，则需要在 Firebase 控制台项目设置中指定软件包 ID。此外，您还需要指定 App Store ID 和 Apple Developer Team ID。
2. 您还需要在应用功能中将 FDL 通用链接网域配置为关联网域。
3. 如果您计划将应用分发到 iOS 8 及更低版本，则需要将软件包 ID 设置为传入网址的自定义方案。
4. 如需了解详情，请参阅接收 Apple 平台动态链接的说明。

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

您可以指定是否要先在 Web 应用中处理操作代码链接，然后在成功完成后再重定向到另一个网页或移动应用（如果已安装移动应用）。将 ActionCodeSettings 对象中的 handleCodeInApp 设置为 false，即可完成此操作。尽管在这种情况下不强制要求您提供软件包 ID 或 Android 软件包名称，但提供这些信息可让用户能够在完成电子邮件操作代码流程后重定向回指定的应用。

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

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

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

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

您可以指定是否要先在移动应用中处理操作代码链接（如果已安装移动应用）。对于 Android 应用，您还可以通过 androidInstallApp 指定安装该应用（如果设备支持该应用但尚未安装）。如果用户在不支持该移动应用的设备中点击链接，则链接会改为在网页中打开。将 ActionCodeSettings 对象中的 handleCodeInApp 设置为 true，即可完成此操作。您还需要指定移动应用的 Android 软件包名称或软件包 ID。如果没有任何可供使用的移动应用，此处使用的后备网址是在电子邮件操作模板部分配置的网址。所有项目都预配有一个默认网址。请参阅自定义电子邮件处理程序，详细了解如何对电子邮件操作处理程序进行自定义。

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