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

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

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

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

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

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

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

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

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

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

範圍類型描述
url細繩

設置在不同上下文中具有不同含義的鏈接(state/continue 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 應用程序鏈接發送,如果已安裝,將由應用程序打開。在錯誤的情況下,代碼將首先發送到網絡小部件,然後繼續將重定向到應用程序(如果已安裝)。
dynamicLinkDomain (字符串|未定義)如果要使用 Firebase 動態鏈接打開當前鏈接,則設置要用於當前鏈接的動態鏈接域(或子域)。由於可以為每個項目配置多個動態鏈接域,因此該字段提供了明確選擇一個的能力。如果未提供,則默認使用第一個域。

以下示例說明瞭如何使用自定義動態鏈接域example.page.link (iOS 應用程序com.example.ios或 Android 應用程序com.example.android如果應用程序尚未安裝且最低版本為12 ,則將安裝該應用程序的com.example.android 。深層鏈接將包含繼續 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 包名稱,但提供它們將允許用戶在電子郵件操作代碼完成時重定向回指定的應用程序。

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

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

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

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

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

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

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

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