Firebase Dynamic Links：是什么、链接创建与集成

什么是 Firebase Dynamic Links

Firebase Dynamic Links 是 Google 的一项技术，创建单个链接，引导至移动应用或网站中的所需内容，根据平台和安装状态调整行为。链接检查应用是否已安装在设备上：如果是 — 打开应用并传递参数，如果否 — 引导至 Google Play 或 App Store 进行安装，安装后重定向到目标屏幕。

关键特性：Deferred Deep Linking

Dynamic Links 相对于普通深层链接的主要优势在于支持延迟深层链接。Deferred Deep Linking 意味着即使应用尚未安装，跳转上下文（链接参数）也会被保留。当用户从商店安装应用时，Dynamic Links SDK 读取保存的上下文并将其传递到相应屏幕。如果没有这项技术，用户安装后将直接进入主屏幕，丢失促销代码、邀请函或特定订单的链接。

应用领域

Dynamic Links 用于推荐计划，通过关联邀请者的账户来吸引新用户。营销活动通过电子邮件通讯和社交媒体的跳转使用 Dynamic Links 精确衡量转化率。在新用户引导场景中，链接将新用户带到带有个性化内容的欢迎屏幕。在电子商务中，产品链接保持上下文，即使在安装后首次启动时也能引导至产品页面。

动态链接如何工作

工作原理 Dynamic Links 由多个阶段组成，每个阶段根据应用状态可能有所不同。当用户点击动态链接时，浏览器向 Firebase 服务器发送请求。Firebase 通过 intent-filter 或 universal link 验证检查应用是否已安装。如果应用已安装，Firebase 打开应用并传递深层链接。如果没有 — 重定向到商店页面或网页版本。

动态链接的结构

标准 Dynamic Link 由基础 URL、链接参数和可选营销标签组成。基础 URL 是注册在 Firebase Console 中的域名，格式为 your-app.page.link。深层链接参数通过查询参数设置：link（应用内的目标 URL）、apn（Android Package Name）、ibi（iOS Bundle ID）、st 和 sd（社交预览的标题和描述）。营销标签 utm_source、utm_medium、utm_campaign 传递给 Google Analytics 进行跟踪。

通过 Firebase Console 和 API 创建链接

Firebase Console 在 Engage > Dynamic Links 部分提供可视化界面来创建 Dynamic Links。在控制台中，可以设置所有链接参数，包括深层链接、网页行为、社交元数据和 UTM 标签。创建链接后，控制台提供准备好的 URL 以及点击和跳转统计信息。对于批量创建链接，使用带有 OAuth 2.0 身份验证的 Firebase Dynamic Links REST API。

通过 REST API 创建链接

以编程方式创建 Dynamic Links 使用向 Firebase Dynamic Links API 发送 POST 请求。请求体包含 dynamicLinkInfo，其中包含深层链接参数、平台设置和社交元数据。API 返回格式为 https://your-app.page.link/abc123 的完整 URL。对于长期链接，使用 suffix.option = UNIQUE — 带有唯一后缀的短链接。对于临时链接 — SHORT，可能存在冲突。

const axios = require("axios")

const apiUrl = "https://firebasedynamiclinks.googleapis.com/v1/shortLinks?key=API_KEY"

const data = {
    dynamicLinkInfo: {
        domainUriPrefix: "https://yourapp.page.link",
        link: "https://yourapp.com/promo/summer",
        androidInfo: { androidPackageName: "com.example.myapp" },
        iosInfo: { iosBundleId: "com.example.myapp.ios" },
        socialMetaTagInfo: {
            socialTitle: "夏季促销",
            socialDescription: "月底前最高 50% 折扣"
        }
    },
    suffix: { option: "UNIQUE" }
}

axios.post(apiUrl, data)
    .then(res => console.log(res.data.shortLink))
    .catch(err => console.error(err))

短链接和 UTM 标签

Dynamic Links 自动生成短 URL，域名后长度为 6-8 个字符，使其适合在短信和社交媒体中使用。UTM 参数通过 utmParameters 字段或直接在 link 参数中添加。Firebase 自动将 Dynamic Links 点击与 Firebase 的 Google Analytics 关联，从而可以跟踪引荐流量和活动归因。

在 Android 中集成 Dynamic Links

在 Android 中配置 Dynamic Links 包括添加 Firebase SDK、配置接收深层链接的 Activity 的 intent-filter 以及通过 Firebase Dynamic Links SDK 处理链接。安装 SDK 并添加 google-services.json 后，需要在 AndroidManifest.xml 中注册 Activity，并配置 intent-filter 以处理来自应用域名的链接。

在 AndroidManifest 中配置 intent-filter

处理 Dynamic Links 的 Activity 必须具有针对 VIEW 操作以及 DEFAULT 和 BROWSABLE 类别的 intent-filter。AndroidManifest.xml 包含一个 data 标签，带有与您的深层链接对应的 android:scheme、android:host 和 android:pathPrefix。为了处理来自 page.link 域名的链接，还需要添加一个带有 https 方案和 Dynamic Links 域名 host 的 intent-filter。

<!-- AndroidManifest.xml -->
<activity android:name=".MainActivity">
    <intent-filter>
        <action android:name=
            "android.intent.action.VIEW" />
        <category android:name=
            "android.intent.category.DEFAULT" />
        <category android:name=
            "android.intent.category.BROWSABLE" />
        <data android:scheme="https"
            android:host="yourapp.com"
            android:pathPrefix="/promo" />
    </intent-filter>
</activity>

在代码中处理链接

配置 intent-filter 后，需要在 Activity 代码中处理传入的 Dynamic Link。FirebaseDynamicLinks API 从 intent 中获取链接，并返回带有提取参数的 PendingDynamicLinkData 对象。getLink 方法返回目标深层链接，可以解析并用于导航。重要的是在冷启动时（通过 onCreate 中的 getIntent）和热启动时（通过 onNewIntent）都要处理链接。

在 iOS 中集成 Dynamic Links

在 iOS 中配置 Dynamic Links 需要在 Firebase 端和 Xcode 项目中都进行配置。需要在 Firebase Console 中上传 APNs 密钥，通过 Swift Package Manager 或 CocoaPods 添加 Firebase SDK，并配置 App Delegate 以处理 Universal Links。iOS 中的 Dynamic Links 使用 Universal Links 实现浏览器和应用之间的无缝跳转，无需中间页面。

配置 Universal Links

Universal Links 是 Apple 的一项技术，用于将您的域名与移动应用关联。apple-app-site-association (AASA) 文件加载到服务器上的 https://your-app.page.link/apple-app-site-association 地址。Firebase 为您的 Dynamic Links 域名自动创建和维护此文件。在 Xcode 中，需要启用 Associated Domains 并在项目的 Capabilities 中指定 applinks:your-app.page.link。

通过 Firebase SDK 处理链接

对于 iOS，Dynamic Links 的处理通过 Firebase SDK 在 App Delegate 或 Scene Delegate 中执行。application:continueUserActivity: 方法拦截传入的 Universal Link 并将其传递给 Firebase Dynamic Links API，该 API 提取目标链接和参数。Firebase SDK 自动处理 Deferred Deep Links，通过 Firebase Installation API 的短期存储请求安装数据。

import FirebaseDynamicLinks

class AppDelegate: UIApplicationDelegate {

    func application(
        _ application: UIApplication,
        continue userActivity: NSUserActivity,
        restorationHandler: @escaping
            ([UIUserActivityRestoring]?) -> Void
    ) -> Bool {
        return DynamicLinks.dynamicLinks()
            .handleUniversalLink(userActivity.webpageURL!) {
                dynamicLink, error in
                if let link = dynamicLink?.url {
                    self.handleDeepLink(link)
                }
            }
    }
}

Kotlin 实现示例

让我们看看在 Kotlin 的 Android 应用中处理 Dynamic Link 的完整示例。MainActivity 在应用的冷启动和热启动时都读取传入的 Dynamic Link。链接被解析为参数，用于通过传递参数导航到相应的屏幕。示例展示了处理指向促销页面的链接，其中包含促销 ID。

class MainActivity : AppCompatActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.activity_main)
        handleDynamicLink(intent)
    }

    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleDynamicLink(intent)
    }

    private fun handleDynamicLink(intent: Intent) {
        FirebaseDynamicLinks.getInstance()
            .getDynamicLink(intent)
            .addOnSuccessListener { data ->
                val deepLink = data?.link ?: return@addOnSuccessListener
                val promoId = deepLink
                    .getQueryParameter("promoId") ?: ""
                if (promoId.isNotEmpty()) {
                    navigateToPromoScreen(promoId)
                }
            }
            .addOnFailureListener { e ->
                Log.e("DL", "链接处理错误", e)
            }
    }
}

测试 Dynamic Links

要测试 Dynamic Links，使用 Firebase Console，可以在其中创建测试链接并通过即时通讯工具或电子邮件发送到设备。Firebase Dynamics Links Debugger 可通过 URL https://your-app.page.link/?d=1 访问，显示有关链接行为的详细信息。在测试 Deferred Deep Links 时，需要确保应用已被卸载，并且安装后链接使用传递的参数引导到正确的屏幕。