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

在傳送密碼重設電子郵件操作或驗證使用者電子郵件時,您可以透過繼續 URL 傳遞狀態。這使用戶能夠在操作完成後返回應用程式。此外,您可以指定在安裝行動應用程式(而不是網頁)時是否直接從行動應用程式處理電子郵件操作連結。

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

  • 目前未登入的使用者可能正在嘗試存取需要使用者登入的內容。但是,使用者可能忘記了密碼,因此觸發重設密碼流程。在流程結束時,使用者希望返回到他們嘗試存取的應用程式部分。

  • 應用程式可能只提供對經過驗證的帳戶的存取。例如,時事通訊可能要求使用者在訂閱之前驗證其電子郵件。用戶將完成電子郵件驗證流程,並期望返回應用程式以完成訂閱。

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

透過連續 URL 傳遞狀態的能力是 Firebase Auth 提供的一項強大功能,可顯著增強使用者體驗。

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

為了安全地傳遞繼續 URL,該 URL 的網域需要在Firebase 控制台中列入白名單。這是在「驗證」部分中完成的,方法是將此網域新增至「登入方法」標籤下的「授權網域」清單中(如果尚不存在)。

發送密碼重設郵件或驗證郵件時需要提供ActionCodeSettings實例。它可以使用關聯的ActionCodeSettings.Builder類別來創建,該類別包含以下方法:

方法描述
setUrl(String url)

設定在不同上下文中具有不同含義的連結(狀態/繼續 URL):

  • 當在 Web 操作小部件中處理連結時,這是continueUrl查詢參數中的深層連結。
  • 當直接在應用程式中處理連結時,這是動態連結深層連結中的continueUrl查詢參數。
setIOSBundleId(String iOSBundleId)設定 iOS 捆綁包 ID。如果已安裝,這將嘗試在 iOS 應用程式中開啟該連結。 iOS 應用程式需要在控制台中註冊。
setAndroidPackageName(String androidPackageName, boolean installIfNotAvailable, String minimumVersion)設定 Android 套件名稱。如果已安裝,這將嘗試在 Android 應用程式中開啟連結。如果 installIfNotAvailable 設定為true ,則指定在裝置支援且尚未安裝應用程式的情況下是否已安裝 Android 應用程式。如果指定了minimumVersion,並且安裝了舊版本的應用程序,用戶將被帶到Play 商店升級應用程式。 Android 應用程式需要在控制台中註冊。
setHandleCodeInApp(boolean status)電子郵件操作連結是先在行動應用程式中打開,還是先在網頁連結中開啟。預設為 false。當設定為 true 時,操作代碼連結將作為通用連結或 Android 應用程式連結發送,並由應用程式(如果已安裝)開啟。在錯誤的情況下,程式碼將首先發送到網路小部件,然後繼續將重定向到應用程式(如果已安裝)。
setDynamicLinkDomain(String dynamicLinkDomain)如果要使用 Firebase 動態連結開啟目前鏈接,則設定要用於目前連結的動態連結網域(或子網域)。由於每個項目可以配置多個動態連結域,因此該欄位提供了明確選擇一個動態連結域的能力。如果未提供,則預設使用第一個網域。

以下範例說明如何發送電子郵件驗證鏈接,該鏈接將首先在移動應用程式中作為 Firebase 動態鏈接(iOS 應用程式com.example.ios或 Android 應用程式com.example.android )打開。深層連結將包含繼續 URL 負載https://www.example.com/?email=user@example.com

Kotlin+KTX

val auth = Firebase.auth
val user = auth.currentUser!!

val url = "http://www.example.com/verify?uid=" + user.uid
val actionCodeSettings = ActionCodeSettings.newBuilder()
    .setUrl(url)
    .setIOSBundleId("com.example.ios")
    // The default for this is populated with the current android package name.
    .setAndroidPackageName("com.example.android", false, null)
    .build()

user.sendEmailVerification(actionCodeSettings)
    .addOnCompleteListener { task ->
        if (task.isSuccessful) {
            Log.d(TAG, "Email sent.")
        }
    }

Java

FirebaseAuth auth = FirebaseAuth.getInstance();
FirebaseUser user = auth.getCurrentUser();

String url = "http://www.example.com/verify?uid=" + user.getUid();
ActionCodeSettings actionCodeSettings = ActionCodeSettings.newBuilder()
        .setUrl(url)
        .setIOSBundleId("com.example.ios")
        // The default for this is populated with the current android package name.
        .setAndroidPackageName("com.example.android", false, null)
        .build();

user.sendEmailVerification(actionCodeSettings)
        .addOnCompleteListener(new OnCompleteListener<Void>() {
            @Override
            public void onComplete(@NonNull Task<Void> task) {
                if (task.isSuccessful()) {
                    Log.d(TAG, "Email sent.");
                }
            }
        });

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 應用程式的操作程式碼鏈接,然後在成功完成後重定向到另一個網頁或行動應用程式(前提是行動應用程式可用)。這是透過在ActionCodeSettings.Builder物件中呼叫setHandleCodeInApp(false)來完成的。雖然不需要 iOS 捆綁包 ID 或 Android 包名稱,但提供它們將允許用戶在電子郵件操作代碼完成時重定向回指定的應用程式。

此處使用的 Web URL 是在電子郵件操作範本部分中配置的 URL。為所有項目配置了預設的一個。請參閱自訂電子郵件處理程序以了解有關如何自訂電子郵件操作處理程序的詳細資訊。

在這種情況下, continueUrl查詢參數中的連結將是 FDL 鏈接,其負載是ActionCodeSettings物件中指定的URL 。雖然您可以攔截和處理來自應用程式的傳入連結而無需任何額外的依賴項,但我們建議您使用 FDL 用戶端程式庫來解析深層連結。

在處理電子郵件驗證等電子郵件操作時,需要從深層連結解析oobCode查詢參數中的操作程式碼,然後透過applyActionCode以使變更生效,即驗證電子郵件。

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

您可以指定是否要先處理行動應用程式中的操作程式碼連結(如果已安裝)。對於 Android 應用程序,您還可以透過installIfNotAvailable布林值指定如果裝置支援且尚未安裝該應用程序,則要安裝該應用程式。如果從不支援行動應用程式的裝置點擊鏈接,則會從網頁開啟該連結。這是透過在ActionCodeSettings.Builder物件中呼叫setHandleCodeInApp(true)來完成的。還需要指定行動應用程式的 Android 套件名稱或 iOS 套件 ID。

當沒有可用的行動應用程式時,此處使用的後備 Web URL 是在電子郵件操作範本部分中配置的 URL。為所有項目配置了預設的一個。請參閱自訂電子郵件處理程序以了解有關如何自訂電子郵件操作處理程序的詳細資訊。

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

在處理電子郵件驗證等電子郵件操作時,需要從深層連結解析oobCode查詢參數中的操作程式碼,然後透過applyActionCode以使變更生效,即驗證電子郵件。