深度链接 - OneSignal

概览

深度链接在用户点击链接时将其引导至应用中的特定页面——无论链接来自电子邮件、SMS、网站、推送通知还是应用内消息。如果未安装应用程序，操作系统可以将用户重定向至应用商店或备用网页。本指南涵盖：

深度链接类型及各类型的适用场景
Android 和 iOS 的平台设置
使用 OneSignal SDK 在应用中处理深度链接
推送、电子邮件和应用内消息的渠道特定行为

有关常规 URL 和链接配置（启动 URL、UTM 参数、动态 URL、链接跟踪），请参阅 URL、链接和深度链接。

前提条件

设置深度链接前，您需要：

已配置应用的 OneSignal 账户
已在移动应用中安装 OneSignal SDK
您控制的域名，通过 HTTPS 托管，用于通用链接或应用链接
访问应用源代码和构建配置的权限（iOS 使用 Xcode，Android 使用 Android Studio）

深度链接类型

深度链接有三种常见机制，各自的行为取决于应用是否已安装。

类型	平台	格式	应用未安装时
通用链接	iOS 9+	`https://yourdomain.com/path`	在 Safari 中打开 URL
应用链接	Android 6.0+	`https://yourdomain.com/path`	在浏览器中打开 URL
自定义 URI 方案	iOS 和 Android	`myapp://path`	静默失败或显示错误

建议： 使用通用链接（iOS）和应用链接（Android）以获得最可靠的体验。它们使用标准 https:// URL，可跨渠道（推送、电子邮件、SMS）使用，并在应用未安装时提供备用行为。自定义 URI 方案（myapp://）设置更简单，但不提供备用行为，且在某些场景下可能无法使用（例如，电子邮件客户端）。

通用链接和应用链接需要在您的域名上托管验证文件。没有此文件，操作系统会将链接视为普通网页 URL。

Android 设置（应用链接）

使用 Android Studio 的 App Links Assistant 生成所需配置。

配置 intent 过滤器

向应处理深度链接的 Activity 添加 intent 过滤器：

<activity android:name=".DeepLinkActivity" android:exported="true">
  <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:scheme="https" android:host="yourdomain.com" />
  </intent-filter>
</activity>

处理传入 intent

Intent appLinkIntent = getIntent();
String appLinkAction = appLinkIntent.getAction();
Uri appLinkData = appLinkIntent.getData();

托管 Digital Asset Links 文件

使用 Android Studio 的 App Links Assistant 生成 assetlinks.json 文件，并将其托管在：

https://yourdomain.com/.well-known/assetlinks.json

有关完整文件格式和验证步骤，请参阅 Google 的 Verify App Links 文档。

iOS 设置（通用链接）

Apple 通用链接在用户点击匹配的 https:// URL 时打开您的应用。对于确保已安装应用的简单用例，您也可以使用 URL 方案。

启用 Associated Domains

在 Xcode 中，选择您的 target → Signing & Capabilities → 添加 Associated Domains
添加您的域名：applinks:yourdomain.com

在应用中处理通用链接

func application(_ application: UIApplication,
                 continue userActivity: NSUserActivity,
                 restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
  guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
        let url = userActivity.webpageURL else {
    return false
  }
  // Route to the correct screen based on the URL path
  return true
}

托管 Apple App Site Association 文件

创建 apple-app-site-association（AASA）文件并将其托管在：

https://yourdomain.com/.well-known/apple-app-site-association

将 TEAMID 替换为您的 Apple Team ID，将 com.example.app 替换为您的 bundle identifier：

{
  "applinks": {
    "apps": [],
    "details": [{
      "appID": "TEAMID.com.example.app",
      "paths": ["/path/*", "/another-path"]
    }]
  }
}

有关完整规范，请参阅 Apple 的支持关联域文档。

iOS 启动 URL 行为

OneSignal 的 iOS SDK 使用 openURL 处理启动 URL（url 属性）。这会导致链接先在浏览器中打开，然后重定向回应用——可能带来较差的用户体验。要避免此问题，请使用以下方法之一：

在 API 载荷中使用 data 替代 url，并在您的推送通知点击监听器中处理深度链接
通过在 Info.plist 中添加布尔值 YES 的 OneSignal_suppress_launch_urls 来抑制启动 URL，然后在点击监听器中处理所有导航

推荐方法 1（使用 data + 点击监听器），因为它让您无需依赖操作系统解析 URL 即可完全控制导航。

使用 OneSignal SDK 处理深度链接

从 OneSignal 消息处理深度链接最可靠的方式是使用 SDK 的点击监听器，而不是依赖操作系统级别的链接解析。这让您可以完全控制应用中的导航。

推送通知点击监听器

使用 addClickListener 拦截通知点击，并根据深度链接 URL 或附加数据路由用户：

OneSignal.Notifications.addClickListener { event ->
  val url = event.notification.launchURL
  val data = event.notification.additionalData
  // Route to the correct screen based on url or data
}

有关包含 Java、Objective-C 和 Cordova/Ionic 的完整 API 参考，请参阅 addClickListener() 推送。

应用内消息点击监听器

使用应用内消息点击监听器处理来自应用内消息按钮和操作的深度链接：

OneSignal.InAppMessages.addClickListener { event ->
  val actionId = event.result.actionId
  // Route based on the action ID (your deep link URI)
}

有关完整 API 参考，请参阅 addClickListener() 应用内。

推送通知

通过以下两种方式之一包含深度链接：

方法	API 属性	行为
启动 URL	`url`（或仅限移动端的 `app_url`）	操作系统直接打开 URL。在 iOS 上，除非抑制，否则会先打开浏览器。
附加数据（推荐）	`data`	URL 传递至您的点击监听器，您完全控制导航。

平台行为

Android：通过应用链接直接打开匹配的 Activity
iOS：打开 Safari，然后打开应用（除非您抑制启动 URL并在点击监听器中处理导航）

有关 url、web_url 和 app_url 定向的详细信息，请参阅 URL、链接和深度链接。

电子邮件

默认情况下，OneSignal 会重写电子邮件链接以进行点击跟踪。这会更改 URL，从而破坏深度链接，因为操作系统不再将域名识别为与您的应用关联域匹配。

在电子邮件中启用深度链接

要保留深度链接，请使用以下方法之一禁用点击跟踪：

仪表板：在电子邮件编辑器中取消勾选 Track link clicks
API：设置 disable_email_click_tracking: true
单链接：使用 Liquid 过滤器 {{ 'https://yourdomain.com/path' | do_not_track_link }} 禁用单个链接的跟踪，同时为其他链接保持启用状态

OneSignal 电子邮件编辑器中 Track link clicks 复选框未勾选

禁用点击跟踪意味着您将失去电子邮件报告中的点击指标。考虑对非深度链接 URL 使用单链接跟踪排除以保留分析数据。

电子邮件深度链接行为

场景	结果
iOS + Safari + 通用链接 + 跟踪已禁用	直接打开应用
iOS + Safari + 通用链接 + 跟踪已启用	打开 Safari，提示打开应用
iOS + 非 Safari 邮件客户端 + 通用链接	应用未安装时打开 App Store
Android + 应用链接 + 跟踪已禁用	直接打开应用
Android + 应用链接 + 跟踪已启用	先打开浏览器，然后打开应用

应用内消息

应用内消息中的深度链接使用点击监听器模式。您在消息编辑器中设置自定义操作标识符，然后在应用代码中处理它。

拖放编辑器

添加按钮或可点击元素
将点击操作设置为 Custom Action ID
将您的深度链接 URI 输入为 Action Name（例如，https://yourdomain.com/promo 或 myapp://promo）

HTML 编辑器

在应用内 JS 库中使用 openUrl 方法从自定义 HTML 触发深度链接。

处理点击

使用应用内消息点击监听器拦截操作并在您的应用中引导用户。

测试深度链接

Android

使用 adb 在不发送通知的情况下测试应用链接：

adb shell am start -a android.intent.action.VIEW \
  -d "https://yourdomain.com/path" \
  com.your.package

验证您的 assetlinks.json 是否可访问：

curl -I https://yourdomain.com/.well-known/assetlinks.json

iOS

使用 Apple 的关联域验证工具验证您的 AASA 文件。您也可以通过以下方式测试通用链接：

将链接粘贴到备忘录应用中
长按链接确认”在 [App] 中打开”选项出现
点击链接验证其是否打开您的应用

通用链接在直接输入 Safari 地址栏时不起作用——必须从其他应用（备忘录、邮件、信息等）中点击。

OneSignal 测试消息

从 OneSignal 仪表板发送测试推送，将深度链接 URL 作为启动 URL 或放入附加数据中
验证通知是否在应用中打开正确的页面
检查您的点击监听器日志，确认已接收到 URL 或数据

故障排除

iOS 深度链接打开 Safari 而非应用

这是最常见的问题。可能原因：

AASA 文件未正确托管 — 验证其位于 https://yourdomain.com/.well-known/apple-app-site-association，Content-Type: application/json 且无重定向
未配置 Associated Domains — 检查 Xcode → Signing & Capabilities → Associated Domains 是否包含 applinks:yourdomain.com
启动 URL 行为 — OneSignal 的 iOS SDK 对 url 属性使用 openURL，会触发浏览器优先行为。改用 data + 点击监听器或抑制启动 URL
在 Safari 中测试 — 通用链接不会从 Safari 地址栏激活，请从备忘录、邮件或其他应用测试。

Android 深度链接打开浏览器

缺少 autoVerify — 确保您的 intent 过滤器包含 android:autoVerify="true"
未找到 assetlinks.json — 验证文件位于 https://yourdomain.com/.well-known/assetlinks.json 且返回 HTTP 200
SHA256 指纹不匹配 — assetlinks.json 中的指纹必须与应用的签名证书匹配。调试版和发布版使用不同的证书。

深度链接在推送中有效但在电子邮件中无效

电子邮件点击跟踪会重写 URL，破坏域名验证。对包含深度链接的电子邮件禁用点击跟踪。

收到深度链接但应用未导航

验证您的点击监听器在应用生命周期早期注册（例如，在 Application.onCreate() 或 AppDelegate.didFinishLaunchingWithOptions 中）
检查 URL 或 action ID 是否与您的路由逻辑期望的相符
在 iOS 上，确认您没有在未抑制启动 URL 的情况下依赖 url——浏览器可能在监听器触发前消耗链接

常见问题

如果未安装应用会发生什么？

使用通用链接（iOS）时，URL 在 Safari 中作为普通网页打开。使用应用链接（Android）时，URL 在默认浏览器中打开。在这两种情况下，您可以将网页配置为重定向至相应的应用商店。自定义 URI 方案（myapp://）在未安装应用时会静默失败或显示错误。

深度链接应使用启动 URL 还是附加数据？

移动深度链接推荐使用附加数据（data），因为它通过点击监听器让您完全控制导航。启动 URL（url）更简单，但在 iOS 上存在限制（浏览器重定向），且不允许自定义路由逻辑。

我可以用用户数据个性化深度链接吗？

可以。使用带有 Liquid 语法的动态 URL 将用户属性、标签或自定义数据注入深度链接 URL。例如：https://yourdomain.com/profile/{{subscription.external_id}}。

我可以使用自定义 URI 方案的深度链接吗？

可以。将您的自定义方案（例如 myapp://screen）设置为启动 URL 或附加数据值。自定义方案适用于推送和应用内消息，但在电子邮件客户端中可能不起作用。如果未安装应用，它们也不提供备用方案。

深度链接是否适用于 OneSignal Journeys？

可以。在 Journey 中配置消息步骤时，将启动 URL 或附加数据设置为您的深度链接。其行为与独立推送或应用内消息相同。

URL、链接和深度链接

启动 URL、UTM 参数、动态 URL 和链接跟踪配置。

移动 SDK 参考

点击监听器和通知事件处理的完整 API 参考。

应用内点击操作

配置应用内消息按钮和元素的点击操作。

移动推送设置

Android 和 iOS 的平台专用推送通知设置。

开始使用和设置

消息渠道

旅程

受众和自定义事件

分析和集成

隐私和安全

​概览

​前提条件

​深度链接类型

​Android 设置（应用链接）

​配置 intent 过滤器

​处理传入 intent

​托管 Digital Asset Links 文件

​iOS 设置（通用链接）

​启用 Associated Domains

​在应用中处理通用链接

​托管 Apple App Site Association 文件

​iOS 启动 URL 行为

​使用 OneSignal SDK 处理深度链接

​推送通知点击监听器

​应用内消息点击监听器

​推送通知

​平台行为

​电子邮件

​在电子邮件中启用深度链接

​电子邮件深度链接行为

​应用内消息

​拖放编辑器

​HTML 编辑器

​处理点击

​测试深度链接

​Android

​iOS

​OneSignal 测试消息

​故障排除

​iOS 深度链接打开 Safari 而非应用

​Android 深度链接打开浏览器

​深度链接在推送中有效但在电子邮件中无效

​收到深度链接但应用未导航

​常见问题

​如果未安装应用会发生什么？

​深度链接应使用启动 URL 还是附加数据？

​我可以用用户数据个性化深度链接吗？

​我可以使用自定义 URI 方案的深度链接吗？

​深度链接是否适用于 OneSignal Journeys？

URL、链接和深度链接

移动 SDK 参考

应用内点击操作

移动推送设置

概览

前提条件

深度链接类型

Android 设置（应用链接）

配置 intent 过滤器

处理传入 intent

托管 Digital Asset Links 文件

iOS 设置（通用链接）

启用 Associated Domains

在应用中处理通用链接

托管 Apple App Site Association 文件

iOS 启动 URL 行为

使用 OneSignal SDK 处理深度链接

推送通知点击监听器

应用内消息点击监听器

推送通知

平台行为

电子邮件

在电子邮件中启用深度链接

电子邮件深度链接行为

应用内消息

拖放编辑器

HTML 编辑器

处理点击

测试深度链接

Android

iOS

OneSignal 测试消息

故障排除

iOS 深度链接打开 Safari 而非应用

Android 深度链接打开浏览器

深度链接在推送中有效但在电子邮件中无效

收到深度链接但应用未导航

常见问题

如果未安装应用会发生什么？

深度链接应使用启动 URL 还是附加数据？

我可以用用户数据个性化深度链接吗？

我可以使用自定义 URI 方案的深度链接吗？

深度链接是否适用于 OneSignal Journeys？