電子郵件動作中的狀態

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

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

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

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

  • 一般來說，當使用者在 Apple 應用程式中開始密碼重設或電子郵件驗證流程時，他們會預期在應用程式內完成流程；透過繼續網址傳遞狀態的功能可讓這項作業順利進行。

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

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

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

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

參數 類型 說明
url 字串

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

  • 如果連結是在網頁動作小工具中處理，則是 continueUrl 查詢參數中的深層連結。
  • 如果連結是直接在應用程式中處理，則這是動態連結深層連結中的 continueUrl 查詢參數。
iOSBundleId 字串 設定軟體包 ID。系統會嘗試在已安裝的 Apple 應用程式中開啟連結。應用程式必須在管理中心註冊。如果未提供軟體包 ID，這個欄位的值會設為應用程式主軟體包的軟體包 ID。
androidPackageName 字串 設定 Android 套件名稱。系統會嘗試在已安裝的 Android 應用程式中開啟連結。
androidInstallApp bool 指定裝置支援 Android 應用程式，且尚未安裝該應用程式時，是否要安裝該應用程式。如果您在提供這個欄位時未提供 packageName，系統會擲回錯誤，說明必��與這個欄位一併提供 packageName。
androidMinimumVersion 字串 這個流程中支援的應用程式最低版本。如果指定 minimumVersion，且安裝的是舊版應用程式，使用者會被帶往 Play 商店升級應用程式。Android 應用程式必須在管理中心註冊。
handleCodeInApp bool 電子郵件動作連結是否會先在行動應用程式或網頁連結中開啟。預設值為 false。如果設為 True，系統會以通用連結或 Android 應用程式連結傳送動作碼連結，並在應用程式安裝後由應用程式開啟。在 false 的情況下，系統會先將程式碼傳送至網頁小工具，然後在繼續時將重新導向至已安裝的應用程式。
dynamicLinkDomain 字串 (已淘汰，請改用 `linkDomain`) 設定要用於目前連結的動態連結網域 (或子網域)，如果要使用 Firebase Dynamic Links 開啟連結。每個專案可設定多個動態連結網域，因此這個欄位可讓您明確選擇其中一個網域。如果未提供任何網域，系統會預設使用第一個網域。 linkDomain 字串 當您透過指定的行動應用程式開啟連結時，可選用自訂 Firebase 託管網域。網域必須在 Firebase 託管中設定，且由專案擁有。這項設定不得為預設託管網域 (`web.app` 或 `firebaseapp.com`)。這項設定會取代已淘汰的 `dynamicLinkDomain` 設定。

以下範例說明如何傳送電子郵件驗證連結，該連結會先在行動應用程式中以 Firebase 動態連結的形式開啟，並使用自訂動態連結網域 example.page.link (iOS 應用程式 com.example.ios 或 Android 應用程式 com.example.android，如果應用程式尚未安裝，則會安裝，且最低版本為 12)。深層連結會包含繼續網址酬載 https://www.example.com/?email=user@example.com。

final user = FirebaseAuth.instance.currentUser;

final actionCodeSettings = ActionCodeSettings(
  url: "http://www.example.com/verify?email=${user?.email}",
  iOSBundleId: "com.example.ios",
  androidPackageName: "com.example.android",
);

await user?.sendEmailVerification(actionCodeSettings);

Firebase 驗證會在傳送要在行動應用程式中開啟的連結時，使用 Firebase 動態連結。如要使用這項功能，您必須在 Firebase 控制台中設定動態連結。

  1. 啟用 Firebase Dynamic Links：

    1. 在 Firebase 控制台中，開啟「動態連結」部分。

    2. 如果您尚未接受 Dynamic Links 條款並建立 Dynamic Links 網域，請立即完成這些步驟。

    3. 如果您已建立動態連結網域，請記下該網域。動態連結網域通常如下所示：

      example.page.link

    4. 您需要這個值才能設定 Apple 或 Android 應用程式，以攔截傳入的連結。

  2. 設定 Android 應用程式：

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

  3. 設定 Apple 應用程式：

    1. 如果您打算透過應用程式處理這些連結，請在 Firebase 控制台專案設定中指定套件 ID。此外，您還必須指定 App Store ID 和 Apple 開發人員團隊 ID。
    2. 您也需要將 FDL 通用連結網域設為應用程式功能中的關聯網域。
    3. 如果您打算將應用程式發���至 iOS 8 以下版本，就必須將軟體包 ID 設為傳入網址的自訂配置。
    4. 如需進一步瞭解，請參閱「接收 Apple 平台 Dynamic Links 指示」。

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

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

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

在這種情況下，continueURL 查詢參數中的連結會是 FDL 連結，其酬載為 ActionCodeSettings 物件中指定的 URL。雖然您可以攔截並處理來自應用程式的傳入連結，而無需任何額外依附元件，但我們建議您使用 FDL 用戶端程式庫，為您剖析深層連結。

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

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

您可以指定是否要在行動應用程式中先處理動作碼連結 (如果已安裝)。對於 Android 應用程式，您也可以透過 androidInstallApp 指定應用程式安裝作業，前提是裝置支援該應用程式且尚未安裝。如果使用者從不支援行動應用程式的裝置點選連結，系統會改為透過網頁開啟連結。方法是將 handleCodeInApp 設為 true 物件中的 true。ActionCodeSettings您也必須指定行動應用程式的 Android 套件名稱或套件 ID。如果沒有可用的行動應用程式，這裡使用的備用網頁網址就是在電子郵件動作範本部分中設定的網址。系統會為所有專案提供預設的專案。如要進一步瞭解如何自訂電子郵件動作處理常式，請參閱「自訂電子郵件處理常式」。

在這種情況下，傳送給使用者的行動應用程式連結會是 FDL 連結，其酬載為在主控台中設定的動作碼網址，以及查詢參數 oobCode、mode、apiKey 和 continueUrl。後者是 ActionCodeSettings 物件中指定的原始 URL。雖然您可以攔截並處理來自應用程式的傳入連結，而無需任何額外依附元件，但我們建議您使用 FDL 用戶端程式庫來剖析深層連結。行動應用程式可以直接套用動作代碼，類似於自訂電子郵件處理程序一節所述的網頁流程處理方式。

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