做手游的都知道拉新靠买量回流靠唤醒。而 iOS 端的 Deep Link就是那条把用户从 Safari、广告页、活动 H5 重新拽回游戏 App 的绳子。很多人以为这不就是配个 URL Scheme 的事但真做到 Unity 工程里就会发现从链接点击到 C# 层拿到参数中间隔着系统回调、原生桥接、消息时机三层坑单是“热启动丢参数”就够人折腾半天的。这篇东西不聊虚的直接讲完整链路URL Scheme 和 Universal Links 怎么选、原生侧怎么配、参数怎么从 Objective-C 一路安全送到 C# 层以及在真机调试时最容易踩的坑。适合正在做游戏买量归因、老玩家召回、活动直达页面的 Unity 开发者也适合刚接手手游 SDK 对接的客户端工程师。1. 为什么手游需要 Deep Link两条路线怎么选1.1 URL Scheme 与 Universal Links 的核心差别iOS 上的 Deep Link 技术路线说穿了就两条。一是 URL Scheme早期方案二是 Universal Links通用链接iOS 9 之后苹果主推的方案。URL Scheme 本质上是给 App 注册一个自定义协议头比如gameact://。当 Safari 或其他 App 尝试打开gameact://open?item1001这个地址时系统会检测到有 App 注册了这个 scheme然后拉起对应应用。Universal Links 则是用标准的 HTTPS 链接来做。你在网页上点击https://www.game.com/promo?item1001系统会去校验这个域名下挂载的apple-app-site-association文件校验通过后直接打开 App而不是打开网页。两者在体验上的差异很明显维度URL SchemeUniversal Links链接形式自定义协议头非 http/https标准 HTTPS 链接未安装时的表现报错“打不开网页”正常打开对应网页是否询问用户会弹窗确认是否打开不弹窗直接打开域名校验无需校验需要关联域名并用 AASA 文件校验被系统封禁风险其他 App 可随意注册同一 scheme不会冲突归因准确性一般更高手游项目里我通常建议两条都做URL Scheme 保底Universal Links 作为主路径。原因后文细说。1.2 手游场景下哪种方案更适合主路径如果你只是做个活动页跳转游戏URL Scheme 绝对够用配起来也快。但只要是涉及买量归因、老用户召回就得把 Universal Links 扶正。原因有三点。第一Android 生态早就是 link 满天飞投放素材里的链接都是 http/httpsiOS 侧如果用 URL Scheme很多落地页要单独维护一套custom://协议渠道侧的配置工作量直接翻倍。第二Universal Links 没装 App 时会优雅降级到网页用户可以看到 H5 引导页而不是一个冰冷的“无法打开”。第三归因平台比如 AppsFlyer、Adjust对 Universal Links 的归因成功率明显高于 URL Scheme因为域名是你的链路可信度高。URL Scheme 也不是没用它最大的价值是作为“兜底”。Universal Links 偶尔会有缓存失效、首次安装不识别之类的问题这种时候 URL Scheme 反而能救场。像支付宝、微信这种体量的 App至今依然保留 URL Scheme道理一样多一条路多一分唤醒成功率。2. 原生侧配置Info.plist 与 Associated Domains2.1 URL Scheme 的注册信息配置在 Unity 工程里URL Scheme 的配置不在 C# 里写而是在最终导出的 Xcode 工程里的 Info.plist 中。手动改一次容易但每次出包都要手动改就太折磨了所以我用 Unity 的OnPostProcessBuild自动注入。先看手动配置长什么样keyCFBundleURLTypes/key array dict keyCFBundleURLName/key stringcom.yourgame.promo/string keyCFBundleURLSchemes/key array stringgameact/string /array /dict /arrayCFBundleURLName可以理解成这个 URL 类型的标识名建议用反域名格式比如com.company.product。CFBundleURLSchemes里填的就是你的协议头这里要特别注意两点。Scheme 千万不能用纯数字开头系统会直接忽略掉。另外 Scheme 是全局唯一的隐患点任何 App 都能注册相同的 scheme如果你注册了gameact别人也能注册gameactiOS 在唤起时会优先找最近打开的 App这个行为不可控。2.2 Universal Links 的域名关联与 AASA 文件Universal Links 的配置分两步。第一步在 Apple Developer 后台把域名加进 App 的 Associated Domains 里格式是applinks:www.game.com。第二步在域名根目录挂一个apple-app-site-association文件这个文件没有后缀名内容是一个 JSON。AASA 文件的标准结构如下{ applinks: { appids: [ ABCDE12345.com.yourgame.promo ], components: [ { #: promo/*, exclude: false, comment: 匹配 promo 路径下的所有链接 } ] } }appids里填的是 Team ID 加 Bundle ID 的组合。很多人卡在这一步AASA 文件上传了就是不生效结果一看appids里只写了 Bundle ID忘了前缀的 Team ID。组件的匹配规则也是重点。#键对应 URL 的 path 部分*支持通配。exclude为 true 表示不匹配常用于排除某些路径。还有一点AASA 文件必须通过 HTTPS 访问不能用 HTTP且证书要有效。2.3 Unity 工程自动注入配置脚本手动配置只适合第一次验证真正出包必须让 Unity 自动处理。我通常在建一个PostProcessBuild.cs挂在Editor文件夹下using UnityEditor; using UnityEditor.Callbacks; using UnityEditor.iOS.Xcode; public class PostProcessBuild { [PostProcessBuild(1)] public static void OnPostProcessBuild(BuildTarget target, string path) { if (target ! BuildTarget.iOS) { return; } string projectPath path /Unity-iPhone.xcodeproj/project.pbxproj; PBXProject project new PBXProject(); project.ReadFromFile(projectPath); #if UNITY_2019_3_OR_NEWER string targetGuid project.GetUnityMainTargetGuid(); #else string targetGuid project.TargetGuidByName(Unity-iPhone); #endif project.AddCapability(targetGuid, PBXCapabilityType.AssociatedDomains); project.WriteToFile(projectPath); string plistPath path /Info.plist; PlistDocument plist new PlistDocument(); plist.ReadFromFile(plistPath); PlistElementArray urlTypes plist.root.CreateArray(CFBundleURLTypes); PlistElementDict dict urlTypes.AddDict(); dict.SetString(CFBundleURLName, com.yourgame.promo); PlistElementArray schemes dict.CreateArray(CFBundleURLSchemes); schemes.AddString(gameact); plist.WriteToFile(plistPath); } }AddCapability会自动往 Entitlements 文件里写入 Associated Domains但关联域名本身不会自动添加。你还需要在 Assets 下建一个 Entitlements 文件或者继续在脚本里操作。我习惯直接把 entitlements 文件放到Assets/Entitlements下手动填好applinks:www.game.com然后在 Xcode 里勾选。导出后务必手动检查一次Build Settings 里的 Associated Domains 是否勾选Entitlements 文件是否生效Info.plist 里是否有 URL Types。这个检查花不了两分钟但能省掉后面一上午的排查。3. 原生到 C# 层的参数透传桥接最关键的一步3.1 为什么参数不能直接用网页跳转方式处理链接被系统识别后iOS 会把它交给AppDelegate的某个方法。在这个环节之前一切都还是 iOS 原生层面的事。而 Unity 游戏逻辑跑在 Mono 或 IL2CPP 里两边像两个国家需要一座桥。这座桥就是 UnitySendMessage。Objective-C 通过这个方法可以调用 C# 层 GameObject 上挂的脚本方法完成参数投递。在动手之前得先统一参数格式。iOS 回调给你的 URL 是原始的可能长这样gameact://open?item1001typegiftts1712345678或者 Universal Links 传递过来的https://www.game.com/promo?item1001typegiftts1712345678我不会直接把完整 URL 丢给 C#而是统一解析成 key-value 然后以 JSON 字符串传递。原因很简单C# 层直接再去解析 URL 虽然可行但 Unity 的Uri类在解析某些编码后的参数时会出幺蛾子比如中文参数被不断重复转码。原生侧解析一次JSON 化C# 侧收到就是一串干净的字符串。3.2 冷启动与热启动调用时机的差异这里是我踩坑最多的地方。所谓冷启动是 App 完全被杀掉后通过 Deep Link 拉起来。此时 Unity 引擎还在初始化过程中UnitySendMessage要求目标 GameObject 已经存在否则消息发过去会直接丢失。热启动则是 App 在后台活着通过 Deep Link 唤起。这时引擎完全就绪UnitySendMessage可以立即送达。Cold Start 场景下最简单的做法是延迟发送。我在 OC 侧会做个延迟重试每 0.5 秒检查 Unity 是否就绪最多重试 5 次。3.3 OC 侧解析与消息投递实现我要在AppDelegate里接收两种链接。旧版本写法是分开的iOS 13 之后需要同时处理 SceneDelegate 的情况但 Unity 导出工程默认仍以 AppDelegate 为主这里以 AppDelegate 为例#import UnityFramework/UnityFramework-Swift.h - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionaryUIApplicationOpenURLOptionsKey,id *)options { return [self handleDeepLink:url]; } - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSUserActivity * _Nullable))restorationHandler { if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) { return [self handleDeepLink:userActivity.webpageURL]; } return NO; } - (BOOL)handleDeepLink:(NSURL *)url { NSString *parameterString [self convertURLToJSONString:url]; [self sendMessageToUnity:parameterString]; return YES; }convertURLToJSONString这个方法建议把 query 展开成可变字典再序列化成 JSON。核心代码- (NSString *)convertURLToJSONString:(NSURL *)url { NSMutableDictionary *params [NSMutableDictionary dictionary]; if (url.scheme) { params[scheme] url.scheme; } if (url.host) { params[host] url.host; } if (url.path) { params[path] url.path; } NSURLComponents *components [NSURLComponents componentsWithURL:url resolvingAgainstBaseURL:NO]; for (NSURLQueryItem *item in components.queryItems) { params[item.name] item.value; } NSData *data [NSJSONSerialization dataWithJSONObject:params options:0 error:nil]; return [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]; }然后sendMessageToUnity就是那个带延迟重试的函数- (void)sendMessageToUnity:(NSString *)message { [self trySendMessage:message retryCount:0]; } - (void)trySendMessage:(NSString *)message retryCount:(int)retryCount { if (retryCount 5) { return; } if ([UnityFrameworkGetInstance() appController] nil || ![[UnityFrameworkGetInstance() appController] unityIsReady]) { dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(0.5 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{ [self trySendMessage:message retryCount:retryCount 1]; }); return; } UnitySendMessage(DeepLinkManager, OnDeepLinkReceived, [message UTF8String]); }先说明一下Unity 导出 Xcode 工程后UnityFrameworkGetInstance和unityIsReady是从UnityFramework-Swift.h里暴露的。老版本 Unity2019 之前直接用UnityGetAppController也行但新版本强烈建议走 UnityFramework 接口否则冷启动时序会判断不准。3.4 C# 侧接收与分发处理C# 侧的工作分两块。第一块是接收原生消息丢到主线程执行第二块是解析 JSON触发业务逻辑。挂载对象名必须和方法名完全匹配UnitySendMessage的第一个参数填的是 GameObject 名称不是脚本名。我在场景中建了一个常驻的DeepLinkManager节点挂上DeepLinkManager.csusing System; using System.Collections.Generic; using UnityEngine; public class DeepLinkManager : MonoBehaviour { public static event ActionDictionarystring, string OnDeepLinkArrived; private static bool _pendingEventsPending false; private static readonly Queuestring PendingMessages new Queuestring(); private readonly object _lock new object(); public void OnDeepLinkReceived(string json) { lock (_lock) { if (!_pendingEventsPending) { _pendingEventsPending true; ExecuteOnMainThread(json); } else { PendingMessages.Enqueue(json); } } } private void ExecuteOnMainThread(string json) { DispatchQueue(); } private void DispatchQueue() { // 这里放在 Update 里逐帧出队 } private void Update() { lock (_lock) { while (PendingMessages.Count 0) { string json PendingMessages.Dequeue(); ParseAndDispatch(json); } } } private void ParseAndDispatch(string json) { try { var dict MiniJSON.Json.Deserialize(json) as Dictionarystring, object; var result new Dictionarystring, string(); foreach (var kv in dict) { result[kv.Key] kv.Value null ? : kv.Value.ToString(); } OnDeepLinkArrived?.Invoke(result); } catch (Exception ex) { Debug.LogError([DeepLink] 参数解析失败: ex.Message); } } }上面的代码是个简化骨架重点是搞清楚两点。第一不是所有场景都适合用Update轮询出队但它是 Unity 主线程执行的最稳妥方式。原生回调本身就是主线程理论上可以直接执行但为了保险我仍然建议入队后延迟到Update里处理避免在引擎未完全初始化的极小时间窗内出问题。第二MiniJSON是 Unity 的简单 JSON 库可以直接用。如果你项目已经引入了 Newtonsoft.Json用哪个都无所谓核心是把参数还原成 C# 可用的键值字典。业务侧接收消息就是订阅事件void OnEnable() { DeepLinkManager.OnDeepLinkArrived OnDealWithDeepLink; } void OnDisable() { DeepLinkManager.OnDeepLinkArrived - OnDealWithDeepLink; } private void OnDealWithDeepLink(Dictionarystring, string payload) { if (payload.TryGetValue(item, out string itemId)) { // 跳转活动页、发放礼包、进入指定关卡等 } }4. 常见问题排查实录4.1 Universal Links 不生效的常见原因Universal Links 不生效是排查频率最高的问题我列一份自己常用的排查顺序排查点操作验证结果AASA 文件是否可访问Safari 打开https://www.game.com/apple-app-site-association能看到 JSON 内容AASA 文件是否合法用 JSON 校验工具检查格式无语法错误Team ID 是否写全检查appids是否TeamID.BundleID与开发者后台一致Associated Domains 是否配置Xcode 里检查 entitlements 文件包含applinks:www.game.comiOS 是否缓存旧配置每次改动后在系统设置里重装 App重新验证这里有个系统行为iOS 对 AASA 文件的缓存策略比较保守首次拉取之后可能在长时间内不再重新请求。测试链接不生效不要马上断言配置错了先在真实设备上删掉 App、重启、再安装很多缓存问题在这一步就消失了。还有一种情况你在 Safari 地址栏直接输入链接它会先尝试打开网页而不是 App。这正常Universal Links 的要求是点击链接触发纯手动输入地址不算标准场景。4.2 参数在冷启动时丢失或过早回调这是我被玩家反馈最多次的问题。症状是玩家点了链接游戏打开了但礼包没发。查日志发现OnDeepLinkReceived在 C# 层压根没被调用过或者调用太早业务侧监听事件的脚本还没注册上。第一个坑GameObject 不存在。UnitySendMessage 的 target 必须在场景里而且名字要一字不差。注意大小写deepLinkManager和DeepLinkManager是两个名字。最简单的验证方法是在OnDeepLinkReceived第一行加Debug.Log如果 Unity 控制台完全没有输出问题就在消息没送达或者名字错了。第二个坑回调早于业务监听。游戏启动后场景加载、热更下载、SDK 初始化是一大串逻辑Deep Link 参数到了但你的礼包模块还没初始化。解决方法是把参数先暂存起来等到业务模块就绪后再取。我在DeepLinkManager里加了一个静态属性LastPayload业务侧随时可以拉取。第三个坑IL2CPP 下字符串编码。原生传来的是 UTF8 C 字符串C# 侧作为string接收正常但如果中间经过了 Objective-C 的NSString转char*且没指定编码中文参数会出现乱码。稳妥做法是原生侧用[message UTF8String]C# 侧默认按 UTF-8 处理别用Default编码。4.3 真机调试的实用技巧Xcode 的 Console 是调试 Deep Link 的第一阵地。链接点击后AppDelegate里是否收到回调、UnitySendMessage是否执行这些日志一目了然。如果你想知道 iOS 系统到底有没有识别链接有一个快速验证方法在备忘录里输入链接长按如果弹出“在 xxx 中打开”选项说明这个链接已经被系统登记并能唤起 App。这是设备级的链路验证绕过了你的代码可以快速区分是“系统没识别”还是“代码没处理”。命令行调试也有一个小技巧在 Mac 终端执行xcrun simctl openurl booted gameact://open?item1001这个命令可以在模拟器上直接唤起 App测试冷启动热启动都很方便。不过模拟器对 Universal Links 的支持不完整最终验证还是要上真机。5. 工程化落地的几点经验5.1 参数标准化是设计的第一步Deep Link 参数天生不稳定。链接从广告平台出来被各种落地页包裹、跳转某些渠道还会在回调 URL 里加追踪参数。如果 C# 层依赖固定参数名渠道侧一多就容易打架。我落地项目的习惯是定义一份文档把 item、type、ts 这类核心字段固定下来渠道侧只允许追加参数不允许改动语义。C# 侧接收到参数后统一做类型校验和默认值兜底宁可缺失不报异常。5.2 日志是排查 Deep Link 问题的唯一依靠Deep Link 链路长从系统到原生再到 Unity任何一段出问题都可能导致静默失败。工程里必留三段日志原生收到链接原文、UnitySendMessage 发出的 JSON、C# 层解析后的 key-value 列表。这三处日志完整的情况下用户反馈“点链接没反应”我们能在五分钟内定位到是哪一环出了问题。5.3 多场景兼容别只盯着 iOS现在很多游戏项目是 Unity 双端一起出iOS 走了 Universal LinksAndroid 也大概率要接 App Links。两端在参数设计上如果能统一后台上传链接的同事就省心很多。这里不展开 Android 的具体实现但参数 JSON 化的思路是共通的。最后分享一个日常被忽视的小细节。每次改了 AASA 文件或者 entitlements 配置别急着在开发者后台里反复看先用 Safari 直接访问 AASA 的 URL 确认文件内容正确、可访问再上真机验证。很多“改了不生效”的问题其实是从第一步就把文件放错了位置或者格式不对。这行干久了你会明白Deep Link 调试的大多数时间都花在排除各种低级错误上链路本身并不神秘系统回调、协议匹配、消息投递每一步都有章可循。把日志埋好把方案选对剩下的事情就是按照流程逐步验证。