電子郵件動作中的狀態

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

這在下列常見情境中非常實用：

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

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

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

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

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

為確保安全地傳送繼續網址，您必須在 Firebase 控制台中，將網址的網域新增為授權網域。如要完成這項操作，請前往「Authentication」部分，將這個網域新增至「Sign-in method」分頁下方的「Authorized domains」清單中 (如果尚未加入)。

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

參數 類型 說明
url 字串

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

  • 如果連結是在網頁動作小工具中處理，則是 continueUrl 查詢參數中的深層連結。
  • 如果連結是直接在應用程式中處理，則這是 Hosting 連結深層連結中的 continueUrl 查詢參數。
iOS ({bundleId: string}|undefined) 設定 iOS 軟體包 ID，協助 Firebase Authentication 判斷是否應建立在 Apple 裝置上開啟的網頁專屬或行動連結
android ({packageName: string, installApp:boolean|undefined, minimumVersion: string|undefined}|undefined) 設定 Android 套件名稱，協助 Firebase Authentication 判斷是否應建立在 Android 裝置上開啟的僅限網頁或行動連結
handleCodeInApp (布林值|未定義) 電子郵件動作連結是否會先在行動應用程式或網頁連結中開啟。預設值為 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 代管連結指南」。

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

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

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

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

處理電子郵件驗證等電子郵件動作時，需要從深層連結解析 oobCode 查詢參數的動作代碼，然後透過 applyActionCode 套用變更，才能生效，也就是驗證電子郵件。

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

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

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

在這種情況下，傳送給使用者的行動應用程式連結會是 Hosting 連結，其酬載是使用控制台中設定的動作碼網址，以及查詢參數 oobCode、mode、apiKey 和 continueUrl。後者是 ActionCodeSettings 物件中指定的原始 URL。行動應用程式可以直接套用動作代碼，類似於自訂電子郵件處理程序一節所述的網頁流程處理方式。

處理電子郵件驗證等電子郵件動作時，需要從深層連結解析 oobCode 查詢參數的動作代碼，然後透過 applyActionCode 套用變更，才能生效，也就是驗證電子郵件。