创建 Dynamic Links 动态链接 (Android)

您可以使用 Firebase Dynamic Links Builder API 创建长短两种形式的 Dynamic Links 动态链接。此 API 接受一个长动态链接或一个包含动态链接参数的对象，并返回类似下方所示的网址：

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

您必须先安装 Firebase SDK，然后才能在您的 Android 应用中创建 Dynamic Links 动态链接。如果您的应用已设置为接收 Dynamic Links 动态链接，说明您已经完成了这些步骤，可以跳过这一部分。

  1. 将 Firebase 添加到您的 Android 项目（如果尚未添加）。

    在注册您的应用时，请指定 SHA-1 签名密钥。如果您使用 App Links，还需要指定 SHA-256 密钥。

  2. 使用 Firebase Android BoM 在模块（应用级）Gradle 文件（通常为 app/build.gradle）中声明 Dynamic Links Android 库的依赖项。

    为了获得最佳的 Dynamic Links 使用体验，我们建议您在 Firebase 项目中启用 Google Analytics（分析），并将适用于 Google Analytics（分析）的 Firebase SDK 添加到您的应用中。

    Java

    dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:29.0.3')

    // Declare 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 {
    // Declare 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.0.0'
    implementation 'com.google.firebase:firebase-analytics:20.0.2'
}

    Kotlin+KTX

    dependencies {
    // Import the BoM for the Firebase platform
    implementation platform('com.google.firebase:firebase-bom:29.0.3')

    // Declare 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-ktx'
    implementation 'com.google.firebase:firebase-analytics-ktx'
}

    使用 Firebase Android BoM，可确保您的应用始终使用 Firebase Android 库的兼容版本。

    （替代方法） 在不使用 BoM 的情况下声明 Firebase 库依赖项

    如果您选择不使用 Firebase BoM，则必须在每个 Firebase 库的依赖项行中指定相应的库版本。

    请注意，如果您在应用中使用多个 Firebase 库，我们强烈建议您使用 BoM 来管理库版本，以确保所有版本都兼容。 

    dependencies {
    // Declare 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-ktx:21.0.0'
    implementation 'com.google.firebase:firebase-analytics-ktx:20.0.2'
}
  3. 在 Firebase 控制台中，打开 Dynamic Links 部分。

  4. 如果您尚未接受服务条款，也尚未为 Dynamic Links 设置网域，请在收到提示时执行相关操作。

    如果您已经有了 Dynamic Links 网域，请记下它。在以编程方式创建 Dynamic Links 动态链接时，您需要提供 Dynamic Links 网域。

  5. 推荐：指定可以在您的深层链接和后备链接中使用的网址格式。这样做可以防止未经授权者创建动态链接，从您的网域重定向至您无法控制的网站。 请参阅允许特定网址格式。

使用 Firebase 控制台

如果您想生成一个动态链接（无论是出于测试目的，还是为了让您的营销团队轻松创建可以在社交媒体帖子等地方使用的链接），最简单的方法就是访问 Firebase 控制台并按照分步说明手动创建一个。

如需创建动态链接，请使用其构建器创建一个新的 DynamicLink 对象，并在构建器方法中指定动态链接参数。然后，调用 buildDynamicLink 或 buildShortDynamicLink。

下面这个极为简单的示例创建了一个指向 https://www.example.com/ 的长动态链接，此链接会在您的 Android 应用和 iOS 应用 com.example.ios 中打开：

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

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

如需创建一个短动态链接，请按照上面相同的方式构建一个 DynamicLink，然后调用 buildShortDynamicLink。构建短链接需要发出网络调用。因此，buildShortDynamicLink 会返回一个 Task（用于在请求完成时提供短链接），而不是直接返回链接。例如：

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

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.ktx.component1 and
    // com.google.firebase.dynamiclinks.ktx.component2

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

默认情况下，生成的短 Dynamic Links 动态链接有 17 个字符的链接后缀，让他人极难猜测出有效的 Dynamic Links 动态链接。如果在您的用例中，短链接即使被人猜中也不会造成任何危害，可以仅生成长度足以确保唯一性的后缀。将 ShortDynamicLink.Suffix.SHORT 传递到 buildShortDynamicLink 方法即可实现此目的：

Java

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

Kotlin+KTX

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

您可以使用 Dynamic Link Builder API 根据任意受支持的参数来创建 Dynamic Links 动态链接。如需了解详细信息，请参阅 API 参考。

以下示例创建了一个设置了几个常见参数的动态链接：

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

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

您可以使用以下方法设置动态链接参数：

DynamicLink 参数
setLink

您的应用将打开的链接。指定一个您的应用能够处理的网址，通常是应用的内容或载荷，用于启动应用特有的逻辑（例如为用户发放优惠券或显示欢迎页面）。此链接必须是格式正确的网址、采用正确的网址编码、使用 HTTP 或 HTTPS 架构，并且不能是另一个动态链接。
setDomainUriPrefix 您的动态链接网址前缀，可在 Firebase 控制台中找到。动态链接网域类似于以下示例：

https://example.com/link
https://example.page.link
AndroidParameters
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”，当动态链接打开时，会跳过应用预览页面，重定向到相关应用或商店。当用户在应用中打开动态链接时，应用预览页面（默认启用）可以更加可靠地将用户引导至最合适的目标位置；但是，如果您希望某个动态链接只在没有此页面也能可靠地打开动态链接的应用中打开，则可以使用此参数停用应用预览页面。此参数只会影响 iOS 上的动态链接的行为。
SocialMetaTagParameters
setTitle 在社交贴子中分享动态链接时要使用的标题。
setDescription 在社交贴子中分享动态链接时要使用的描述。
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。

如需缩短长动态链接，请使用 setLongLink 指定动态链接的网址，而不是使用其他构建器方法来设置参数：

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

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.ktx.component1 and
    // com.google.firebase.dynamiclinks.ktx.component2

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