在 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 專案，請先新增。

    註冊應用程式時，請指定 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:35.0.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 程式庫版本。

    (替代方案)  不使用 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:24.0.0'
}
  3. 在 Firebase 控制台中，開啟 Dynamic Links部分。

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

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

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

使用 Firebase 控制台

如要產生單一 Dynamic Link (用於測試，或方便行銷團隊建立連結，用於社群媒體貼文等)，最簡單的方法是前往 Firebase 控制台，按照逐步表單手動建立。

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

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

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

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();

如要建立短 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
    // ...
}

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
                    // ...
                }
            }
        });

根據預設，系統會產生 17 個字元的連結後置字串Dynamic Links，因此幾乎不可能猜出有效的 Dynamic Link。如果您的用途不擔心有人猜中短連結，可以選擇產生長度僅夠不重複的後置字串，方法是將 ShortDynamicLink.Suffix.SHORT 傳遞至 buildShortDynamicLink 方法：

Kotlin

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

Java

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

您可以使用 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!"
    }
}

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()

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

DynamicLink 參數
setLink

應用程式會開啟的連結。指定應用程式可處理的網址，通常是應用程式的內容或酬載，用於啟動應用程式專屬邏輯 (例如向使用者提供優待券或顯示歡迎畫面)。這個連結必須是格式正確的網址、經過適當的網址編碼、使用 HTTP 或 HTTPS，且不得為其他 Dynamic Link。
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 上開啟的連結。如果使用者未安裝應用程式，您可以指定這項參數，執行從應用程式商店安裝應用程式以外的操作，例如開啟網頁版內容，或顯示應用程式的宣傳頁面。
setIpadBundleId 在 iPad 上開啟連結時，要使用的 iOS 應用程式軟體包 ID。應用程式必須從 Firebase 控制台的「總覽」頁面連結至專案。
setMinimumVersion 可開啟連結的應用程式最低版本號碼。應用程式開啟時，系統會將這個標記傳遞給應用程式，應用程式必須決定如何處理。
NavigationInfoParameters
setForcedRedirectEnabled 如果設為「1」，則在開啟 Dynamic Link 時略過應用程式預覽頁面，改為重新導向至應用程式或商店。應用程式預覽頁面 (預設為啟用) 可更可靠地將使用者導向最合適的目的地，當他們在應用程式中開啟 Dynamic Links 時；不過，如果您預期 Dynamic Link 只會在能可靠開啟 Dynamic Links 的應用程式中開啟，而不需要這個頁面，則可以使用這個參數停用它。這項參數只會影響 Dynamic Link 在 iOS 上的行為。
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) 會傳遞至應用程式商店。

如要縮短長 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
    // ...
}

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
                    // ...
                }
            }
        });