電子郵件動作中的狀態

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

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

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

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

  • 一般來說，使用者在 Apple 應用程式中開始密碼重設或電子郵件驗證流程時，會希望在應用程式內完成流程；透過繼續網址傳遞狀態的功能可實現這項需求。

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

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

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

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

Swift

參數 類型 說明
URL 字串

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

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

Objective-C

參數 類型 說明
URL NSString

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

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

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

Swift

var actionCodeSettings =  ActionCodeSettings.init()
actionCodeSettings.canHandleInApp = true
let user = Auth.auth().currentUser()
actionCodeSettings.URL =
    String(format: "https://www.example.com/?email=%@", user.email)
actionCodeSettings.iOSbundleID = Bundle.main.bundleIdentifier!
actionCodeSettings.setAndroidPakageName("com.example.android")
// Specify a custom Hosting link domain to use. The domain must be
// configured in Firebase Hosting and owned by the project.
actionCodeSettings.linkDomain = "custom-domain.com"
user.sendEmailVerification(withActionCodeSettings:actionCodeSettings { error in
  if error {
    // Error occurred. Inspect error.code and handle error.
    return
  }
  // Email verification sent.
})

Objective-C

 FIRActionCodeSettings *actionCodeSettings = [[FIRActionCodeSettings alloc] init];
 actionCodeSettings.handleCodeInApp = YES;
 FIRUser *user = [FIRAuth auth].currentUser;
 NSString *urlString =
     [NSString stringWithFormat:@"https://www.example.com/?email=%@", user.email];
 actionCodeSettings.URL = [NSURL URLWithString:urlString];
 actionCodeSettings.iOSBundleID = [NSBundle mainBundle].bundleIdentifier;
// Specify a custom Hosting link domain to use. The domain must be
// configured in Firebase Hosting and owned by the project.
 actionCodeSettings.linkDomain = @"custom-domain.com";
 [actionCodeSettings setAndroidPackageName:@"com.example.android"];
 [user sendEmailVerificationWithActionCodeSettings:actionCodeSettings
                                        completion:^(NSError *_Nullable error) {
   if (error) {
     // Error occurred. Inspect error.code and handle error.
     return;
   }
   // Email verification sent.
 }];

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

  1. 設定 Apple 應用程式：

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

  2. 設定 Android 應用程式：

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

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

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

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

在本例中，continueURL 查詢參數中的連結會是 Hosting 連結，其酬載是 ActionCodeSettings 物件中指定的 URL。

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

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

您可以指定是否要先在行動應用程式中處理動作代碼連結 (如果已安裝)。如果使用者從不支援行動應用程式的裝置點選連結，系統會改為開啟網頁。方法是在 FIRActionCodeSettings (Obj-C) 或 ActionCodeSettings (Swift) 物件中，將 handleCodeInApp 設為 true。您也需要指定行動應用程式的 Android 套件名稱或軟體包 ID。如果沒有可用的行動應用程式，系統會使用電子郵件動作範本部分中設定的備用網頁網址。系統會為所有專案佈建預設專案。如要進一步瞭解如何自訂電子郵件動作處理常式，請參閱自訂電子郵件處理常式。

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

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