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

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

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

  • 当前未登录的用户可能在尝试访问需要登录才能访问的内容。但是,用户可能已经忘记了他们的密码,因此触发了重设密码流程。在流程结束时,用户希望返回应用中他们原本尝试访问的部分。

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

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

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

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

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

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

Swift

参数 类型 说明
URL 字符串

设置在不同上下文中具有不同含义的链接(状态/接续网址):

  • 当在网页操作微件中处理链接时,此参数是 continueUrl 查询参数中的深层链接。
  • 当直接在应用中处理链接时,此参数是动态链接的深层链接中的 continueUrl 查询参数。
iOSBundleID 字符串 设置 iOS 软件包 ID。如果用户已安装相关 iOS 应用,此参数将尝试在该应用中打开链接。需要在控制台中注册该 iOS 应用。如果未提供软件包 ID,此字段的值将设为应用主软件包的软件包 ID。
androidPackageName 字符串 设置 Android 软件包名称。如果用户已安装相关 Android 应用,此参数将尝试在该应用中打开链接。
androidInstallIfNotAvailable 布尔值 指定是否要安装相关 Android 应用(如果设备支持但尚未安装该应用)。如果提供此字段时未提供 packageName,系统将抛出一个错误,提示 packageName 必须与此字段一起提供。
androidMinimumVersion 字符串 此流程支持的应用的最低版本。如果指定了 minimumVersion,且用户安装了相关应用的较旧版本,则用户将被定向到 Play 商店以升级该应用。需要在控制台中注册该 Android 应用。
handleCodeInApp 布尔值 决定电子邮件操作链接是先在移动应用中还是先在网页链接中打开。默认值为 false。当设置为 true 时,操作码链接将以通用链接或 Android 应用链接的形式发送;如果用户安装了应用,该链接将在应用中打开。如果设置为 false,则系统会先将代码发送到网页微件,然后将继续重定向到该应用(如果该应用已安装)。

Objective-C

参数 类型 说明
URL NSString

设置在不同上下文中具有不同含义的链接(状态/接续网址):

  • 当在网页操作微件中处理链接时,此参数是 continueUrl 查询参数中的深层链接。
  • 当直接在应用中处理链接时,此参数是动态链接的深层链接中的 continueUrl 查询参数。
iOSBundleID NSString 设置 iOS 软件包 ID。如果用户已安装相关 iOS 应用,此参数将尝试在该应用中打开链接。需要在控制台中注册该 iOS 应用。
androidPackageName NSString 设置 Android 软件包名称。如果用户已安装相关 Android 应用,此参数将尝试在该应用中打开链接。
androidInstallIfNotAvailable 布尔值 指定是否要安装相关 Android 应用(如果设备支持该应用且该应用尚未安装)。如果提供此字段时未提供 packageName,系统将抛出一个错误,提示 packageName 必须与此字段一起提供。
androidMinimumVersion NSString 此流程支持的应用的最低版本。如果指定了 minimumVersion,且用户安装了相关应用的较旧版本,则用户将被定向到 Play 商店以升级该应用。需要在控制台中注册该 Android 应用。
handleCodeInApp 布尔值 决定电子邮件操作链接是先在移动应用中还是先在网页链接中打开。默认值为 false。当设置为 true 时,操作码链接将以通用链接或 Android 应用链接的形式发送;如果用户安装了应用,该链接将在应用中打开。如果设置为 false,则系统会先将代码发送到网页微件,然后将继续重定向到该应用(如果该应用已安装)。

下面的示例阐述了如何发送一个电子邮件验证链接,该链接会作为 Firebase 动态链接先在移动应用中打开(iOS 应用 com.example.ios 或 Android 应用 com.example.android;如果相应应用尚未安装,则将安装应用,且最低版本为 12)。深层链接将包含接续网址负载 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",
                                         installIfNotAvailable:true,
                                         minumumVersion:"12")
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;
 [actionCodeSettings setAndroidPackageName:@"com.example.android"
                     installIfNotAvailable:YES
                            minimumVersion:'12'];
 [user sendEmailVerificationWithActionCodeSettings:actionCodeSettings
                                        completion:^(NSError *_Nullable error) {
   if (error) {
     // Error occurred. Inspect error.code and handle error.
     return;
   }
   // Email verification sent.
 }];

在发送要在移动应用中打开的链接时,Firebase 身份验证会使用 Firebase 动态链接。要使用此功能,您需要在 Firebase 控制台中配置动态链接。

  1. 启用 Firebase 动态链接:

    1. Firebase 控制台中,打开 Dynamic Links(动态链接)部分。
    2. 如果您尚未接受动态链接条款,并且也未创建动态链接网域,请立即完成这些操作。

      如果您已经创建了动态链接网域,请记下它。动态链接网域通常采用如下格式:

      example.page.link

      配置 iOS 或 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 动态链接的说明

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

您可以指定是否要先在网页应用中处理操作代码链接,然后在成功完成后重定向到另一个网页或移动应用(如果移动应用可供使用的话)。此操作通过在 FIRActionCodeSettings (Obj-C) 或 ActionCodeSettings (Swift) 对象中将 handleCodeInApp 设置为 false 来完成。尽管不需要提供 iOS 软件包 ID 或 Android 软件包名称,但提供这些信息将允许用户在完成电子邮件操作代码流程后重定向回指定的应用。

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

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

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

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

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

发送以下问题的反馈:

此网页
需要帮助?请访问我们的支持页面