在電子郵件操作中傳遞狀態

在發送電子郵件操作以重置密碼或驗證用戶的電子郵件時,您可以通過繼續 URL 傳遞狀態。這使用戶能夠在操作完成後返回應用程序。此外,您可以指定在安裝移動應用程序而不是網頁時是否直接從移動應用程序處理電子郵件操作鏈接。

這在以下常見場景中非常有用:

  • 當前未登錄的用戶可能正在嘗試訪問需要用戶登錄的內容。但是,用戶可能忘記了他們的密碼,因此觸發了重置密碼流程。在流程結束時,用戶希望返回到他們嘗試訪問的應用程序部分。

  • 應用程序只能提供對經過驗證的帳戶的訪問權限。例如,時事通訊可能會要求用戶在訂閱之前驗證他們的電子郵件。用戶將通過電子郵件驗證流程並期望返回應用程序以完成他們的訂閱。

  • 在其他情況下,用戶可能已經從他們的移動設備啟動了流程,並希望在驗證後返回到他們的移動應用程序而不是瀏覽器。

能夠通過 continue URL 傳遞狀態是 Firebase Auth 提供的一項強大功能,可以顯著增強用戶體驗。

在電子郵件操作中傳遞狀態/繼續 URL

為了安全地傳遞一個繼續 URL,需要將該 URL 的域添加為Firebase 控制台中的授權域。這是在身份驗證部分中完成的,方法是將此域添加到登錄方法選項卡下的授權域列表中(如果它尚不存在)。

發送密碼重置郵件或驗證郵件時需要提供firebase.auth.ActionCodeSettings實例。該接口採用以下參數:

範圍類型描述
url細繩

設置在不同上下文中具有不同含義的鏈接(狀態/繼續 URL):

  • 在 Web 操作小部件中處理鏈接時,這是continueUrl查詢參數中的深層鏈接。
  • 直接在app中處理鏈接時,這是動態鏈接的深層鏈接中的continueUrl查詢參數。
iOS ({bundleId:字符串}|未定義)設置 iOS 捆綁包 ID。如果已安裝,這將嘗試在 iOS 應用程序中打開該鏈接。 iOS 應用需要在控制台中註冊。
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined)設置 Android 包名稱。如果已安裝,這將嘗試在 Android 應用程序中打開該鏈接。如果installApp被傳遞,它指定如果設備支持並且尚未安裝該應用程序,是否安裝 Android 應用程序。如果此字段未提供packageName ,則會引發錯誤,說明packageName必須與此字段一起提供。如果指定了minimumVersion ,並且安裝了舊版本的應用程序,用戶將被帶到 Play 商店以升級應用程序。 Android 應用需要在控制台中註冊。
handleCodeInApp (布爾值|未定義)電子郵件操作鏈接是首先在移動應用程序中打開還是在 Web 鏈接中打開。默認值為假。設置為 true 時,操作代碼鏈接將作為通用鏈接或 Android 應用鏈接發送,如果已安裝,將由應用打開。在 false 情況下,代碼將首先發送到 Web 小部件,然後繼續將重定向到已安裝的應用程序。
dynamicLinkDomain (字符串|未定義)如果要使用 Firebase 動態鏈接打開當前鏈接,則設置用於當前鏈接的動態鏈接域(或子域)。由於每個項目可以配置多個動態鏈接域,因此該字段提供了明確選擇一個的能力。如果沒有提供,則默認使用第一個域。

以下示例說明瞭如何使用自定義動態鏈接域example.page.link (iOS 應用程序com.example.ios或 Android 應用程序com.example.android如果尚未安裝應用程序將安裝的com.example.android並且最低版本為12 )。深層鏈接將包含繼續 URL 有效負載https://www.example.com/?email=user@example.com

var actionCodeSettings = {
  url: 'https://www.example.com/?email=' + firebase.auth().currentUser.email,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
    installApp: true,
    minimumVersion: '12'
  },
  handleCodeInApp: true,
  // When multiple custom dynamic link domains are defined, specify which
  // one to use.
  dynamicLinkDomain: "example.page.link"
};
firebase.auth().currentUser.sendEmailVerification(actionCodeSettings)
  .then(function() {
    // Verification email sent.
  })
  .catch(function(error) {
    // Error occurred. Inspect error.code.
  });

Firebase Auth 在發送要在移動應用程序中打開的鏈接時使用Firebase 動態鏈接。要使用此功能,需要在 Firebase 控制台中配置動態鏈接。

  1. 啟用 Firebase 動態鏈接:

    1. Firebase 控制台中,打開動態鏈接部分。
    2. 如果您尚未接受動態鏈接條款並創建動態鏈接域,請立即執行。

      如果您已經創建了動態鏈接域,請記下它。動態鏈接域通常類似於以下示例:

      example.page.link

      當您配置 Apple 或 Android 應用程序以攔截傳入鏈接時,您將需要此值。

  2. 配置 Android 應用程序:

    1. 如果您計劃從 Android 應用程序處理這些鏈接,則需要在 Firebase 控制台項目設置中指定 Android 包名稱。另外,需要提供申請證書的SHA-1和SHA-256。
    2. 您還需要在AndroidManifest.xml文件中為深層鏈接配置意圖過濾器。
    3. 有關這方面的更多信息,請參閱接收 Android 動態鏈接說明
  3. 配置 iOS 應用程序:

    1. 如果您計劃從 iOS 應用程序處理這些鏈接,則需要在 Firebase 控制台項目設置中指定 iOS 捆綁包 ID。此外,App Store ID 和 Apple Developer Team ID 也需要指定。
    2. 您還需要將 FDL 通用鏈接域配置為應用程序功能中的關聯域。
    3. 如果您計劃將應用程序分發到 iOS 8 及以下版本,則需要將您的 iOS 捆綁 ID 設置為傳入 URL 的自定義方案。
    4. 有關這方面的更多信息,請參閱接收 iOS 動態鏈接說明

在 Web 應用程序中處理電子郵件操作

您可以指定是否要先處理來自 Web 應用程序的操作代碼鏈接,然後在成功完成後重定向到另一個網頁或移動應用程序,前提是移動應用程序可用。這是通過在firebase.auth.ActionCodeSettings對像中將handleCodeInApp設置為false來完成的。雖然不需要 iOS 包 ID 或 Android 包名稱,但提供它們將允許用戶在電子郵件操作代碼完成時重定向回指定的應用程序。

此處使用的 Web URL 是在電子郵件操作模板部分中配置的 URL。為所有項目配置了一個默認值。請參閱自定義電子郵件處理程序以了解有關如何自定義電子郵件操作處理程序的更多信息。

在這種情況下, continueUrl查詢參數中的鏈接將是一個 FDL 鏈接,其負載是ActionCodeSettings對像中指定的URL 。雖然您可以攔截和處理來自應用程序的傳入鏈接而無需任何額外依賴,但我們建議使用 FDL 客戶端庫為您解析深層鏈接。

在處理電子郵件驗證等電子郵件操作時,需要從深度鏈接中解析來自oobCode查詢參數的操作代碼,然後通過applyActionCode應用以使更改生效,即要驗證的電子郵件。

在移動應用程序中處理電子郵件操作

如果已安裝,您可以指定是否要首先處理移動應用程序中的操作代碼鏈接。對於 Android 應用程序,您還可以通過android.installApp指定要安裝的應用程序(如果設備支持但尚未安裝)。如果從不支持移動應用程序的設備單擊該鏈接,則會改為從網頁打​​開該鏈接。這是通過在firebase.auth.ActionCodeSettings對像中將handleCodeInApp設置為true來完成的。還需要指定移動應用程序的 Android 包名稱或 iOS 包 ID。

當沒有可用的移動應用程序時,此處使用的後備 Web URL 是在電子郵件操作模板部分中配置的。為所有項目配置了一個默認值。請參閱自定義電子郵件處理程序以了解有關如何自定義電子郵件操作處理程序的更多信息。

在這種情況下,發送給用戶的移動應用鏈接將是一個 FDL 鏈接,其有效負載是操作代碼 URL,在控制台中配置,查詢參數oobCodemodeapiKeycontinueUrl 。後者將是ActionCodeSettings對像中指定的原始URL 。雖然您可以攔截和處理來自應用程序的傳入鏈接而無需任何額外依賴,但我們建議使用 FDL 客戶端庫為您解析深層鏈接。操作代碼可以直接從移動應用程序應用,類似於從自定義電子郵件處理程序部分中描述的 Web 流處理它的方式。

在處理電子郵件驗證等電子郵件操作時,需要從深層鏈接中解析出來自oobCode查詢參數的操作代碼,然後通過applyActionCode應用以使更改生效,即要驗證的電子郵件。