iOS深度链接故障：点击链接无法打开应用并展示指定内容

一、先确认基础深度链接配置正确性 #

Universal Links（通用链接）配置 #

• 苹果开发者后台启用Associated Domains，添加applinks:你的域名
• 服务器根目录或.well-known文件夹放置apple-app-site-association文件，格式如下：

  {
    "applinks": {
      "apps": [],
      "details": [
        {
          "appID": "你的团队ID.应用BundleID",
          "paths": ["*", "/指定路径/*"]
        }
      ]
    }
  }
  

• Xcode中，在Signing & Capabilities里添加Associated Domains，填入对应域名

自定义URL Scheme（作为Universal Links降级方案） #

在Info.plist中添加配置：

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>你的自定义scheme（如myapp）</string>
    </array>
  </dict>
</array>

二、应用内处理链接跳转逻辑 #

不管是Universal Links还是自定义Scheme，都需要在应用启动/唤醒时捕获链接并解析：

iOS 13+ 使用SceneDelegate #

func scene(_ scene: UIScene, continue userActivity: NSUserActivity) {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else { return }
    handleDeepLink(url: url)
}

iOS 12及以下 使用AppDelegate #

func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool {
    handleDeepLink(url: url)
    return true
}

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard let url = userActivity.webpageURL else { return false }
    handleDeepLink(url: url)
    return true
}

统一解析与页面跳转 #

写通用方法处理URL参数并导航到目标页面：

func handleDeepLink(url: URL) {
    let components = URLComponents(url: url, resolvingAgainstBaseURL: true)
    let referralCode = components?.queryItems?.first(where: { $0.name == "referral" })?.value
    let targetPath = components?.path

    // 根据路径和参数跳转对应页面
    if targetPath == "/product" {
        // 导航到商品页，传入参数
    } else if targetPath == "/invite" {
        // 导航到邀请页，用referralCode追踪推荐来源
    }
}

三、实现类似branch.io的动态跳转逻辑 #

需要一个服务器托管的中间跳转页，逻辑如下：

1. 用户点击深度链接先跳转到该页面
2. 通过JS尝试唤起应用，失败则自动跳转App Store
   示例JS代码：

function openAppOrStore() {
    const universalLink = "https://你的域名/目标路径?referral=xxx";
    const schemeLink = "myapp://目标路径?referral=xxx";
    const appStoreLink = "https://apps.apple.com/cn/app/你的应用ID";

    // 优先尝试Universal Links
    window.location.href = universalLink;
    // 1.5秒后检查页面是否仍可见，是则跳转App Store
    setTimeout(() => {
        if (document.visibilityState === "visible") {
            window.location.href = appStoreLink;
        }
    }, 1500);

    // 同时尝试自定义Scheme作为补充
    setTimeout(() => {
        window.location.href = schemeLink;
    }, 500);
}

window.onload = openAppOrStore;

四、推荐用户追踪实现 #

• 深度链接中携带唯一推荐码参数（如?referral=user123）
• 应用内解析参数后，将其与当前用户绑定（存储到本地或上传后端）
• 用户完成注册、下单等目标行为时，上报推荐码与行为数据到后端完成追踪

常见排查点 #

• 检查apple-app-site-association文件是否可直接访问，无重定向且JSON格式正确
• 用真机测试，模拟器可能存在Universal Links缓存问题
• 重置缓存：设置→Safari浏览器→清除历史记录与网站数据，或卸载重装应用

内容的提问来源于stack exchange，提问作者Harsh Bardolia