一、iOS 9.0+ 原生实现Universal Link的完整步骤 #

Universal Link的核心是让你的域名和App建立安全关联，下面是一步步的落地流程：

• 1. 开启开发者后台与Xcode的关联域名功能

  • 登录Apple Developer后台，找到你的App ID，勾选Associated Domains选项并保存配置。
  • 回到Xcode，在项目的Signing & Capabilities面板中，添加Associated Domains能力，填入格式为applinks:your-domain.com的域名（替换成你要关联的实际域名）。

• 2. 生成并部署apple-app-site-association文件

  • 创建一个无后缀名的apple-app-site-association文件，内容示例如下：

    {
      "applinks": {
        "apps": [],
        "details": [
          {
            "appID": "你的TeamID.你的BundleID",
            "paths": ["*", "/articles/*"] // 配置允许触发跳转的路径，*为通配符
          }
        ]
      }
    }
    

    注意把你的TeamID和你的BundleID替换成实际值，paths根据业务需求调整，比如只允许商品页跳转就写/products/*。
  • 将这个文件上传到你域名的.well-known目录下（推荐）或根目录，确保能通过HTTPS直接访问（比如https://your-domain.com/.well-known/apple-app-site-association），且没有重定向。

• 3. 处理App内的跳转逻辑

  • 如果你用的是UIKit，在AppDelegate（iOS 12及以下）或SceneDelegate（iOS 13+）中实现对应方法：

    // AppDelegate示例
    func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
        if userActivity.activityType == NSUserActivityTypeBrowsingWeb {
            guard let url = userActivity.webpageURL else { return false }
            // 在这里处理URL跳转，比如根据路径打开对应的页面
            print("收到Universal Link跳转请求: \(url)")
            return true
        }
        return false
    }
    

  • 如果你用SwiftUI，在App结构体中添加如下修饰符：

    @main
    struct YourApp: App {
        var body: some Scene {
            WindowGroup {
                ContentView()
                    .onContinueUserActivity(NSUserActivityTypeBrowsingWeb) { userActivity in
                        if let url = userActivity.webpageURL {
                            // 处理URL跳转逻辑
                        }
                    }
            }
        }
    }
    

二、Branch集成Universal Link失败的排查方案 #

我之前帮很多开发者踩过Branch的Universal Link坑，大概率是某个配置环节遗漏了，你可以按下面的步骤逐一排查：

• 1. 核对Branch后台的配置

  • 登录Branch后台，进入你的项目，检查Link Settings里的Universal Links配置：
    • 关联的域名是否和Xcode中Associated Domains的完全一致？比如Branch提供的xxx.app.link或者你的自定义域名，格式必须是applinks:xxx.app.link。
    • 如果用的是自定义域名，确认你已经把Branch提供的验证文件上传到了域名服务器的对应位置。

• 2. 检查Xcode项目的关键配置

  • 确认Signing & Capabilities中的Team和Branch后台填写的Team ID完全一致，签名配置不能有问题。
  • 检查Info.plist中是否添加了LSApplicationQueriesSchemes，并把Branch的scheme（比如branch）加进去，否则App无法识别Branch的链接。
  • 确保Branch初始化代码正确：在AppDelegate的didFinishLaunchingWithOptions里调用Branch.getInstance().initSession(launchOptions: launchOptions)；iOS 13+还要在SceneDelegate的scene(_:willConnectTo:options:)中重复调用这个初始化方法。

• 3. 验证Universal Link的有效性

  • 在终端执行curl -v https://your-domain.com/.well-known/apple-app-site-association，检查返回的JSON内容是否正确，特别是appID和paths是否匹配你的App。
  • 测试时不要直接在Safari地址栏输入链接，要通过短信、备忘录或其他App点击链接——直接输入地址Safari会默认打开网页，不会触发Universal Link跳转。
  • 用Branch后台的Link Tester工具检查你的链接配置，确认是否能正确关联到你的App。

• 4. 清除缓存再测试

  • Apple会缓存apple-app-site-association文件，刚修改配置后可能需要等待数小时甚至24小时才能生效。你可以尝试删除App、重启设备，再重新安装测试。
  • 模拟器的缓存经常出问题，建议优先用真机测试。

• 5. 检查代码逻辑是否正确

  • 确保在Branch的初始化回调中处理了链接参数：

    Branch.getInstance().initSession(launchOptions: launchOptions) { (params, error) in
        if let error = error {
            print("Branch初始化失败: \(error.localizedDescription)")
            return
        }
        if let params = params {
            print("Branch获取到的跳转参数: \(params)")
            // 根据参数跳转到对应的页面
        }
    }
    

  • 不要忘记在continue userActivity方法中调用Branch的处理方法：

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

内容的提问来源于stack exchange，提问作者shubham bhadauria