在 Android 上建立動態鏈接

您可以使用 Firebase 動態連結產生器 API 建立短動態連結或長動態連結。此 API 接受長動態連結或包含動態連結參數的對象,並傳回如下範例所示的 URL:

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

您必須先包含 Firebase SDK,然後才能在 Android 應用程式中建立動態連結。如果您的應用程式設定為接收動態鏈接,則您已經完成了這些步驟,並且可以跳過此部分。

  1. 如果您尚未將 Firebase 新增至您的 Android 專案中,請將其新增至您的 Android 專案中。

    註冊應用程式時,請指定您的 SHA-1 簽章金鑰。如果您使用應用程式鏈接,也請指定您的 SHA-256 金鑰。

  2. 模組(應用程式層級)Gradle 檔案(通常<project>/<app-module>/build.gradle.kts<project>/<app-module>/build.gradle )中,新增動態連結的依賴項Android 的函式庫。我們建議使用Firebase Android BoM來控制函式庫版本控制。

    為了獲得動態連結的最佳體驗,我們建議在您的 Firebase 專案中啟用 Google Analytics ,並將適用於 Google Analytics 的 Firebase SDK 新增至您的應用程式。

    dependencies {
        // Import the BoM for the Firebase platform
        implementation(platform("com.google.firebase:firebase-bom:32.7.2"))
    
        // 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:21.2.0'
        implementation 'com.google.firebase:firebase-analytics:21.5.1'
    }
    
    正在尋找 Kotlin 特定的庫模組?2023 年 10 月(Firebase BoM 32.5.0)開始,Kotlin 和 Java 開發人員都可以依賴主庫模組(有關詳細信息,請參閱有關此計劃的常見問題解答)。
  3. 在 Firebase 控制台中,開啟動態連結部分。
  4. 如果您尚未接受服務條款並為動態連結設定網域,請在出現提示時執行此操作。

    如果您已有動態連結網域,請記下它。以程式設計方式建立動態連結時,您需要提供動態連結網域。

  5. 推薦:指定深層連結和後備連結中允許的 URL 模式。透過這樣做,您可以防止未經授權的各方建立從您的網域重定向到您無法控制的網站的動態連結。請參閱允許特定 URL 模式

使用 Firebase 控制台

如果您想生成單個動態鏈接,無論是出於測試目的,還是讓您的營銷團隊輕鬆創建可在社交媒體帖子等內容中使用的鏈接,最簡單的方法是訪問Firebase 控制台並創建一個手動按照分步表格操作。

若要建立動態鏈接,請使用其產生器建立新的DynamicLink對象,並使用生成器方法指定動態連結參數。然後,呼叫buildDynamicLinkbuildShortDynamicLink

以下最小範例建立一個指向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

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

若要建立短動態鏈接,請以相同的方式建立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
    // ...
}

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 個字元的連結後綴,這使得某人極不可能猜出有效的動態連結。對於您的用例,如果有人成功猜出短連結並沒有什麼壞處,那麼您可能更願意產生唯一所需長度的後綴,您可以透過將ShortDynamicLink.Suffix.SHORT傳遞給buildShortDynamicLink方法來實現:

Kotlin+KTX

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

Java

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

您可以使用動態連結產生器 API 透過任何支援的參數建立動態連結。有關詳細信息,請參閱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!"
    }
}

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

您可以透過以下方法設定動態連結參數:

動態連結參數
設定連結

您的應用程式將打開的連結。指定您的應用程式可以處理的 URL,通常是應用程式的內容或負載,用於啟動特定於應用程式的邏輯(例如向使用者提供優惠券或顯示歡迎畫面)。此連結必須是格式良好的 URL、正確的 URL 編碼、使用 HTTP 或 HTTPS,且不能是另一個動態連結。

設定DomainUriPrefix您的動態連結 URL 前綴,您可以在 Firebase 控制台中找到。動態連結網域類似以下範例:
https://example.com/link
https://example.page.link
Android參數
設定後備網址未安裝應用程式時開啟的連結。指定此選項可以在未安裝應用程式時執行從 Play 商店安裝應用程式之外的其他操作,例如開啟內容的行動網路版本,或顯示應用程式的促銷頁面。
設定最低版本可以打開連結的應用程式的最低版本的versionCode 。如果安裝的應用程式是舊版本,用戶將被帶到 Play 商店升級應用程式。
Ios參數
設定應用程式商店Id您的應用程式的 App Store ID,用於在未安裝應用程式時將使用者引導至 App Store
設定後備網址未安裝應用程式時開啟的連結。指定此選項可以在未安裝應用程式時執行從 App Store 安裝應用程式之外的其他操作,例如開啟內容的行動網路版本,或顯示應用程式的促銷頁面。
設定自訂方案您的應用程式的自訂 URL 方案(如果定義為應用程式的捆綁包 ID 以外的其他內容)
setIpadFallbackUrl未安裝應用程式時在 iPad 上開啟的連結。指定此選項可以在未安裝應用程式時執行從 App Store 安裝應用程式之外的其他操作,例如開啟內容的 Web 版本,或顯示應用程式的促銷頁面。
設定IpadBundleId用於在 iPad 上開啟連結的 iOS 應用程式的捆綁包 ID。該應用程式必須從 Firebase 控制台的「概述」頁面連接到您的專案。
設定最低版本可以開啟連結的應用程式的最低版本號。當您的應用程式打開時,此標誌會傳遞給您的應用程序,您的應用程式必須決定如何處理它。
導航資訊參數
設定強制重定向啟用如果設定為“1”,則在開啟動態連結時跳過應用程式預覽頁面,而是重定向到應用程式或商店。當使用者在應用程式中開啟動態連結時,應用程式預覽頁面(預設為啟用)可以更可靠地將使用者傳送到最合適的目的地;但是,如果您希望僅在無需此頁面即可可靠打開動態鏈接的應用程式中打開動態鏈接,則可以使用此參數禁用它。此參數僅影響 iOS 上動態連結的行為。
社交元標籤參數
設定標題在社交貼文中分享動態連結時使用的標題。
設定描述在社交貼文中分享動態連結時使用的描述。
設定圖片地址與此連結相關的圖像的 URL。影像應至少為 300x200 像素,且小於 300 KB。
GoogleAnalytics參數
設定來源
設定中
設定活動
設定期限
設定內容
Google Play 分析參數。這些參數( utm_sourceutm_mediumutm_campaignutm_termutm_content )會傳遞到 Play 商店並附加到連結負載中。
ItunesConnectAnalytics參數
設定提供商令牌
設定附屬令牌
設定活動令牌
iTunes Connect 分析參數。這些參數( ptatct )被傳遞到 App Store。

若要縮短長動態鏈接,請使用setLongLink指定動態連結的 URL,而不是使用其他建構器方法設定參數:

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

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