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

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

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

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

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

  • 一般而言，当用户在 Apple 应用中开始密码重设或电子邮件验证流程时，他们希望在应用内完成相应流程；通过接续网址传递状态使得这一点成为可能。

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

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

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

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

Swift

参数 类型 说明
URL 字符串

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

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

Objective-C

参数 类型 说明
URL NSString

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

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

以下示例说明了如何发送先在移动应用中打开的电子邮件验证链接（使用自定义 Hosting 链接网域 custom-domain.com）。深层链接将包含接续网址载荷 https://www.example.com/?email=user@example.com。

Swift

var actionCodeSettings =  ActionCodeSettings.init()
actionCodeSettings.canHandleInApp = true
let user = Auth.auth().currentUser()
actionCodeSettings.URL =
    String(format: "https://www.example.com/?email=%@", user.email)
actionCodeSettings.iOSbundleID = Bundle.main.bundleIdentifier!
actionCodeSettings.setAndroidPakageName("com.example.android")
// Specify a custom Hosting link domain to use. The domain must be
// configured in Firebase Hosting and owned by the project.
actionCodeSettings.linkDomain = "custom-domain.com"
user.sendEmailVerification(withActionCodeSettings:actionCodeSettings { error in
  if error {
    // Error occurred. Inspect error.code and handle error.
    return
  }
  // Email verification sent.
})

Objective-C

 FIRActionCodeSettings *actionCodeSettings = [[FIRActionCodeSettings alloc] init];
 actionCodeSettings.handleCodeInApp = YES;
 FIRUser *user = [FIRAuth auth].currentUser;
 NSString *urlString =
     [NSString stringWithFormat:@"https://www.example.com/?email=%@", user.email];
 actionCodeSettings.URL = [NSURL URLWithString:urlString];
 actionCodeSettings.iOSBundleID = [NSBundle mainBundle].bundleIdentifier;
// Specify a custom Hosting link domain to use. The domain must be
// configured in Firebase Hosting and owned by the project.
 actionCodeSettings.linkDomain = @"custom-domain.com";
 [actionCodeSettings setAndroidPackageName:@"com.example.android"];
 [user sendEmailVerificationWithActionCodeSettings:actionCodeSettings
                                        completion:^(NSError *_Nullable error) {
   if (error) {
     // Error occurred. Inspect error.code and handle error.
     return;
   }
   // Email verification sent.
 }];

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

  1. 配置 Apple 应用：

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

  2. 配置 Android 应用：

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

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

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

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

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

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

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

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

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

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