创建动态链接 (Android)

已弃用：Firebase Dynamic Links 已弃用，不应在尚未使用它的项目中采用。该服务将于 2025 年 8 月 25 日关停。如需了解详情，请参阅 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 和 Dynamic Links SDK

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

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

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

2. 在模块（应用级）Gradle 文件（通常是 <project>/<app-module>/build.gradle.kts 或 <project>/<app-module>/build.gradle）中，添加 Dynamic Links 库的依赖项。我们建议使用 Firebase Android BoM 来实现库版本控制。

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

   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

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

下面这个极为简单的示例创建了一个指向 https://www.example.com/ 的长 Dynamic Link，此链接会在您的 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

默认情况下，生成的短 Dynamic Links 有 17 个字符的链接后缀，这样他人基本上不可能猜测出有效的 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 个参数

您可以使用 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 开头，并且不能是另一个动态链接。 当用户在桌面网络浏览器中打开 Dynamic Link 时，浏览器将加载此网址（除非指定了 ofl 参数）。如果您没有与所链接的内容相对应的 Web 资源，该网址就无需指向一个有效的 Web 资源。在这种情况下，您应设置一个从此网址重定向到的网址，例如您的首页。
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	在未安装应用时要打开的链接。指定此链接是为了在用户未安装应用时完成一些不同于从 App Store 安装您的应用的任务，比如打开内容的移动网页版或显示您的应用的宣传页面。
setCustomScheme	您的应用的自定义网址方案（如果定义为不同于您的应用的软件包 ID 的其他内容）。
setIpadFallbackUrl	在未安装应用时要在 iPad 上打开的链接。指定此链接是为了在用户未安装应用时完成一些不同于从 App Store 安装您的应用的任务，比如打开内容的网页版或显示您的应用的宣传页面。
setIpadBundleId	在 iPad 上用于打开链接的 iOS 应用的软件包 ID。您必须从 Firebase 控制台的“概览”页面将该应用关联到您的项目。
setMinimumVersion	可以打开链接的应用最低版本的版本号。此标志在您的应用被打开时传递到该应用，并且应用必须决定如何处理此标志。

NavigationInfoParameters
setForcedRedirectEnabled	如果设为“1”，当 Dynamic Link 打开时，会跳过应用预览页面，重定向到相关应用或商店。当用户在应用中打开 Dynamic Links 时，应用预览页面（默认启用）可以更加可靠地将用户引导至最合适的目标位置；但是，如果您计划让 Dynamic Link 只在没有此页面也能可靠地打开 Dynamic Links 的应用中打开，则可以使用此参数停用应用预览页面。此参数只会影响 iOS 上的 Dynamic Link 的行为。

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）会传递到 App Store。

缩短长 Dynamic Link

如需缩短长 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