iOS中带查询参数的Universal Links无法正常工作问题排查

问题分析 #

你的App Site Association文件中，/register/*仅匹配路径以/register/开头的URL（比如/register/step1），但不匹配路径为/register且带查询参数的URL（比如/register?referral=code）——因为Apple的Universal Links路径匹配仅针对域名后、查询参数前的路径部分，/register?referral=code的路径部分是/register，而非/register/xxx。

解决方案 #

1. 修正App Site Association文件的路径配置 #

更新paths数组，使用/register*通配符覆盖所有以register开头的路径（包括带查询参数的情况）：

{
    "applinks": {
        "apps": [],
        "details": [
            {
                "appID": "K85K7YK4HY.com.send.sprint",
                "paths": [ "/login/*", "/change-password/*","/verify-successful/*","/register*"]
            }
        ]
    }
}

• /register*会匹配：/register、/register?referral=code、/register/invite等所有以/register开头的URL。

2. 处理缓存与文件有效性 #

• 确保文件托管在域名的HTTPS根目录或.well-known目录下，无重定向，且返回的Content-Type为application/json。
• 修改文件后，必须删除App重新安装或重启设备——iOS会缓存App Site Association文件，直接更新服务器文件不会立即生效。

3. 检查App内的链接处理逻辑 #

在App的链接回调方法中，确保正确解析URL的查询参数：

• UIKit项目：在AppDelegate的application(_:continue:restorationHandler:)中处理
• SceneKit项目：在SceneDelegate的scene(_:continue:)中处理

示例代码（Swift）：

func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: @escaping ([UIUserActivityRestoring]?) -> Void) -> Bool {
    guard userActivity.activityType == NSUserActivityTypeBrowsingWeb,
          let url = userActivity.webpageURL else {
        return false
    }
    
    // 解析带查询参数的注册链接
    if url.path == "/register", let components = URLComponents(url: url, resolvingAgainstBaseURL: false),
       let referralCode = components.queryItems?.first(where: { $0.name == "referral" })?.value {
        // 执行对应注册逻辑
        print("获取到邀请码: \(referralCode)")
        return true
    }
    
    // 处理其他路由
    return true
}

4. 正确测试Universal Links #

不要直接在Safari地址栏输入URL（iOS可能不会触发Universal Links），而是通过短信、备忘录、第三方应用等点击链接进行测试。

内容的提问来源于stack exchange，提问作者Vishal Thakur