在 Android 上建立 Dynamic Links

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

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

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

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

    註冊應用程式時，請指定 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:33.6.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:22.1.2'
}
    想找 Kotlin 專屬的程式庫模組嗎？自 2023 年 10 月 (Firebase BoM 32.5.0)起，Kotlin 和 Java 開發人員都可以依附主要程式庫模組 (詳情請參閱這項計畫的常見問題)。
  3. 在 Firebase 主控台中，開啟「Dynamic Links」專區。

  4. 如果您尚未接受服務條款，並為 Dynamic Links 設定網域，請在系統提示時完成這些步驟。

    如果您已經有 Dynamic Links 網域，請記下網域名稱。您必須透過程式碼建立 Dynamic Links 時提供 Dynamic Links 網域。

  5. 建議：指定深層連結和備用連結中允許的網址模式。這樣一來，您就能防止未經授權的對象建立 Dynamic Links，從您的網域重新導向至您無法控管的網站。請參閱「允許特定網址模式」。

使用 Firebase 主控台

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

如要建立 Dynamic Link，請使用建構工具建立新的 DynamicLink 物件，並使用建構工具方法指定 Dynamic Link 參數。接著，呼叫 buildDynamicLink 或 buildShortDynamicLink。

以下簡單範例會建立長 Dynamic Link 至 https://www.example.com/，在 Android 上透過 Android 應用程式和 iOS 上的應用程式 com.example.ios 開啟：

Kotlin+KTX

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+KTX

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 Links，因此使用者幾乎不可能猜到有效的 Dynamic Link。如果在您的用例中，有人成功猜出短網址並無妨，您可能會偏好產生只在必要時才會是唯一的後置字串，方法是將 ShortDynamicLink.Suffix.SHORT 傳遞至 buildShortDynamicLink 方法：

Kotlin+KTX

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 Builder API 搭配任何支援的參數建立 Dynamic Links。詳情請參閱 API 參考資料。

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

Kotlin+KTX

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 參數：

DynamicLink 參數
setLink

應用程式會開啟的連結。指定應用程式可處理的網址，通常是應用程式內容或酬載，可啟動應用程式專屬邏輯 (例如使用優待券為使用者提供抵用額或顯示歡迎畫面)。這個連結必須是格式正確的網址、使用正確的網址編碼、使用 HTTP 或 HTTPS，且不得是另一個動態連結。
setDomainUriPrefix Dynamic Link 網址前置字元，您可以在 Firebase 控制台中找到。Dynamic Link 網域如下所示： 
https://example.com/link
https://example.page.link
AndroidParameters
setFallbackUrl 未安裝應用程式時要開啟的連結。指定這個值，即可在未安裝應用程式時，執行其他操作 (例如開啟內容的行動版網頁版本，或顯示應用程式宣傳頁面)，而非從 Play 商店安裝應用程式。
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 Links 的應用程式中開啟 Dynamic Link，可以使用這個參數停用該頁面。這個參數只會影響 iOS 版 Dynamic Link 的行為。
SocialMetaTagParameters
setTitle 在社群媒體貼文中分享 Dynamic Link 時使用的標題。
setDescription 在社群媒體貼文中分享 Dynamic Link 時使用的說明。
setImageUrl 與此連結相關的圖片網址。圖片尺寸不得小於 300 x 200 像素，且大小不得超過 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，請使用 setLongLink 指定 Dynamic Link 的網址，而非使用其他建構工具方法設定參數：

Kotlin+KTX

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