概述

为 Singular 追踪链接实现深度链接和延迟深度链接，让用户从广告活动无缝跳转到你应用中的特定页面。

深度链接是一个可点击的链接，用于打开应用内部的特定内容。需要支持两种场景：

深度链接（直接）： 用户已经安装了应用。他们点击一个 Singular Link，应用直接打开到正确的内容。
延迟深度链接（DDL）： 用户尚未安装应用。他们点击链接、从商店安装，首次打开时应用仍会将他们引导到目标内容。

在 SDK 集成中，Singular 会自动处理其中的大部分工作。在服务器到服务器（S2S）集成中，设备上没有 SDK，因此你的团队需要负责两项额外的工作：将应用接收到的深度链接传递给 Singular，以及读取 Singular 返回的延迟深度链接并引导用户。这两项都通过 SESSION 端点进行：

GET https://s2s.singular.net/api/v1/launch

本文的定位： 本指南是 S2S 文档套件的一部分。有关端点基础知识、身份验证和常用参数，请参阅 S2S 基础知识中心。下文中使用的深度链接参数（ openuri 、 ddl_enabled 以及响应字段）在 SESSION 端点 API 参考中有定义。

资源：深度链接常见问题 | Singular Links 常见问题

三项配置一览

步骤	作用	发生位置
1. 应用层级	使 Singular Links 能够打开你的应用（iOS Universal Links / Android App Links），并定义深度链接的目标位置。	Apple/Google 配置 + Singular 控制面板（Apps & Manage Links）
2. SESSION（入站）	Singular 接收深度链接结果。你的应用通过 `openuri` 参数将打开的链接传递上来。	SESSION 请求 → Singular
3. SESSION（出站）	应用接收 DDL 结果。Singular 在响应中返回延迟深度链接，你的服务器将其转发给应用。	SESSION 响应 → 你的服务器 → 应用

步骤 1：应用层级配置

在任何深度链接生效之前，Singular Links 必须被操作系统识别为 iOS Universal Links 和 Android App Links，这样点击链接才能打开你的应用而不是浏览器。传统的 URI 应用 scheme 作为后备方案受支持。

请按照标准设置指南完成各平台的详细步骤，然后确认下面的每一项都已完成。详细步骤见 Singular Links 前提条件和如何配置深度链接。这里的检查清单为你提供了所需的顺序以及团队最常遗漏的要点。

配置检查清单：

添加链接子域名 ，在 Attribution > Manage Links > Manage Link Domains 中（例如 yourbrand.sng.link ）。这是你的 Singular Links 使用的主机。
iOS — Universal Links： 为 applinks:yourbrand.sng.link 启用 Associated Domains 能力，然后将你的 App Prefix / Team ID 从 Apple Developer Portal 复制到 Settings > Apps > [iOS app] > Show Advanced Settings 。可选择在 Xcode 中将 app-scheme 后备方案注册为 URL Type。
Android — App Links： 生成你的 SHA-256 签名指纹（生产环境使用 Play Console，调试使用 keytool ），为你的 Singular 域名向 AndroidManifest.xml 添加一个 autoVerify intent filter，然后将指纹粘贴到 Settings > Apps > [Android app] > Show Advanced Settings > App Links SHA256 fingerprints 。
定义深度链接 ，在 Attribution > Manage Links > Create Link 中（见下面的字段映射）。

重要： 在 iOS 上，如果跳过 Team ID 这一步，每个 Singular Link 都会重定向到 App Store，深度链接将无法工作。这是构建正确的链接却无法打开应用的最常见原因。

映射 Manage Links 的重定向字段

当你创建链接时，三个重定向字段直接对应到后面在 API 中使用的三个深度链接概念：

Manage Links 中的字段	含义
如果应用未安装，则前往	后备重定向，通常是你的 App Store / Play Store 页面。
如果应用已安装，则前往	深度链接，即为现有用户提供的应用内目标位置（步骤 2）。
安装后，直接前往	延迟深度链接，即为新用户在安装后提供的目标位置（步骤 3）。通常与深度链接的值相同。

开发者交接： 工程团队应提供每个平台的深度链接 scheme 以及目标 URL 列表（例如 myapp://autumnfashion ）。

步骤 2：SESSION（入站）— 将深度链接发送给 Singular

当应用从 Singular Link 打开时，捕获完整的打开 URL，并在 SESSION 请求的 openuri 参数（经过 URL 编码）中发送给 Singular。这是 Singular 将会话归因到该链接并报告深度链接结果的方式。使用 Singular Links 时必填。

深度链接打开时始终发送 SESSION。 每当应用通过深度链接、Universal Link 或 App Link 打开时，都要发送一个填充了 openuri 的 SESSION 请求，即使该会话在正常情况下会被认为仍处于活动状态（也就是说，无论超时窗口如何）。

URL 上携带的 Singular Link 参数

参数	含义
`_dl`	深度链接值（iOS 和 Android 使用相同的目标位置）。
`_ios_dl` / `_android_dl`	各平台不同时使用的平台专用深度链接值。
`_p`	透传参数，一个经过 URL 编码的 JSON 或纯字符串，用于自定义路由。

在应用中捕获打开 URL

应用需要处理程序代码来接收打开 URL，并将其转发给你的服务器，以便包含在 SESSION 请求中。

iOS (Swift)：

// Custom scheme / direct opens
func scene(_ scene: UIScene,
           openURLContexts URLContexts: Set<UIOpenURLContext>) {
    guard let url = URLContexts.first?.url else { return }
    SessionReporter.report(openURL: url.absoluteString)
}

// Universal Links arrive via:
func scene(_ scene: UIScene,
           continue userActivity: NSUserActivity) {
    if let url = userActivity.webpageURL {
        SessionReporter.report(openURL: url.absoluteString)
    }
}

Android (Kotlin)：

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    intent?.data?.let { uri ->
        SessionReporter.report(uri.toString())
    }
}

override fun onNewIntent(intent: Intent?) {
    super.onNewIntent(intent)
    intent?.data?.let { SessionReporter.report(it.toString()) }
}

发送带有 openuri 的 SESSION 请求

从你的服务器，将捕获到的 URL（经过 URL 编码）作为 openuri 包含进来：

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "openuri=myapp://home/page?queryparam1=value1"

短链接解析

如果用户打开的是缩短后的 Singular Link，还要发送 singular_link_resolve_required=true 。Singular 会返回展开后的长链接，以便你解析深度链接和透传值。

示例响应：

{
  "status": "ok",
  "resolved_singular_link": "https://myapp.sng.link/A59c0/nha7?_dl=myapp%3A%2F%2Fdeeplink&_ddl=myapp%3A%2F%2Fdeferred-deeplink&_p=passthroughvalue"
}

动态透传参数

如果你的组织为某个链接配置了动态透传，深度链接 URL 会包含 _p 参数，其中带有经过 URL 编码的 JSON 字符串或非结构化字符串，用于内容路由。参阅动态透传参数。

参考： SESSION 端点 API 参考（深度链接参数）。

步骤 3：SESSION（出站）— 将延迟深度链接转发给应用

对于点击链接后才安装应用的用户，Singular 会在安装后的首个会话的 SESSION 响应中返回延迟深度链接。你的服务器必须将该值转发回应用，以便应用能够引导用户。

在首个会话中请求 DDL

在安装后的第一个 SESSION 请求中，添加以下两个参数：

参数	用途
`install=true`	将此标记为全新安装后的第一个会话。
`ddl_enabled=true`	告诉 Singular 应用期望在响应中收到延迟深度链接。

示例 SESSION 请求（install + DDL enabled）：

curl -G https://s2s.singular.net/api/v1/launch \
  --data-urlencode "a=<SDK key>" \
  --data-urlencode "p=Android" \
  --data-urlencode "i=com.yourcompany.app" \
  --data-urlencode "aifa=<GAID>" \
  --data-urlencode "n=YourAppName" \
  --data-urlencode "install=true" \
  --data-urlencode "ddl_enabled=true"

读取响应并转发给应用

如果安装来自携带延迟深度链接的追踪链接，Singular 会返回：

响应字段	如何处理
`deferred_deeplink`	深度链接地址。转发给应用，并将用户引导到匹配的内容。
`deferred_passthrough`	附加到链接上的任何透传参数。用于个性化。

示例 SESSION 响应：

{
  "deferred_deeplink": "myapp://deferred-deeplink",
  "status": "ok",
  "deferred_passthrough": "passthroughvalue"
}

必须处理响应。 在纯 S2S 设置中，Singular 无法直接与设备通信。你的后端必须解析 SESSION 响应，并将 deferred_deeplink （以及 deferred_passthrough ）转发回客户端应用，在那里你的路由代码会将用户引导到正确的页面。如果不转发响应，延迟深度链接将会静默失败。

测试与验证

延迟深度链接： 在未安装应用的设备上，点击链接并确认你会落到商店页面。安装并打开后，应用应显示目标内容。
直接深度链接： 在已安装应用的情况下，点击链接并确认应用直接打开到目标内容。
SESSION 顺序： 确认在任何事件之前收到单个 SESSION，并且 SESSION 响应被解析并传递给客户端（对延迟深度链接至关重要）。
openuri 已填充： 验证深度链接打开时会发送一个已设置 openuri 的 SESSION，无论超时窗口如何。

测试指南：测试你的集成 | 测试追踪链接

服务器到服务器 — 深度链接指南

概述

三项配置一览

步骤 1：应用层级配置

映射 Manage Links 的重定向字段

步骤 2：SESSION（入站）— 将深度链接发送给 Singular

URL 上携带的 Singular Link 参数

在应用中捕获打开 URL

发送带有 openuri 的 SESSION 请求

短链接解析

动态透传参数

步骤 3：SESSION（出站）— 将延迟深度链接转发给应用

在首个会话中请求 DDL

读取响应并转发给应用

测试与验证