1. 这套链路到底在解决什么问题先说个实际场景。你们游戏在抖音、微信或者 Safari 里投放了一波买量素材玩家点开落地页点了立即下载。结果你发现个诡异现象安卓用户下载安装后能直接打开游戏并自动领取新手礼包iOS 用户却大多数停留在打开 App这一步就没下文了。再或者你们做了个邀请好友得钻石的活动分享出去的是 URL Scheme 链接结果因为微信内置浏览器拦截、iOS 9 以后的系统弹窗警告转化率低得没法看。这背后其实就是 Deep Link 在 iOS 上的老问题怎么从一个网页/另一个 App 里精准唤醒你的游戏并且把携带参数投递给 Unity 层。很多团队在开发期根本不重视这个等到上线买量、做裂变活动时才临时补课然后被各种奇奇怪怪的系统行为坑得头大。我在这篇文章里会完整梳理一条经过验证的链路从 URL Scheme 和 Universal Links 的选型对比到 Xcode 工程配置再到 iOS 原生层接收和解析参数最后通过 UnitySendMessage 桥接到 C# 层并分发到业务侧。整个过程覆盖了冷启动、热启动、App 未安装三种场景附带我在真实项目里踩过的坑和排查思路。这套东西适合正在给 Unity 手游加导流能力的客户端开发也适合刚接手游戏客户端、被H5 页面怎么唤起游戏这种需求砸脸的策划转岗同学。2. 方案选型为什么两条路都要留2.1 URL Scheme 和 Universal Links本质是两个时代的东西URL Scheme 是 iOS 8 之前就有的老方案形式长这样mygame://open?roomID1001inviterID888它的原理很简单在 App 的 Info.plist 里注册一个自定义协议比如 mygame之后 iOS 系统里任何地方出现 mygame:// 开头的链接系统就直接唤起你的 App。注册方式是在 Xcode 的 Info 标签页里加 URL Types或者在 Info.plist 里写 CFBundleURLTypes。这种方式实现成本极低到今天仍然可用。但它的缺点同样明显任何 App 都可以声明同样的 scheme存在冲突系统弹窗需要用户确认微信内置浏览器对自定义 scheme 基本是直接拦截的这就导致它在中国区社交裂变场景里越来越不顺手。Universal Links 是 iOS 9 推出的替代方案本质是用正规的 HTTPS 链接代替自定义协议。你注册一个标准的 https:// 域名并在 App 里声明支持 applinks: 这个域名同时服务器在指定路径放一个 apple-app-site-association 文件。之后玩家点击 https://game.example.com/invite?roomID1001 时系统先检查该域名是否被 App 认领匹配则直接唤醒 App无弹窗、不拦截而且如果用户没装 App浏览器直接打开你的网页——这对未安装用户的落地页承接太重要了。我自己在项目里的选型结论是两条腿走路。买量归因、活动落地页跳转、分享邀请这些场景全用 Universal Links老版本物料、合作渠道约定的老链接、以及需要兼容 iOS 8 的老机型保留 URL Scheme 兜底。后面章节的代码也是按这个双通道模式写的。2.2 参数链路的关键环节一个都不能断从玩家点击链接到 Unity 业务层拿到参数中间至少经过四个环节链接携带参数被解析出来比如 roomID、inviterID、scene 等原生层Objective-C / Swift从系统回调里拿到 URL 或 NSUserActivity原生层把参数转成字符串通过 UnitySendMessage 调给 C# 层C# 层把字符串解析成 Dictionary 或结构体再转发给具体的业务模块四个环节里面任何一环出错表现都是App 启动了但没进入对应房间或者活动页面没自动弹出来。更麻烦的是这类问题不容易在自测时发现因为你自己从 Safari 点击链接大概率是正常的拿到用户那边就出诡异问题。要理解为什么容易出现这种状况得先说说 iOS 系统在不同启动场景下的回调行为差异。这是整个方案里最容易翻车的地方我单独开一章讲。3. 原生层与系统交互冷启动和热启动姿势完全不同3.1 为什么必须区分冷启动和热启动这里说的冷启动指的是 App 进程完全被杀掉之后用户点击 Universal Link 拉起 App。热启动指的是 App 已经在后台活着用户点击链接把 App 切回前台。iOS 对这两种状态的处理路径不一样如果你只按网上教程里最简化的写法来做大概率冷启动时会丢参数或者参数到达 Unity 的时间晚于业务逻辑初始化。冷启动时Universal Links 的回调走的是func scene(_ scene: UIScene, continue userActivity: NSUserActivity)URL Scheme 冷启动时走的是func scene(_ scene: UIScene, openURLContexts URLContexts: SetUIOpenURLContext)注意这些都是 SceneDelegate 的写法如果你的工程还在用 AppDelegate 管理生命周期则对应方法分别是 application(:continue:restorationHandler:) 和 application(:open:options:)。问题在于冷启动的这段回调发生时间非常早早到 Unity 引擎可能还没初始化完成UnitySendMessage 调过去目标 GameObject 可能还没创建消息直接丢失。我第一次自己写这套逻辑时就是直接拿到 URL 就立刻调用 UnitySendMessage结果日志里能看到原生层收到了链接但 C# 那边始终没反应。查了很久才意识到是回调时序问题。3.2 正确做法原生层做参数缓存等 Unity 上报 ready正确做法是原生层拿到链接后先解析成 JSON 字符串缓存到一个静态变量里。等 Unity 那边通过原生层暴露的接口主动来取或者统一通过 UnitySendMessage 在合适的时机推送过去。我采用的模式是被动拉取 主动推送双保险原生层收到链接后立刻解析参数并存进一个静态内存变量原生层同时向 Unity 发一条推送消息通知有一条待处理的 Deep Link 参数Unity 层收到通知后调用原生层暴露的方法把缓存的参数拉回来如果在原生层收到链接时 Unity 还没完全就绪推送可能失败但缓存里已经有数据了C# 层之后主动 pull 也能拿到这套方案的好处是无论 Unity 初始化耗时多久参数都不会丢只是到达时间会晚一点。3.3 SceneDelegate 与 AppDelegate新工程老工程差异Unity 2020 以后创建的工程默认生成的是 SceneDelegate 模式。老工程可能是 AppDelegate 模式。你写原生代码之前先看下 AppDelegate.swift 里有没有 scene(_:willConnectTo:options:) 方法有就是新架构。另外注意即使走 SceneDelegateapplication(_:open:options:) 在部分情况下也会被调用比如 Safari 直接打开 URL Scheme。网上不少教程只贴了其中一半如果你照着抄发现某种唤情况没收到回调先怀疑是不是写错了生命周期入口。4. 实操环节完整的接入步骤与核心代码4.1 第一步URL Scheme 配置五分钟搞定在 Xcode 选中 target切到 Info 标签页找到 URL Types 区域点击加号。Identifier 填一个唯一标识比如 game-deeplink-schemeURL Schemes 填你的 scheme 名比如 mygameRole 默认 Editor 就行。改动之后 Info.plist 里会自动出现 CFBundleURLTypes 这个 key。一个工程里可以注册多个 scheme但注意 scheme 只能用大小写字母、数字、、-、.、这几个字符且首字符必须是字母。我用过一个带数字开头的 schemeiOS 直接忽略掉调试了半天才发现是命名问题。4.2 第二步Universal Links 的核心三步配置Universal Links 配置比 URL Scheme 麻烦但也没有很多人想的那么复杂。它需要同时完成三边配置Apple 开发者后台、Xcode 工程、服务器文件。Apple 开发者后台这边需要确认 App ID 已经开启了 Associated Domains 能力。Xcode 工程这边在 Signing Capabilities 里加 Associated Domains然后填 applinks: 你的域名比如applinks:game.example.com这里的域名必须是 HTTPS且不能带路径是主域名一级后续子路径由系统去匹配 AASA 文件。服务器那边需要在域名的根目录或者 .well-known 目录下放置一个文件文件名固定叫 apple-app-site-association简称 AASA 文件。文件内容最简形式是这样{ applinks: { apps: [], details: [ { appID: TEAMID.com.example.game, paths: [*] } ] } }注意 appID 是 Team ID 加 Bundle ID用英文句号连接。多人协作时我见过有人把 TeamID 写错拿的是公司名而不是开发者后台那一串字符 ID。确认方法是在开发者后台 Membership Details 里看 Team ID。文件放好后可以用 https://yourdomain.com/apple-app-site-association 直接访问来验证。另外这个文件必须返回有效的 JSON不能有 BOM 头部分服务器默认给文件加了 BOM 就会解析失败。还有一个很坑的点有些 CDN 会拦截 .json 文件Apple 的抓取器不一定走的是标准浏览器 UA结果就是别人的能行你的不行。我用阿里云 OSS 时遇到过这种情况最后是给文件设置了正确的 Content-Type 并关闭了 CDN 自动 gzip 才解决。4.3 第三步核心原生代码设计与实现先写一个统一处理 Deep Link 的原生管理类。我用 Swift 风格写一遍但实际工程如果是 ObjC转换成本很低核心逻辑一样。import Foundation import UnityFramework class DeepLinkManager { static let shared DeepLinkManager() // 缓存最近一次收到的深层链接参数 private var pendingLink: String? // 统一入口从 NSUserActivity 处理 Universal Links func handleUniversalLink(_ userActivity: NSUserActivity) { guard userActivity.activityType NSUserActivityTypeBrowsingWeb, let url userActivity.webpageURL else { return } processURL(url) } // 统一入口处理 URL Scheme func handleURLScheme(_ url: URL) { processURL(url) } private func processURL(_ url: URL) { // 把 URL 转成一个标准 JSON 字符串方便 C# 层解析 let params: [String: String] [ url: url.absoluteString, scheme: url.scheme ?? , host: url.host ?? , path: url.path, query: url.query ?? ] if let data try? JSONSerialization.data(withJSONObject: params, options: []), let jsonString String(data: data, encoding: .utf8) { pendingLink jsonString // 通知 Unity 层有新的 Deep Link 到达 UnitySendMessage(DeepLinkHandler, OnNativeLinkReceived, jsonString) } } // 供 C# 层主动拉取缓存参数用于冷启动时 Unity 初始化晚于原生回调的情况 objc func fetchPendingLink() - String { return pendingLink ?? } // 清空缓存避免同一份参数被重复消费 objc func clearPendingLink() { pendingLink nil } }对应的生命周期入口在 SceneDelegate 中实现func scene(_ scene: UIScene, continue userActivity: NSUserActivity) { DeepLinkManager.shared.handleUniversalLink(userActivity) } func scene(_ scene: UIScene, openURLContexts URLContexts: SetUIOpenURLContext) { guard let firstContext URLContexts.first else { return } DeepLinkManager.shared.handleURLScheme(firstContext.url) }如果是 AppDelegate 的老架构func application(_ application: UIApplication, continue userActivity: NSUserActivity, restorationHandler: escaping ([UIUserActivityRestoring]?) - Void) - Bool { DeepLinkManager.shared.handleUniversalLink(userActivity) return true } func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey: Any] [:]) - Bool { DeepLinkManager.shared.handleURLScheme(url) return true }注意一个细节老架构下如果实现了scene(_:openURLContexts:)则旧的application(_:open:options:)可能不会被调用。反过来也存在兼容问题。最稳妥的做法是只选一套生命周期实现不能两套都留着否则同一个链接回调两次参数就会被消费两次。我在第二版本调整时吃过这个亏玩家分享的房间号总是被重复请求两次服务端记录到同一个邀请码被消费两次排查了半天最后发现是 AppDelegate 和 SceneDelegate 都写了回调。4.4 第四步C# 层接收与解析C# 侧我建了一个专门的脚本叫 DeepLinkHandler挂在场景里一个常驻 GameObject 上。这个 GameObject 必须跨场景保留所以用 DontDestroyOnLoad 处理否则切场景后消息目标就没了。这是另一个容易被忽略的细节UnitySendMessage 的目标对象必须存在且激活否则连错误日志都看不到。using System; using System.Collections.Generic; using UnityEngine; public class DeepLinkHandler : MonoBehaviour { public static DeepLinkHandler Instance { get; private set; } // 业务侧监听的回调 public ActionDeepLinkData onDeepLinkArrived; // 缓存最近一次未消费的链接供业务在合适时机拉取 private string cachedLinkJson; private void Awake() { if (Instance ! null) { Destroy(gameObject); return; } Instance this; DontDestroyOnLoad(gameObject); } // 由 iOS 原生层通过 UnitySendMessage 调用的入口 public void OnNativeLinkReceived(string json) { Debug.Log($[DeepLink] native - csharp: {json}); cachedLinkJson json; TryDispatch(); } // 主动拉取原生层缓存的参数用于冷启动时消息早于 Unity 就绪的情况 public void PullPendingLinkFromNative() { #if UNITY_IOS !UNITY_EDITOR try { string json DeepLinkNativeBridge.FetchPendingLink(); if (!string.IsNullOrEmpty(json)) { cachedLinkJson json; TryDispatch(); } } catch (Exception e) { Debug.LogError($[DeepLink] pull failed: {e.Message}); } #endif } private void TryDispatch() { if (string.IsNullOrEmpty(cachedLinkJson)) { return; } try { var linkData JsonUtility.FromJsonDeepLinkData(cachedLinkJson); onDeepLinkArrived?.Invoke(linkData); // 分发完成后清空本次缓存 cachedLinkJson null; #if UNITY_IOS !UNITY_EDITOR DeepLinkNativeBridge.ClearPendingLink(); #endif } catch (Exception e) { Debug.LogError($[DeepLink] parse failed: {e.Message}); } } } [Serializable] public class DeepLinkData { public string url; public string scheme; public string host; public string path; public string query; }这里的 DeepLinkNativeBridge 是一个 C# 侧 static class用 DllImport 绑定原生导出函数。iOS 原生导出给 Unity 调用的方法是用 extern C 包一层返回一个 C 字符串指针C# 侧用 DllImport 拉取时 Unity 会自动转成 string。4.5 第五步冷启动参数补拉机制现在解释我前面说的双保险。你在 Awake 之后等游戏逻辑初始化到一个合适的时机调用一次 PullPendingLinkFromNative。比如你在启动流程的初始化链末尾或者在用户进入主界面后延迟 0.5 秒拉一次。这样能兜住两类场景原生层收到链接时 Unity 的 DeepLinkHandler 对象还不存在UnitySendMessage 失败消息直接丢了Unity 引擎起来了但 C# 脚本还没有执行到注册回调的时机提前到达的消息被 OnNativeLinkReceived 接住了但业务代码还没准备好只能缓存补拉机制的代码简洁但它是整套方案真正的救火队员。我见过不少团队只实现了 UnitySendMessage 推送这一条路冷启动时参数丢失率能到三成以上用户分享出来的房间链接点进去打开游戏却没人拉他进房体验极度糟糕。4.6 第六步实际参数解析与业务分发上面的 DeepLinkData 只是把整个 URL 拆成了几个字段。你在实际业务里更需要的往往是把 query 里面的 key-value 拆出来。比如链接是https://game.example.com/invite?roomID1001inviterID888fromwechat需要在 C# 层再加一步把 query 字符串解析成 Dictionarystring, string。我自己写了一个简单解析函数不依赖外部库public static Dictionarystring, string ParseQueryString(string query) { var dict new Dictionarystring, string(); if (string.IsNullOrEmpty(query)) { return dict; } string clean query.StartsWith(?) ? query.Substring(1) : query; string[] pairs clean.Split(); foreach (string pair in pairs) { if (string.IsNullOrEmpty(pair)) continue; string[] kv pair.Split(); if (kv.Length 2) continue; string key Uri.UnescapeDataString(kv[0]); string value Uri.UnescapeDataString(kv[1]); dict[key] value; } return dict; }拿到字典之后具体跳转逻辑就简单了。比如取到 sceneroom且 roomID 存在就加载房间场景把 roomID 传给网络层去做加入房间操作取到 sceneactivity就弹活动弹窗取到 scenegift就触发展示礼包领取界面。分发逻辑我建议做成一个独立的 DeepLinkDispatcher不要在 DeepLinkHandler 里写业务判断不然每次加新业务场景都要改动这个常驻脚本容易弄坏链路本身。5. 常见问题与排查技巧实录5.1 Universal Links 完全不起作用优先排查顺序这类问题排查起来很费精力因为你不知道问题出在 Apple 后台、服务器还是 Xcode。按照下面顺序排查可以少走弯路确认 Xcode 里 Associated Domains 是否开启且填写正确格式必须是applinks:你的域名不能带 https:// 前缀确认 AASA 文件能直接访问。在 Safari 地址栏输入https://你的域名/apple-app-site-association能直接看到 JSON 文件才算通过确认 AASA 文件的 appID 拼写TeamID . BundleID 是标准格式。TeamID 错误是最常见的低级错误确认开发者后台里该 App ID 的 Associated Domains 能力已开启确认在真机上测试。Universal Links 在模拟器上的行为不完全一致部分路径在模拟器上表现正常但真机不工作确认 iOS 没有把链接当作普通网页打开。如果你的 App 已安装并支持该域名Safari 右上角会显示 App 名称点击即可打开5.2 参数到达 C# 层是乱码或解析失败常见原因是 URL 里带了中文字符或者特殊符号没有做 URL Encode。在原生层拿到 URL 时尽量直接取原始字符串进行 JSON 序列化而不是自己拼接字段。C# 层解析时用 Uri.UnescapeDataString 统一做一次解码。有些参数本身可能包含 符号比如加密后的签名串这也必须在生成链接时做 encode否则 query 会被拆成多段。我们项目里约定所有参数在业务方生成链接时统一走一个 web 侧和客户端都用同一个规则编码的库绕开各种参数走样问题。5.3 同一参数被触发两次趋势上最典型的原因是 AppDelegate 和 SceneDelegate 都有回调且在单一架构下叠加执行。解决方案前面提到过检查工程里是否同时实现了两套生命周期代理只保留一套。另外如果 Universal Links 中打开了associatedDomains又写了URL Scheme兼容逻辑且链接恰好可以通过两种方式解析到也可能出现双回调。给方案加一个去重机制更保险记录最近一次消费的 URL 字符串及其时间戳5 秒内的重复链接直接忽略。5.4 用户没装 App 时的承接处理Universal Links 在这种场景下会直接跳转网页这正是它的价值你可以让 Safari 打开一个落地页引导用户去 App Store。URL Scheme 没这个能力跳转一个未注册的 scheme 只会弹一个无法打开的提示框。所以纯 URL Scheme 做买量导流时通常还需要配一个 H5 页H5 检测到 App 未安装时通过 App Store 链接引导下载。而 Universal Links 天然有这个承接能力不用额外做 JS 检测。这就是我前面说两条腿走路的价值所在。5.5 冷启动时序问题的统一处理总结我见过很多帖子建议直接在scene(_:continue:)里调用 UnitySendMessage然后怪 Unity 的 C# 侧怎么不支持。这个问题的根源在于把系统回调时间和Unity 引擎初始化完成时间这两个无关联的时间点强行绑定在一起。iOS 系统回调出现在 App 启动最早期此时 Unity 的 main 线程可能还没跑起来UnitySendMessage 要求 Unity 运行时已初始化且目标 GameObject 已存在。原生层能做的只有缓存参数等时机合适再投递。所以补拉机制不是可选项而是必选项。如果某些特殊原因导致补拉时机也晚于玩家预期可以在原生层收到链接后延迟 1 秒再做一次推送多数场景下 Unity 已经就绪。5.6 多域名和多 App 支持有些产品矩阵会有两个以上域名或者多个 App 共用同一个链接规则。Associated Domains 可以配置多个 applinks 条目AASA 文件的 details 数组里可以包含多个 appID 与 paths 组合。比如一个 App 接收两个域名的链接就在 Xcode 加两行AASA 文件里写两个带 appID 的对象。多 App 共享一个域名则反过来AASA 文件里写多个 appIDpaths 按规则分配。实际项目里如果做矩阵产品这一块配置是要提前规划好的否则后面到处切来切去很容易乱。6. 一次完整实战记录从配置到验证我把整套流程按我的实际执行顺序整理成一个清单方便你照着操作。下面这个步骤假设你用 Unity 2021 以上版本创建游戏工程并且使用 Xcode 15 打包。确认你的 App 在 Apple 开发者后台已开启 Associated DomainsXcode 里添加 Associated Domains填入 applinks:game.example.com在服务器根目录放 AASA 文件通过 HTTPS 访问验证Info.plist 添加 URL Schememygame原生层实现 DeepLinkManager 类并接好两个生命周期入口导出 Unity 工程用 Xcode 打开编译安装到测试机在备忘录里输入 https://game.example.com/invite?roomID999inviterID888点击观察 App 是否被拉起查看 Xcode 控制台确认原生层收到链接并输出了 JSON 字符串查看 Unity 侧日志确认 C# 层收到了参数并触发了分发杀掉 App再次从备忘录点击同一个链接冷启动场景再验证一遍在 Unity 编辑器里手动调用 PullPendingLinkFromNative验证补拉机制不报错我在项目里用的是 TestFlight 分发方式给测试人员装包方便。有一点提醒没装正式证书时在真机上测试 Universal Links 可能不生效必须用带开发者证书的包。模拟器部分功能不完整不要省事只用模拟器验证。7. 一些后期扩展思考如果 Deep Link 只是用来传一两个参数上面这套方案足够了。但业务一旦复杂起来比如需要做买量归因、跨渠道 ROI 分析光靠这些还不够。买量归因是典型场景。从广告平台点击到 App Store 下载再到首次启动中间隔着好几个小时的耗时深度链接参数根本不可能原样保留。这种情况一般要接第三方归因平台比如 Adjust、AppsFlyer 这类它们在下载后静默注册时会带上归因参数。如果你自己在做投放数据汇总这个链路必须要尽早规划好而不是等买量开始了再让客户端免费加班。另一个扩展是推送通知跳转。推送场景要的是 App 已经装好但被系统杀死的情况下也能直接进到对应页面。推送服务商的通知 payload 里带上 Deep Link 参数点击通知后 App 被拉起原生层在 didReceive 回调里拿到参数再走同样一条 C# 桥接链路。不同推送厂商的回调时机不一样但参数投递逻辑的大原则一致缓存-等待-投递。游戏内活动的限时跳转也可以用这套机制在运营后台配置一个带参数的活动链接推送给对应玩家群点开就直接进活动界面。省去了玩家自己从主界面手动找入口的步骤。这种场景对路由容错要求更高链接过期或参数错误都要有兜底页面不能直接白屏。8. 我实际开发中踩过的几个坑单独说一次有些细节网上教程很少提但真能让你白干一两天我列在最底下。AASA 文件更新后不是即时生效Apple 的抓取和缓存时间可能长达数小时甚至跨天。所以测试时如果改了文件内容发现不管用先别急着怀疑代码去 https://验证文件本身能否访问然后等一阵子再测。我遇到过改完很快就生效的例子也遇到过半小时后还在用旧配置的场景只能耐心等。URL Scheme 和 Universal Links 的优先级问题。在 iOS 13 及以上如果 App 同时支持 URL Scheme 和 Universal Links且你点击的是一个 scheme 链接系统只会走 scheme 回调不会走 Universal Links。我们的老链接都是 scheme 形式这倒省事。但如果你不小心把新链接也配成了 scheme 形式就得统一改否则用户侧搞不清哪个入口触发哪种行为。代码里如果用 UnitySendMessage 的第二个参数方法名必须保证 C# 方法是 public 且挂载在场景物体上否则原生层调用不会报错但也不会触发任何内容。这是 Unity 桥接老毛病它返回的消息状态码和错误信息都很含糊。建议在原生层加一个简单的日志调用 UnitySendMessage 前打印一条日志C# 侧 OnNativeLinkReceived 进来也打印一条日志两边一对比就知道消息有没有真正到达。如果游戏里做了热更新框架比如 Lua 侧或者 C# 侧的 hybridCLRDeepLink 参数还要考虑对热更代码的兼容。常见做法是先走原生层 C# 层桥接缓存等热更代码初始化完毕后通过 C# 层再拉取一次参数分发给到热更侧。我就碰到过一次因为合入热更框架后初始化链路变长直接把 DeepLink 的拉取时机改到热更初始化完成之后才解决。最后不管你用上面哪一套实现都建议在 QA 阶段建立一个专门的 Deep Link 测试链接集覆盖正常带参跳转、冷启动、热启动、参数缺失、参数格式异常几个维度。配合自动化遍历工具做一轮回归别只靠手点。iOS 系统版本对这类行为的影响比你想的更大不同系统版本的细微差异能改到你怀疑人生。我在 iOS 16 上调通的行为到 iOS 17 上因为 SceneDelegate 的时序变化又被迫做了一次兼容。所以这个测试链接集要持续维护每次大版本升级后跑一遍。