从动态链接迁移到应用链接和通用链接

本迁移指南重点介绍如何使用应用链接和通用链接，以及选择性地使用 Firebase Hosting 托管您的应用网站关联文件。

此迁移取代了以下 Firebase Dynamic Links 功能：

特征	Firebase Dynamic Links	应用链接/通用链接
用户只需点击一次链接，系统即可将用户引导至设备的相应商店		^★
利用延迟深层链接，在用户下载并安装您的应用后，为用户提供后续体验		^★
在应用中使用深层链接内容为用户提供上下文体验（如果已安装）
提供与动态链接点击事件相关的分析数据
提供创建短链接网址的功能

如果您仍然需要本指南不支持的其他 Firebase 动态链接功能来完成迁移，请参阅动态链接弃用常见问题解答文档中的其他迁移场景。

假设您有一个如下所示的 Firebase Dynamic Links 动态链接：

动态链接示例
关联名称	欢迎访问 Example.com
深层链接	`https://example.web.app/welcome`
Android 应用	`com.example.android`
Apple 应用	`com.example.ios`
长动态链接	`https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos`
短动态链接	`https://example.page.link/m9Mm`

本迁移指南的目标是替换如下所示的 Firebase Dynamic Links：

https://example.page.link/m9Mm

应用链接/通用链接深层链接如下所示：

https://your-project-domain.web.app/welcome

请注意，应用链接/通用链接深层链接将为用户提供以下内容：

用户点击深层链接可以打开已安装的应用
应用打开后，将用户带往应用中的特定部分，以延续用户体验历程

不过，应用链接/通用链接深层链接不会为用户提供以下行为（之前由 Firebase Dynamic Links 提供）：

将用户转到其设备的相应商店，以下载和安装您的应用
在首次下载、安装和打开应用后提供用户体验历程

请注意，上面所示应用链接/通用链接与 Firebase Dynamic Links 动态链接的行为及功能有何不同。

准备工作

Firebase Dynamic Links 在其底层实现中利用应用链接（在 Android 上）和通用链接（在 iOS 上），以在用户安装您的应用后提供深层链接功能。

本指南介绍如何使用 Firebase Hosting 创建自己的应用链接和通用链接，以替换 Firebase Dynamic Links 提供的部分功能，同时将 Firebase Dynamic Links 迁移到新的应用链接/通用链接迁移解决方案。

您需要以下信息才能完成迁移：

您打算迁移的 Firebase Dynamic Links 动态链接
您的动态链接中包含的深层链接网址参数
您计划用于替换之前的 Firebase Dynamic Links 网域的网域（如果适用）

您可以参考导出动态链接元数据指南来导出现有的链接元数据并获取上面列出的信息。

迁移步骤概览

预配一个新网域（如果您还没有想要使用的网域）来使用 Firebase Hosting 托管您的应用链接/通用链接配置文件。
在托管网域上创建并托管应用链接/通用链接配置文件。
创建与 Firebase 动态链接中使用的深层链接架构匹配的新应用链接/通用链接。
更新您的 Android/iOS 应用和应用代码以接收深层链接。
测试您的应用链接/通用链接集成。
将已发布或共享的 Firebase Dynamic Links 替换为应用链接和通用链接。

第一步对于应用链接或通用链接迁移流程是相同的。其余步骤因平台而异，因此请根据您要迁移的平台，转到以下指南部分。

Android 应用链接的迁移步骤
iOS 通用链接的迁移步骤

使用 Firebase Hosting 预配新网域以托管您的应用链接/通用链接配置文件

选择网域

第一步是选择要用于应用链接/通用链接的网域。该网域将用于您将提供给用户的新链接。

如果您使用 Firebase Hosting，系统会自动免费预配格式为 your-project-domain.web.app 或 your-project-domain.firebaseapp.com 的项目子网域。您也可以选择使用自定义网域来托管应用链接/通用链接配置文件（无论是否使用 Firebase Hosting）。

设置 Firebase 托管

接下来，您需要设置和配置 Firebase Hosting 实例。

完成 Firebase Hosting 实例的设置后，您将拥有类似于 your-project-domain.web.app 的网域或自定义网域（如果您喜欢使用自定义网域）。

Android 应用链接的迁移步骤

在新托管网域上创建并托管应用链接配置文件

为了使用应用链接，您必须托管一个配置文件，以帮助在您的链接中使用的网域与您的应用之间建立安全的关联。对于应用链接，这就是 assetlinks.json 文件。

创建和托管 assetlinks.json 文件的步骤

我们可以使用 assetlinks.json 文件提供一个授权应用列表，这些应用可以处理我们将用于应用链接的 Web 网域的内容。assetlinks.json 文件本身需要托管在网域的根目录下，路径为 /.well-known。

请按照以下步骤完成此配置：

在 Firebase Hosting 根目录中的公共文件夹下创建 .well-known 文件夹。
在 .well-known 文件夹下创建一个名为 assetlinks.json 的文件。
将以下内容复制到 assetlinks.json 文件中，并注意以下每个字段的含义：
```
[{
  "relation": ["delegate_permission/common.handle_all_urls"],
  "target": {
    "namespace": "android_app",
    "package_name": "com.example.android",
    "sha256_cert_fingerprints":
      ["01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF:01:23:45:67:89:AB:CD:EF"]
  }
}]
```
- namespace - 是指您要提供的应用的名称
- package_name - 是指在应用的 build.gradle 文件中声明的 applicationId
- sha256_cert_fingerprints - 是指用于为应用签名的密钥库文件的 SHA256 指纹。
您可以使用 Android Studio 使用的 debug.keystore 文件生成 sha256_cert_fingerprints 记录，以用于调试。您可以在 Mac 和 Linux 上的 /Users/<username>/.android/debug.keystore 以及 Windows 上的 C:\Users\<username>\.android\debug.keystore 中找到该文件。

在此密钥库中，您可以使用 keytool 提取 SHA256 值。

如需详细了解如何完成此步骤，请参阅应用链接文档的这一部分。

或者，您也可以使用 Android Studio 中的 App Links Assistant 生成 assetlinks.json 文件内容，并将应用配置为处理应用链接。

更新 firebase.json 文件以将该文件编入索引进行托管。

"headers": [
  {
    "source": "/.well-known/assetlinks.json",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ]
  }
]

现在，assetlinks.json 文件已准备就绪，请运行 firebase deploy 来托管更改。

请注意，您需要安装 Firebase CLI 才能运行上述部署命令。
```
firebase deploy --only hosting
```
转到 https://your-project-domain.web.app/.well-known/assetlinks.json 验证 assetlinks.json 文件

创建与 Firebase Dynamic Links 中使用的深层链接架构匹配的新应用链接

在此步骤中，您将使用与您为应用链接创建的新网域匹配的常规深层链接网址重新创建 Firebase Dynamic Links 中的深层链接。

例如，假设您有以下 Firebase Dynamic Links 动态链接：

动态链接示例
关联名称	欢迎访问 Example.com
深层链接	`https://example.web.app/welcome`
Android 应用	`com.example.android`
Apple 应用	`com.example.ios`
长动态链接	`https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos`
短动态链接	`https://example.page.link/m9Mm`

在这种情况下，您需要提取深层链接参数（即 https://example.web.app/welcome），并将其用作应用的应用链接参数。

对于您希望迁移到应用链接/通用链接的每个 Firebase Dynamic Links 动态链接，您需要重复上述流程，并复制您使用的深层链接架构。

例如，请参阅下面一组 Firebase Dynamic Links 短链接、深层链接参数和迁移后的深层链接值：

短链接	深层链接参数	迁移后的深层链接
yourapp.page.link/welcome	https://example.com/welcome	yourapp.web.app/welcome
yourapp.page.link/c7sn	https://example.com/main/?p=23&t=1	yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social	https://example.com/friendinvite/?add=1	yourapp.web.app/friendinvite/?add=1

接下来，您需要将所有已发布或共享的 Firebase Dynamic Links 替换为迁移后的新深层链接，以便用户点击这些应用链接，而不是以前的 Firebase Dynamic Links。

更新 Android 应用和应用代码以接收深层链接

选择网域、选择深层链接架构并将 Firebase Dynamic Links 迁移到应用链接后，下一步是更新您的 Android 应用和应用代码，以接收新的深层链接。

我们建议您参考此处的完整应用链接文档或 Android Studio 指南来将应用配置为处理深层链接。但主要步骤包括：

确定哪些 activity 应处理相应的深层链接
在 AndroidManifest.xml 文件中为这些 activity 添加 intent 过滤器
在 activity 的应用代码中接收深层链接

假设您要使用 MainActivity 处理某些深层链接。为此，您需要将以下 intent 过滤器添加到 AndroidManifest.xml 文件中的 MainActivity：

<activity android:name=".MainActivity"
   android:exported="true">
   <intent-filter>
       <action android:name="android.intent.action.MAIN" />
       <category android:name="android.intent.category.LAUNCHER" />
   </intent-filter>
   <intent-filter android:autoVerify="true">
       <action android:name="android.intent.action.VIEW" />
       <category android:name="android.intent.category.DEFAULT" />
       <category android:name="android.intent.category.BROWSABLE" />
       <data android:host="example.web.app" android:scheme="http"
           android:pathPrefix="/welcome" />
       <data android:host="example.web.app" android:scheme="https"
           android:pathPrefix="/welcome" />
   </intent-filter>
</activity>

在此步骤中，您将指定 MainActivity 是来自 wxample.web.app 网域的深层链接的目标 activity，该链接包含 /welcome 路径前缀。请注意，您还需要指定 android:autoVerify="true" 属性，以便将您的应用指定为此类给定链接的默认处理程序。

最后，您需要在 MainActivity 中添加代码以检索深层链接数据，并使用这些数据来提升应用中的深层链接体验。这类似于您在与 Firebase Dynamic Links 集成时已在应用中编写的逻辑。

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)
  setContentView(R.layout.main)

  val  data: Uri? = intent?.data

  val toast = Toast.makeText(this, data, duration)
  toast.show()
}

测试应用链接

您可以通过在实体设备上运行应用或在 Android 模拟器中运行应用，来测试刚刚创建的应用链接。

您需要使用为应用链接配置的网域创建可点击的链接，然后点击该链接，确保其可打开您的应用并转到预期的 activity。

或者，您可以使用 Android Studio 中的 App Links Assistant 来测试应用链接集成，也可以对您已配置的应用链接网址运行以下命令以确保它正确启动匹配 activity：

adb shell am start -a android.intent.action.VIEW -d <your_deep_link_url>

将已发布或共享的 Firebase Dynamic Links 替换为应用链接

迁移的最后一步是尽可能将已发布的或共享的 Firebase Dynamic Links 替换为应用链接，并且在之后继续使用应用链接。

完成此步骤的方式取决于您发布 Firebase Dynamic Links 的位置和方式，但为了方便跟踪现有的动态链接，您可以导出现有的 Firebase Dynamic Links 元数据。请参阅导出动态链接元数据指南。

iOS 通用链接的迁移步骤

在新的托管网域上创建并托管通用链接配置文件

为了使用通用链接，您必须托管一个配置文件，以帮助在您的链接中使用的网域与您的应用之间建立安全的关联。对于通用链接，这就是 apple-app-site-association 文件（也称为 AASA 文件）。

创建和托管 apple-app-site-association 文件的步骤

我们可以使用 AASA 文件提供一个授权应用列表，这些应用可以处理我们将用于通用链接的 Web 网域的内容。AASA 文件本身需要托管在网域的根目录下，路径为 /.well-known。

请按照以下步骤完成此配置：

在 Firebase Hosting 根目录中的公共文件夹下创建“.well-known”文件夹。
在“.well-known”文件夹下，创建一个名为“apple-app-site-association”的文件。

将以下内容复制到 apple-app-site-association 文件中，并注意以下每个字段的含义：

{
  "applinks": {
    "apps": [],
    "details": [
      {
        "appId": "$TEAM_ID.com.firebase.UniversalLinks",
        "paths": [
          "NOT /_/*",
          "/*"
        ]
      }
    ]
  }
}

$TEAM_ID.BundleId - 获授权处理链接的完全限定应用名称

更新 firebase.json 文件以将该文件编入索引进行托管。

"headers": [
  {
    "source": "/.well-known/apple-app-site-association",
    "headers": [
      {
        "key": "Content-Type",
        "value": "application/json"
      }
    ]
  }
]

现在，AASA 文件已准备就绪，请运行 firebase deploy 来托管更改。
转到 https://your-project-domain.web.app/.well-known/app-app-site-association 来验证 AASA 文件。

创建与 Firebase Dynamic Links 中使用的深层链接架构匹配的新通用链接

在此步骤中，您将使用与您为通用链接创建的新网域匹配的常规深层链接网址重新创建 Firebase Dynamic Links 中的深层链接。

例如，假设您有以下 Firebase Dynamic Links 动态链接：

动态链接示例
关联名称	欢迎访问 Example.com
深层链接	`https://example.web.app/welcome`
Android 应用	`com.example.android`
Apple 应用	`com.example.ios`
长动态链接	`https://example.page.link/?link=https://example.web.app/welcome&apn=com.example.android&isi=123456789&ibi=com.example.iuos`
短动态链接	`https://example.page.link/m9Mm`

在这种情况下，您需要提取深层链接参数（例如 https://example.web.app/welcome），现在将该参数用作应用的通用链接参数。

对于您希望迁移到应用链接/通用链接的每个 Firebase Dynamic Links 动态链接，您需要重复上述流程，并复制您使用的深层链接架构。

例如，请参阅下面一组 Firebase Dynamic Links 短链接、深层链接参数和迁移后的深层链接值：

短链接	深层链接参数	迁移后的深层链接
yourapp.page.link/welcome	https://example.com/welcome	yourapp.web.app/welcome
yourapp.page.link/c7sn	https://example.com/main/?p=23&t=1	yourapp.web.app/main/?p=23&t=1
yourapp.page.link/social	https://example.com/friendinvite/?add=1	yourapp.web.app/friendinvite/?add=1

接下来，您需要将所有已发布或共享的 Firebase Dynamic Links 替换为迁移后的新深层链接，以便用户点击这些通用链接，而不是以前的 Firebase Dynamic Links。

更新 iOS 应用和应用代码以接收深层链接

选择网域、选择深层链接架构并将 Firebase Dynamic Links 迁移到通用链接后，下一步是更新您的 iOS 应用和应用代码，以接收新的深层链接。

我们建议您按照此处的完整通用链接文档将您的应用配置为处理深层链接，但主要步骤包括：

更新项目配置，让应用能够处理来自新创建网域的深层链接
在应用代码中接收深层链接

为了更新项目配置以让应用能够处理深层链接，您需要在 Xcode 中为您计划用于托管 apple-app-site-associate 文件的网域向项目额外添加一个关联网域。

这可通过以下操作实现：

打开 Xcode
在文件导航器中选择您的项目
进入项目设置的“Signing & Capabilities”（签名和功能）标签页
向下滚动到“Associated Domains”（关联的网域）部分
点击 + 按钮向项目添加一个额外的网域，其格式为“applinks:”。

最后，您需要更新应用代码才能接收传入的深层链接。

为此，请先添加以下代码来更新 AppDelegate.swift 文件以响应通用链接：

func application(_ application: UIApplication, continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  AppDelegate.showReceivedUrl(userActivity: userActivity);
  return true
}

static func showReceivedUrl(userActivity: NSUserActivity) {
  if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
    let url = userActivity.webpageURL!
    print(url.absoluteString)
}

上面的代码会替换通用链接回调方法，并记录深层链接网址（如果存在）。

现在，我们还将从 SceneDelegate 类调用相同的 showReceivedUrl 方法，因为如果在用户点击通用链接时应用已经打开，则 SceneDelegate 内的通用链接回调将被调用。

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
  AppDelegate.showReceivedUrl(userActivity: userActivity)
}

测试通用链接

您可以通过在实体设备或模拟器上运行应用来测试刚刚创建的通用链接。

您需要使用为通用链接配置的网域创建可点击的链接，然后点击该链接，确保其可打开您的应用并转到应用内预期的页面。

支持智能应用横幅

我们强烈建议您使用智能应用横幅广告，为用户提供与 Firebase Dynamic Links 类似的体验。

使用智能应用横幅广告时，如果用户设备尚未安装您的应用，用户将被引导至 App Store 中的应用详情。您还可以选择配置在下载和安装后传入应用的参数，以便用户能够继续其体验历程。如果用户已安装您的应用，则应用会打开并传入参数，从而根据用户点击的智能应用横幅广告将用户带往相应的内容。

将已发布或共享的 Firebase Dynamic Links 替换为应用链接

迁移的最后一步是尽可能将已发布的或共享的 Firebase Dynamic Links 替换为通用链接，并且在之后继续使用通用链接。

完成此步骤的方式取决于您发布 Firebase Dynamic Links 的位置和方式。

为帮助您跟踪要迁移的现有 Firebase Dynamic Links，我们将发布有关如何从 Firebase Dynamic Links 导出短链接元数据的指南。请参阅我们的动态链接弃用常见问题解答文档，了解更多最新动态。