在 Android 上建立 Dynamic Links

你可以透過 Firebase Dynamic Links Builder API 建立簡短或長的 Dynamic Links。這個 API 可接受長篇動態連結或包含 Dynamic Link 參數的物件，並傳回類似以下範例的網址：

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

您必須先加入 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 動態連結程式庫的依附元件。建議您使用 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.1.1"))

    // 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 程式庫版本。

    (替代方法) 新增 Firebase 程式庫依附元件，「不必」使用 BoM

    如果選擇不使用 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.0.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 Links 以便進行測試，或是讓行銷團隊輕鬆建立可用於社群媒體貼文等內容的連結，最簡單的方法就是前往 Firebase 控制台，然後按照逐步表單手動建立連結。

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

以下最小範例會建立指向 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 Links，請以相同方式建構 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。如果您的用途並無任何危害，即使成功猜出短連結也無妨，那麼您可能會想要產生只在需要時才產生唯一的後置字串，只要將 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 參考資料。

以下範例會建立含有數個常見參數集的動態連結：

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

您可以使用下列方法設定動態連結參數：

DynamicLink 參數
setLink

應用程式會開啟的連結。指定應用程式可處理的網址 (通常是應用程式的內容或酬載)，它會啟動應用程式專屬的邏輯 (例如將優待券存入使用者，或顯示歡迎畫面)。這個連結必須是格式正確的網址、必須採用正確的網址編碼方式、使用 HTTP 或 HTTPS，而且不能是其他 Dynamic Links。
setDomainUriPrefix 您的動態連結網址前置字串，您可以在 Firebase 控制台中找到這個前置字串。Dynamic Link 網域範例如下： 
https://example.com/link
https://example.page.link
Android 參數
setFallbackUrl 未安裝應用程式時開啟的連結。指定應用程式非安裝應用程式時，可透過 Play 商店進行以外的操作 (例如開啟行動版網站的內容，或顯示應用程式的宣傳頁面)。
setMinimumVersion 可開啟連結的應用程式最低版本 versionCode。如果安裝的應用程式是較舊的版本，系統會將使用者導向 Play 商店，以便升級應用程式。
IosParameters
setAppStoreId 應用程式的 App Store ID，用來在未安裝應用程式的情況下將使用者導向 App Store
setFallbackUrl 未安裝應用程式時開啟的連結。指定應用程式非安裝應用程式時，可透過 App Store 以外的方式進行安裝 (例如開啟行動版網站的內容，或顯示應用程式的宣傳頁面)。
setCustomScheme 應用程式的自訂網址通訊協定 (如果定義不是應用程式的軟體包 ID)
setIpadFallbackUrl 未安裝應用程式時，在 iPad 上開啟的連結。指定非安裝應用程式時，可透過 App Store 安裝以外的其他操作 (例如開啟網頁版內容，或顯示應用程式的宣傳頁面)。
setIpadBundleId 這是在 iPad 上用來開啟連結的 iOS 應用程式軟體包 ID。應用程式必須從 Firebase 控制台的「總覽」頁面連結至專案。
setMinimumVersion 可開啟連結的應用程式最低版本號碼。此標記會在應用程式開啟時傳遞至您的應用程式，而您的應用程式必須決定如何處理此標記。
NavigationInfoParameters
setForcedRedirectEnabled 設定 如果設為「1」，系統會在動態連結開啟時略過應用程式預覽頁面，改為重新導向至應用程式或商店。當使用者在應用程式中開啟 Dynamic Links 時，應用程式預覽頁面 (預設為啟用) 可更穩定地將使用者傳送至最合適的目的地。不過，如果您想讓 Dynamic Links 只在可穩定開啟 Dynamic Links 的應用程式中開啟，可以使用這項參數停用該頁面。這個參數將影響 Dynamic Links 在 iOS 上的行為。
社交中繼代碼參數
設定標題 在社群媒體貼文中分享動態連結時使用的標題。
setDescription 在社群媒體貼文中分享動態連結時要使用的說明。
setImageUrl 與這個連結相關的圖片網址。此圖片應至少為 300x200 像素，且小於 300 KB。
GoogleAnalytics (分析) 參數
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。

如要縮短長動態連結，請使用 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