深度链接和延迟深度链接(DDL)故障排除指南 - FAQ

可能的原因：

• 深度链接处理程序未在应用中完全实现
• 应用未读取来自 Singular SDK 的已解析深度链接
• DDL 的前提条件未完全满足

需检查的内容：

1. 直接测试深度链接(不经过 Singular 链接)。
2. 确认您的 SingularLinkHandler 已实现并正确读取：
   • getDeeplink()
   • isDeferred()
   • getPassthrough()
3. 验证 DDL 已启用 ( should_index_ddl = true )。

如果深度链接在直接测试时有效，但通过 Singular 链接时无效，那么问题几乎总是出在您应用的导航逻辑中——而非链接本身。

在 iOS 上(Universal Links)： 这通常意味着 Universal Link 配置不完整。请检查：

• Team ID 和 iOS App Scheme 已在 Singular 中正确设置
• Associated Domains 已在 Xcode 中添加
• AASA 文件存在且包含正确的链接 ID

开发/QA 构建提示： 如果您在开发或 QA 构建上进行测试，您的设备可能尚未获得最新的 AASA 文件。请尝试在重启设备后重新安装应用。

在 Android 上： 这通常表明 intent filter 配置错误。请检查：

• App Links SHA256 指纹已正确设置(如果使用 App Links)
• assetlinks.json 可在您的 Singular 域名下访问
• intent filter 与 Singular Apps 页面上配置的内容一致

如果以上所有内容都没有问题但问题仍然存在，那么问题很可能出在您的深度链接处理程序逻辑中。

典型错误： "Safari 无法打开该页面，因为地址无效。"

发生这种情况的原因：

• Safari 在处理针对新用户的某些 Universal Links 方面存在已知限制
• _force_redirect=1 存在于链接中

这是预期行为 ，流程应按如下方式继续：用户看到错误 → 点击"确定" → 系统提示打开 App Store。

可能的原因： 透传参数( _p )未正确附加或 URL 编码。

最佳实践：

• 在将 JSON 值添加到链接之前，请始终对其进行 URL 编码
• 从以下位置读取透传数据： singularLinkParams.passthrough

透传数据在深度链接和延迟深度链接 两者 中均可用，因此如果缺失，问题几乎总是出在编码或检索方面。

发生这种情况的原因： 一旦 Singular 链接使用深度链接创建，如果应用已安装，它将始终尝试打开应用。这在操作系统级别受到控制：

• iOS：由 AASA 文件管理
• Android：由 SHA256 证书关联管理

事后无法覆盖此设置。 如果您想要一个始终将用户发送到商店的链接，则需要从一开始就在 不带 深度链接的情况下创建它。

根本原因： 设备上启用了 Apple 的 iCloud Private Relay。

它破坏 DDL 的原因： Private Relay 会在点击和安装之间更改 IP 地址，因此点击 IP 和安装 IP 不匹配——这会破坏概率归因。

建议：

• 测试时禁用 iCloud Private Relay
• 改用 Chrome 或其他非 Safari 浏览器进行测试

发生这种情况的原因： 该链接配置了深度链接，当应用已安装时，它始终优先于着陆页。

关键规则： 应用 + 深度链接始终优先于着陆页。只有在应用确实无法打开时，社交着陆页才会出现。

可能的原因： 您用于测试的追踪链接被双重 URL 编码，导致设备或 Singular 无法解析它。

发生这种情况的原因： 当包含深度链接参数(例如 _dl 或 _p )的 Singular Link 从某些环境(例如 Slack、电子邮件客户端或消息工具)复制时，URL 可能会被第二次编码。例如：

• 正确(单次编码)： https://yourapp.sng.link/Xxxxx/yyyy?_dl=myapp%3A%2F%2Fstory&_p=%7B%22story_id%22%3A%22BananaStory%22%7D
• 无效(双重编码)： https%3A%2F%2Fyourapp.sng.link%2FXxxxx%2Fyyyy%3F_dl%3Dmyapp%3A%2F%2Fstory%26_p%3D%7B%22story_id%22%3A%22BananaStory%22%7D

双重编码的链接将无法正确重定向，由此产生的安装或点击可能不会出现在 Singular 的归因日志中。

需检查的内容：

1. 始终直接从 Singular Manage Links 页面复制追踪链接——而不是从可能已重新编码 URL 的 Slack 消息或其他工具复制。
2. 验证链接以 https:// 开头(而非 https%3A%2F%2F )。如果您在 URL 的最开头看到百分号编码的字符，则整个链接已被双重编码。
3. 使用 URL 解码工具(例如 urldecoder.org )检查链接是否解码为有效的 Singular Link 格式。
4. 将链接解码一次，并使用生成的 URL 进行测试。

问题： 从 Samsung Internet 浏览器点击 Singular 链接的用户可能会被重定向到 Google Play Store——即使应用已安装且链接配置正确。

我们观察到的情况：

• Google Chrome： 链接按预期打开应用
• Samsung Internet： 同一链接却重定向到 Play Store

无论链接是直接在 Samsung Internet 中打开，还是嵌入网页并从中点击，都可能发生这种情况。

根本原因： Samsung Internet 有一个内置的隐私设置，默认阻止应用被外部打开。

• 启用时： 浏览器会阻止深度链接并回退到 Play Store
• 禁用时： 链接会正确打开应用，与 Chrome 的行为一致

我们已确认这是 浏览器设置问题，而非 Singular 配置问题 ——Android App Links 和 SHA-256 指纹均已正确设置，一旦关闭此设置，链接行为在各处都保持一致。

这对您意味着什么： 一些 Samsung 用户即使在应用已安装的情况下，也可能会落在 Play Store 上，具体取决于他们各自的浏览器隐私设置。这在我们这边无法通过编程方式控制。

如果您想引导受影响的用户： 您可以告知他们 Samsung Internet 可能默认阻止打开应用的链接，并且在 Samsung Internet 的隐私设置中启用"打开外部应用"(或类似选项)将恢复预期的应用内体验。

发生这种情况的原因： 当用户从某些社交媒体应用内浏览器中点击 Singular Link 时，浏览器可能会阻止标准的 iOS Universal Links 或 Android App Links。因此，应用可能会成功打开，但深度链接未传递给应用，导致用户落在默认主屏幕而非预期目的地。

为解决此问题，Singular 提供了 社交着陆页 ，这是一个中间着陆页，有助于保留深度链接并可靠地将用户路由到正确的应用内目的地。

支持哪些平台？

社交着陆页支持：

• iOS
• Android(Facebook、Facebook Messenger、Facebook Messenger Lite 和 Instagram 应用内浏览器)
• 合作伙伴链接，包括：
  • Facebook Web
  • TikTok Ads Web
  • X (Twitter) Web
  • Snapchat Web

如何启用社交着陆页？

在创建或编辑 Singular Link 时，在 Social Link Settings 下启用 Landing Page 。

此选项适用于：

• Custom Source 链接
• Mobile Web-to-App 链接
• 合作伙伴链接

我应该何时使用社交着陆页？

每当您通过受支持的社交平台开展 web-to-app 广告系列时，请启用社交着陆页。它有助于确保用户被引导至预期的应用内内容而非应用的主屏幕，从而改善深度链接体验并减少由社交媒体应用内浏览器导致的失败深度链接。