電子郵件動作中的狀態

傳送密碼重設或驗證使用者電子郵件的電子郵件動作時，您可以透過繼續網址傳遞狀態。這樣一來，使用者就能在完成動作後返回應用程式。此外，您也可以指定是否要直接從已安裝的行動應用程式處理電子郵件動作連結，而非網頁。

在下列常見情境中，這項功能非常實用：

  • 使用者可能尚未登入，但嘗試存取需要登入才能存取的內容。不過，使用者可能忘記密碼，因此觸發密碼重設流程。流程結束時，使用者應會返回他們嘗試存取的應用程式部分。

  • 應用程式只能提供經過驗證的帳戶存取權。舉例來說，使用者可能需要先驗證電子郵件地址，才能訂閱電子報。使用者會完成電子郵件驗證流程，並預期返回應用程式完成訂閱。

  • 在其他情況下，使用者可能從行動裝置啟動流程，並期望驗證後返回行動應用程式，而不是瀏覽器。

透過繼續網址傳遞狀態是 Firebase Auth 提供的一項強大功能，可大幅提升使用者體驗。

在電子郵件動作中傳遞延續網址的狀態

如要安全地傳遞繼續網址，請在 Firebase 控制台中將網址的網域新增為授權網域。 如要完成這項操作，請前往「Authentication」(驗證) 專區，然後在「Sign-in method」(登入方式) 分頁下，將這個網域新增至「Authorized domains」(已授權網域) 清單 (如果尚未新增)。

傳送密碼重設電子郵件或驗證電子郵件時，必須提供 firebase.auth.ActionCodeSettings 例項。這個介面會採用下列參數：

參數 類型 說明
url 字串

設定連結 (狀態/繼續網址)，在不同情境中具有不同意義：

  • 在網頁動作小工具中處理連結時，這是 continueUrl 查詢參數中的深層連結。
  • 如果應用程式直接處理連結，這就是連結深層連結中的 continueUrl 查詢參數。Hosting
iOS ({bundleId: string}|undefined) 設定 iOS 軟體包 ID，協助 Firebase Authentication 判斷是否應建立僅限網頁或行動連結，並在 Apple 裝置上開啟
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) 設定 Android 套件名稱，協助 Firebase Authentication 判斷是否應建立僅限網頁或行動連結，並在 Android 裝置上開啟
handleCodeInApp (boolean|undefined) 電子郵件動作連結會先在行動應用程式或網頁連結中開啟。預設值為 false。如果設為 true，系統會將動作代碼連結做為通用連結或 Android 應用程式連結傳送，並在安裝應用程式後開啟。如果為 false，系統會先將驗證碼傳送至網頁小工具，然後在使用者繼續操作時，將其重新導向至應用程式 (如果已安裝)。
linkDomain (字串|未定義) 為專案定義自訂 Hosting 連結網域時，請指定要使用哪個網域，讓連結由指定的行動應用程式開啟。否則，系統會自動選取預設網域 (例如 PROJECT_ID.firebaseapp.com)。
dynamicLinkDomain (字串|未定義) 已淘汰，請勿指定此參數。

以下範例說明如何使用自訂 Hosting 網域 custom-domain.com，傳送會先在行動應用程式中開啟的電子郵件驗證連結。深層連結會包含繼續網址酬載 https://www.example.com/?email=user@example.com。

const actionCodeSettings = {
  url: 'https://www.example.com/?email=' + firebase.auth().currentUser.email,
  iOS: {
    bundleId: 'com.example.ios'
  },
  android: {
    packageName: 'com.example.android',
  },
  handleCodeInApp: true,
  // Specify a custom Hosting link domain to use. The domain must be
  // configured in Firebase Hosting and owned by the project.
  linkDomain: "custom-domain.com"
};
firebase.auth().currentUser.sendEmailVerification(actionCodeSettings)
  .then(function() {
    // Verification email sent.
  })
  .catch(function(error) {
    // Error occurred. Inspect error.code.
  });

Firebase Authentication 會在傳送要在行動應用程式中開啟的連結時使用 Firebase Hosting。如要使用這項功能，請在 Firebase 控制台中設定主機連結。

  1. 設定 Android 應用程式：

    1. 如果您打算從 Android 應用程式處理這些連結，請在 Firebase 控制台專案設定中指定應用程式的套件名稱。此外，您還需要提供應用程式憑證的 SHA-1 和 SHA-256。
    2. 您也需要在 AndroidManifest.xml 檔案中設定深層連結的意圖篩選器。
    3. 詳情請參閱「接收 Android 主機連結的操作說明」。

  2. 設定 iOS 應用程式：

    1. 如果您打算從 iOS 應用程式處理這些連結，請在應用程式功能中，將 Hosting 連結網域設定為關聯網域。
    2. 詳情請參閱「接收 iOS 代管連結的操作說明」。

在網路應用程式中處理電子郵件動作

您可以指定是否要先從網路應用程式處理動作代碼連結，然後在成功完成後重新導向至其他網頁或行動應用程式 (如果行動應用程式可用)。方法是在 firebase.auth.ActionCodeSettings 物件中將 handleCodeInApp 設為 false。雖然不一定要提供 iOS 軟體包 ID 或 Android 套件名稱，但如果提供，使用者完成電子郵件動作代碼後，就能重新導向至指定應用程式。

這裡使用的網址是電子郵件動作範本部分中設定的網址。系統會為所有專案佈建預設的服務帳戶。如要進一步瞭解如何自訂電子郵件動作處理常式，請參閱自訂電子郵件處理常式。

在這種情況下，continueUrl 查詢參數中的連結會是 Hosting 連結，其酬載是 ActionCodeSettings 物件中指定的 URL。

處理電子郵件驗證等電子郵件動作時，需要從深層連結剖析 oobCode 查詢參數中的動作代碼，然後透過 applyActionCode 套用，變更才會生效 (即驗證電子郵件)。

在行動應用程式中處理電子郵件動作

您可以指定是否要先在行動應用程式中處理動作程式碼連結 (如果已安裝)。如果使用者從不支援行動應用程式的裝置點選連結，系統會改為開啟網頁。方法是在 firebase.auth.ActionCodeSettings 物件中將 handleCodeInApp 設為 true。您也需要指定行動應用程式的 Android 套件名稱或 iOS 軟體包 ID。

如果沒有可用的行動應用程式，系統會使用電子郵件動作範本部分中設定的備用網頁網址。系統會為所有專案佈建預設的專案。如要進一步瞭解如何自訂電子郵件動作處理常式，請參閱自訂電子郵件處理常式。

在這種情況下，傳送給使用者的行動應用程式連結會是 Hosting 連結，其酬載是您在管理中心設定的動作代碼網址，並包含查詢參數 oobCode、mode、apiKey 和 continueUrl。後者是 ActionCodeSettings 物件中指定的原始 URL。您可以直接從行動應用程式套用動作代碼，做法與「自訂電子郵件處理常式」一節所述的網頁流程類似。

處理電子郵件驗證等電子郵件動作時，需要從深層連結剖析 oobCode 查詢參數中的動作代碼，然後透過 applyActionCode 套用，變更才會生效 (即驗證電子郵件)。