在 Android 上建立 Dynamic Links

已淘汰： Firebase Dynamic Links 已淘汰，因此不應在尚未採用這項功能的專案中使用。 這項服務將於 2025 年 8 月 25 日終止。 詳情請參閱「動態連結淘汰常見問題」。

您可以使用 Firebase Dynamic Links Builder API 建立短片或長片 Dynamic Links。這項 API 接受長 Dynamic Link 或含有 Dynamic Link 參數的物件，並傳回類似下列範例的網址：

https://example.com/link/WXYZ
https://example.page.link/WXYZ

設定 Firebase 和 Dynamic Links SDK

您必須先加入 Firebase SDK，才能在 Android 應用程式中建立 Dynamic Links。如果應用程式已設定為接收 Dynamic Links，您已完成這些步驟，可以略過本節。

1. 如果您尚未將 Firebase 新增至 Android 專案，請先新增。

   註冊應用程式時，請指定 SHA-1 簽署金鑰。如果您使用應用程式連結，也請指定 SHA-256 金鑰。

2. 在模組 (應用程式層級) Gradle 檔案 (通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle) 中，加入 Android 適用的 Dynamic Links 程式庫依附元件。建議使用 Firebase Android BoM 控制程式庫版本。

   為獲得最佳 Dynamic Links 體驗，建議您在 Firebase 專案中啟用 Google Analytics，並在應用程式中加入 Google Analytics 專用 Firebase SDK。

   dependencies {
       // Import the BoM for the Firebase platform
       implementation(platform("com.google.firebase:firebase-bom:34.0.0"))
   
       // Add the dependencies for the Dynamic Links and Analytics libraries
       // When using the BoM, you don't specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-dynamic-links'
       implementation 'com.google.firebase:firebase-analytics'
   }

   只要使用 Firebase Android BoM，應用程式就會一律使用相容的 Firebase Android 程式庫版本。

   (替代做法)  不使用 BoM 新增 Firebase 程式庫依附元件

   如果選擇不使用 Firebase BoM，則必須在依附元件行中指定每個 Firebase 程式庫版本。

   請注意，如果應用程式使用多個 Firebase 程式庫，強烈建議使用 BoM 管理程式庫版本，確保所有版本都相容。

   dependencies {
       // Add the dependencies for the Dynamic Links and Analytics libraries
       // When NOT using the BoM, you must specify versions in Firebase library dependencies
       implementation 'com.google.firebase:firebase-dynamic-links:22.1.0'
       implementation 'com.google.firebase:firebase-analytics:23.0.0'
   }

3. 在 Firebase 控制台中，開啟 Dynamic Links 專區。

4. 如果尚未接受服務條款及為 Dynamic Links 設定網域，請按照提示操作。

   如果您已有 Dynamic Links 網域，請記下該網域。以程式輔助方式建立 Dynamic Links 時，您需要提供 Dynamic Links 網域。

   

5. 建議：指定可在深層連結和備用連結中使用的網址模式。這麼做可防止未經授權的第三方建立 Dynamic Links，從您的網域重新導向至您無法控制的網站。請參閱「允許特定網址模式」。

使用 Firebase 控制台

如要產生單一 Dynamic Link，無論是為了測試，或是讓行銷團隊輕鬆建立連結，以便用於社群媒體貼文等內容，最簡單的方法就是前往 Firebase 控制台，然後按照逐步表單手動建立。

使用參數建立 Dynamic Link

如要建立 Dynamic Link，請使用 Builder 建立新的 DynamicLink 物件，並使用 Builder 方法指定 Dynamic Link 參數。然後呼叫 buildDynamicLink 或 buildShortDynamicLink。

以下是簡短範例，可建立長 Dynamic Link，在 Android 上透過 Android 應用程式開啟，在 iOS 上則透過 com.example.ios 應用程式開啟：https://www.example.com/

Kotlin

val dynamicLink = Firebase.dynamicLinks.dynamicLink {
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    // Open links with this app on Android
    androidParameters { }
    // Open links with com.example.ios on iOS
    iosParameters("com.example.ios") { }
}

val dynamicLinkUri = dynamicLink.uri
MainActivity.kt

Java

DynamicLink dynamicLink = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        // Open links with this app on Android
        .setAndroidParameters(new DynamicLink.AndroidParameters.Builder().build())
        // Open links with com.example.ios on iOS
        .setIosParameters(new DynamicLink.IosParameters.Builder("com.example.ios").build())
        .buildDynamicLink();

Uri dynamicLinkUri = dynamicLink.getUri();
MainActivity.java

如要建立簡短的 Dynamic Link，請以相同方式建構 DynamicLink，然後呼叫 buildShortDynamicLink。建立短連結需要進行網路呼叫，因此 buildShortDynamicLink 會傳回 Task，而不是直接傳回連結。要求完成後，系統就會提供短連結。例如：

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync {
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    // Set parameters
    // ...
}.addOnSuccessListener { (shortLink, flowchartLink) ->
    // You'll need to import com.google.firebase.dynamiclinks.component1 and
    // com.google.firebase.dynamiclinks.component2

    // Short link created
    processShortLink(shortLink, flowchartLink)
}.addOnFailureListener {
    // Error
    // ...
}
MainActivity.kt

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        // Set parameters
        // ...
        .buildShortDynamicLink()
        .addOnCompleteListener(this, new OnCompleteListener<ShortDynamicLink>() {
            @Override
            public void onComplete(@NonNull Task<ShortDynamicLink> task) {
                if (task.isSuccessful()) {
                    // Short link created
                    Uri shortLink = task.getResult().getShortLink();
                    Uri flowchartLink = task.getResult().getPreviewLink();
                } else {
                    // Error
                    // ...
                }
            }
        });
MainActivity.java

根據預設，系統會產生 17 個字元的連結後置字串，因此使用者極不可能猜到有效的 Dynamic Link。Dynamic Links如果您的用例允許使用者猜出短連結，您可能會偏好產生長度足以確保連結獨一無二的後置字串，方法是將 ShortDynamicLink.Suffix.SHORT 傳遞至 buildShortDynamicLink 方法：

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync(ShortDynamicLink.Suffix.SHORT) {
    // Set parameters
    // ...
}
MainActivity.kt

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        // ...
        .buildShortDynamicLink(ShortDynamicLink.Suffix.SHORT);
        // ...
MainActivity.java

Dynamic Link 個參數

您可以使用 Dynamic Link Builder API，透過任何支援的參數建立 Dynamic Links。詳情請參閱 API 參考資料。

以下範例會建立 Dynamic Link，並設定幾個常見參數：

Kotlin

val dynamicLink = Firebase.dynamicLinks.dynamicLink { // or Firebase.dynamicLinks.shortLinkAsync
    link = Uri.parse("https://www.example.com/")
    domainUriPrefix = "https://example.page.link"
    androidParameters("com.example.android") {
        minimumVersion = 125
    }
    iosParameters("com.example.ios") {
        appStoreId = "123456789"
        minimumVersion = "1.0.1"
    }
    googleAnalyticsParameters {
        source = "orkut"
        medium = "social"
        campaign = "example-promo"
    }
    itunesConnectAnalyticsParameters {
        providerToken = "123456"
        campaignToken = "example-promo"
    }
    socialMetaTagParameters {
        title = "Example of a Dynamic Link"
        description = "This link works whether the app is installed or not!"
    }
}
MainActivity.kt

Java

DynamicLink dynamicLink = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLink(Uri.parse("https://www.example.com/"))
        .setDomainUriPrefix("https://example.page.link")
        .setAndroidParameters(
                new DynamicLink.AndroidParameters.Builder("com.example.android")
                        .setMinimumVersion(125)
                        .build())
        .setIosParameters(
                new DynamicLink.IosParameters.Builder("com.example.ios")
                        .setAppStoreId("123456789")
                        .setMinimumVersion("1.0.1")
                        .build())
        .setGoogleAnalyticsParameters(
                new DynamicLink.GoogleAnalyticsParameters.Builder()
                        .setSource("orkut")
                        .setMedium("social")
                        .setCampaign("example-promo")
                        .build())
        .setItunesConnectAnalyticsParameters(
                new DynamicLink.ItunesConnectAnalyticsParameters.Builder()
                        .setProviderToken("123456")
                        .setCampaignToken("example-promo")
                        .build())
        .setSocialMetaTagParameters(
                new DynamicLink.SocialMetaTagParameters.Builder()
                        .setTitle("Example of a Dynamic Link")
                        .setDescription("This link works whether the app is installed or not!")
                        .build())
        .buildDynamicLink();  // Or buildShortDynamicLink()
MainActivity.java

您可以透過下列方法設定 Dynamic Link 參數：

Dynamic Link 參數
setLink	應用程式將開啟的連結。指定應用程式可處理的網址，通常是應用程式的內容或酬載，可啟動應用程式專屬的邏輯 (例如將優待券發給使用者，或顯示歡迎畫面)。這個連結必須是格式正確的網址、經過適當的網址編碼、使用 HTTP 或 HTTPS，且不得為其他動態連結。 使用者在電腦網頁瀏覽器中開啟 Dynamic Link 時，系統會載入這個網址 (除非指定 ofl 參數)。如果連結內容沒有對應的網頁，網址就不必指向有效的網路資源。在這種情況下，您應設定從這個網址重新導向至首頁等網頁。
setDomainUriPrefix	您的 Dynamic Link 網址前置字元，您可以在 Firebase 控制台中找到。A Dynamic Link 網域看起來會像下列範例： https://example.com/link https://example.page.link

AndroidParameters
setFallbackUrl	應用程式未安裝時要開啟的連結。如果應用程式尚未安裝，您可以指定此動作，以便執行安裝應用程式以外的動作，例如開啟內容的行動版網頁，或顯示應用程式的宣傳頁面。
setMinimumVersion	可開啟連結的應用程式最低版本versionCode。如果安裝的應用程式版本較舊，系統會將使用者帶往 Play 商店升級應用程式。

IosParameters
setAppStoreId	應用程式的 App Store ID，用於在應用程式未安裝時將使用者導向 App Store
setFallbackUrl	應用程式未安裝時要開啟的連結。如果應用程式尚未安裝，您可以指定此動作，以便執行安裝以外的作業，例如開啟內容的行動版網頁，或顯示應用程式的宣傳頁面。
setCustomScheme	應用程式的自訂網址通訊協定 (如果定義為應用程式軟體包 ID 以外的項目)
setIpadFallbackUrl	如果未安裝應用程式，則在 iPad 上開啟的連結。如果應用程式未安裝，請指定此項目，以便執行從 App Store 安裝應用程式以外的動作，例如開啟內容的網頁版，或顯示應用程式的宣傳頁面。
setIpadBundleId	在 iPad 上開啟連結時使用的 iOS 應用程式套件 ID。應用程式必須從 Firebase 控制台的「總覽」頁面連結至專案。
setMinimumVersion	可開啟連結的應用程式最低版本編號。這個標記會在應用程式開啟時傳遞至應用程式，而應用程式必須決定如何處理。

NavigationInfoParameters
setForcedRedirectEnabled	如果設為「1」，開啟 Dynamic Link 時會略過應用程式預覽頁面，並改為重新導向至應用程式或商店。應用程式預覽頁面 (預設為啟用) 可在使用者開啟應用程式中的 Dynamic Links 時，更可靠地將他們導向最合適的目的地。不過，如果您希望 Dynamic Link 只在可穩定開啟 Dynamic Links 的應用程式中開啟，且不需要這個頁面，可以使用這個參數停用預覽頁面。這個參數只會影響 iOS 上的 Dynamic Link 行為。

SocialMetaTagParameters
setTitle	在社群貼文中分享 Dynamic Link 時使用的標題。
setDescription	在社群媒體貼文中分享 Dynamic Link 時使用的說明。
setImageUrl	與這個連結相關的圖片網址。圖片尺寸至少須為 300x200 像素，且小於 300 KB。

GoogleAnalyticsParameters
setSource setMedium setCampaign setTerm setContent	Google Play 數據分析參數。這些參數 (utm_source、utm_medium、utm_campaign、utm_term、utm_content) 會傳遞至 Play 商店，並附加至連結酬載。

ItunesConnectAnalyticsParameters
setProviderToken setAffiliateToken setCampaignToken	iTunes Connect 數據分析參數。這些參數 (pt、 at、ct) 會傳遞至 App Store。

縮短長 Dynamic Link

如要縮短較長的 Dynamic Link，請使用 setLongLink 指定 Dynamic Link 的網址，而非使用其他建構工具方法設定參數：

Kotlin

val shortLinkTask = Firebase.dynamicLinks.shortLinkAsync {
    longLink = Uri.parse(
        "https://example.page.link/?link=" +
            "https://www.example.com/&apn=com.example.android&ibn=com.example.ios",
    )
}.addOnSuccessListener { (shortLink, flowChartLink) ->
    // You'll need to import com.google.firebase.dynamiclinks.component1 and
    // com.google.firebase.dynamiclinks.component2

    // Short link created
    processShortLink(shortLink, flowChartLink)
}.addOnFailureListener {
    // Error
    // ...
}
MainActivity.kt

Java

Task<ShortDynamicLink> shortLinkTask = FirebaseDynamicLinks.getInstance().createDynamicLink()
        .setLongLink(Uri.parse("https://example.page.link/?link=https://www.example.com/&apn=com.example.android&ibn=com.example.ios"))
        .buildShortDynamicLink()
        .addOnCompleteListener(this, new OnCompleteListener<ShortDynamicLink>() {
            @Override
            public void onComplete(@NonNull Task<ShortDynamicLink> task) {
                if (task.isSuccessful()) {
                    // Short link created
                    Uri shortLink = task.getResult().getShortLink();
                    Uri flowchartLink = task.getResult().getPreviewLink();
                } else {
                    // Error
                    // ...
                }
            }
        });
MainActivity.java