去年做SLG的iOS买量落地页，市场同学丢给我一个链接，要求很简单：用户从Safari里点这个链接，能直接唤起游戏，还要带上邀请人ID和渠道标签。我一开始觉得这事没多难，给App加个URL Scheme，再在C#里监听起来不就行了？结果从埋线到真正调通，前后折腾了两周。Universal Links在微信内置浏览器里完全不生效、冷启动时UnitySendMessage发过去C#收了个寂寞、同一个链接被系统回调了两次导致游戏里连续弹两个邀请面板。这篇把从iOS系统层到Unity C#层的Deep Link唤醒完整流程梳理一遍，包含两条技术路线的选型逻辑、原生层代码和Unity侧代码怎么配合，以及一份可以直接照做的上线验收清单。刚接触这个需求的Unity开发者，或者被Deep Link反复折磨过的老手，都能从这里拿到点实际东西。
1. 链条全览：点击链接到 C# 拿到参数，一共要过几道关卡
先别看代码，把整条链路画在脑子里。
用户在某处看到一条链接，可能是Safari、备忘录、短信、邮件，也可能是微信内置浏览器。点击之后，iOS系统根据链接特征决定路由方式。如果是URL Scheme，系统直接判断有没有App注册了这个协议头；如果是Universal Links，系统会先去下载并校验域名下的apple-app-site-association文件，确认域名所有权后，决定唤起App还是打开网页。
这一步的结果传达到App进程内部。进程不在就通过launchOptions带进启动参数，进程在后台就通过AppDelegate的回调方法传进来。到这里为止，所有信息都在原生层，业务无法直接消费。接下来需要把这些参数转成统一格式，通过桥接层投递给Unity引擎。投递的时机非常关键，引擎没Ready时直接发消息会丢失。
最后C#层拿到参数，经过解析、去重、路由分发，落到具体业务逻辑，比如跳转活动页、弹邀请面板、记录归因渠道。这是完整的六步：点击、系统路由、原生进程、桥接层、C#管理单例、业务消费。
手游和普通App最大的区别在于，原生层只是个壳，业务全在C#。普通App可以在原生层直接做路由跳转，手游不行，Unity场景、UI、资源都没加载时，原生层就算拿到Deep Link也没法处理。所以必须有一个稳定的桥接设计，把原生层的参数安全递到C#层，并处理好时序。
三种典型唤起场景有必要分开理解，它们进入C#层的路径完全不同：
| 场景 | App进程状态 | 系统入口 | 参数传递方式 |
|---|---|---|---|
| 冷启动（URL Scheme） | 未运行 | didFinishLaunchingWithOptions里读launchOptions[UIApplicationLaunchOptionsURLKey] | 原生层缓存，Unity启动后主动取；或等待引擎Ready后补发 |
| 冷启动（Universal Links） | 未运行 | didFinishLaunchingWithOptions里读 UserActivity 字典 | 同上；系统之后可能还会补调continueUserActivity，需去重 |
| 热启动 | 在后台 | openURL或continueUserActivity直接回调 | 引擎通常已Ready，可直接UnitySendMessage |
理解这张表，后面排坑就有方向了。大部分问题都出在冷启动时的时序，以及两种Universal Links入口重复触发上。
2. 路线选择：URL Scheme 与 Universal Links 各自的脾气，手游该主用谁
很多团队第一次接Deep Link都是从URL Scheme开始的，因为它简单，在Xcode里给Target配置一个URL Types，注册一个类似mygame://的协议头就能用。但用深了会发现这方案一身毛病。
URL Scheme最大的问题有三个。第一，所有权无法验证，任何App都能声明相同的协议头，系统弹窗时并不能保证唤起的是你的App。第二，未安装App时，Safari会直接提示“无法打开网页”，体验很差，必须在H5落地页里用定时器炸弹降级跳App Store，这种方式在iOS上时灵时不灵。第三，微信、QQ这类App的内置WebView会拦截大部分URL Scheme，分享出去的链接在微信里点了根本没反应。
Universal Links是Apple后来推的标准方案，核心思路是使用权证文件验证域名所有权。需要在Apple Developer后台给App ID开启Associated Domains，在Xcode的Entitlements文件里添加applinks:yourdomain.com，然后在你自己的HTTPS域名根目录或.well-known目录下放一个apple-app-site-association文件。
{ "applinks": { "apps": [], "details": [ { "appID": "TEAMID.com.yourcompany.yourgame", "paths": ["*"] } ] } }我见过不少项目配这个文件时踩坑，后面专门说。简单对比一下两条路线的核心差异：
| 对比项 | URL Scheme | Universal Links |
|---|---|---|
| 配置成本 | 低，Xcode里填一个协议名 | 高，需要域名、HTTPS、苹果后台、服务器文件 |
| 是否弹确认框 | 系统可能弹“在App Store中打开” | 不弹，直接唤起 |
| 未安装时行为 | 报错或需要降级处理 | Safari正常打开你的网页 |
| 微信内置浏览器 | 大部分被拦 | 直接失效 |
| 安全性 | 协议可被其他App抢占 | 校验域名所有权，防抢 |
手游现在的主流做法是两者都配，以Universal Links为主，URL Scheme兜底。Universal Links负责Safari、备忘录、邮件这些系统场景，体验干净；URL Scheme作为微信OpenSDK跳转等特定场景的补位。毕竟国内社交分享绕不开微信，Universal Links在微信内置浏览器里完全使不上劲。
另外要注意，如果项目接了AppsFlyer或Adjust这类归因SDK，它们的深层链接配置同样依赖这两个能力。先跟第三方SDK文档核对一遍，避免配置文件互相覆盖。我见过有团队自己写的aasa文件和AppsFlyer的配置指向同一个域名，路径匹配规则一个用*一个用具体路径，最后互相干扰，排查了两天。
针对纯Unity出包的项目，还有一个很容易忽略的点：如果你是用Unity生成Xcode工程再手动改配置，那每次重新出包配置都会被冲掉。正确做法是写一个PostProcessBuild脚本，在Xcode工程生成后自动添加Associated Domains、URL Scheme和Info.plist字段，把配置固化到打包流程里。这个后面验收清单部分再展开。
3. 原生层落地：AppDelegate 两个入口加一个缓存队列，打通到 Unity
原生层在整个方案里的角色是翻译官：把iOS系统给的URL或NSUserActivity，转成C#能消费的JSON字符串，并且在正确的时机投递过去。
先看AppDelegate里的两个入口。URL Scheme和Universal Links走的是不同方法，必须都实现，然后在内部统一交给同一个桥接单例处理，绝不能在两个方法里各写一套业务。
// AppDelegate.m - (BOOL)application:(UIApplication *)application openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey, id> *)options { if (url) { NSString *json = [[DeepLinkBridge shared] serializeURL:url]; [[DeepLinkBridge shared] enqueuePayload:json]; } return YES; } - (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray<id<UIUserActivityRestoring>> * _Nullable))restorationHandler { if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) { NSURL *url = userActivity.webpageURL; if (url) { NSString *json = [[DeepLinkBridge shared] serializeURL:url]; [[DeepLinkBridge shared] enqueuePayload:json]; } } return YES; }还要处理冷启动。App进程没启动时，两种链接的信息都藏在didFinishLaunchingWithOptions里。URL Scheme对应UIApplicationLaunchOptionsURLKey，Universal Links对应UIApplicationLaunchOptionsUserActivityDictionaryKey，取出后同样塞进桥接缓。
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { NSURL *url = launchOptions[UIApplicationLaunchOptionsURLKey]; if (url) { NSString *json = [[DeepLinkBridge shared] serializeURL:url]; [[DeepLinkBridge shared] enqueuePayload:json]; } NSDictionary *userActivityDict = launchOptions[UIApplicationLaunchOptionsUserActivityDictionaryKey]; NSUserActivity *userActivity = userActivityDict[UIApplicationLaunchOptionsUserActivityKey]; if ([userActivity.activityType isEqualToString:NSUserActivityTypeBrowsingWeb]) { NSURL *webURL = userActivity.webpageURL; if (webURL) { NSString *json = [[DeepLinkBridge shared] serializeURL:webURL]; [[DeepLinkBridge shared] enqueuePayload:json]; } } return YES; }这里有一个很多教程不会提的细节：用Universal Links冷启动时，系统在调用didFinishLaunchingWithOptions之后，可能还会补调一次continueUserActivity。也就是说同一个链接存在被投递两次的可能。C#层必须做去重，或者原生层在处理时打上一个时间戳标记。我习惯在桥接层记录最近一次处理的URL和Unix时间，1秒窗口内相同URL直接丢弃。
URL解析也有讲究。很多人直接取url.query再拆分，遇到+号、中文编码、多个&时会出各种怪问题。正确做法是用NSURLComponents的queryItems，系统帮你处理解码：
- (NSString *)serializeURL:(NSURL *)url { NSURLComponents *components = [NSURLComponents componentsWithURL:url resolvingAgainstBaseURL:NO]; NSMutableDictionary *params = [NSMutableDictionary dictionary]; for (NSURLQueryItem *item in components.queryItems) { if (item.value) { params[item.name] = item.value; } } NSMutableDictionary *payload = [NSMutableDictionary dictionary]; payload[@"route"] = components.path ?: @""; payload[@"params"] = params; NSData *data = [NSJSONSerialization dataWithJSONObject:payload options:0 error:nil]; return [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding]; }接下来是整个人流程里最关键的一步：UnitySendMessage的调用时机。Unity引擎从启动到C#脚本可接收消息，中间有一段初始化时间。如果原生层在didFinishLaunchingWithOptions里拿到URL后立刻调UnitySendMessage，这条消息大概率丢失，而且不会报错，排查起来非常隐蔽。
我的做法是加一个缓存队列，引擎未Ready时先把消息存起来，等Unity通知原生层“我准备好了”再统一补发：
// DeepLinkBridge.h #import <Foundation/Foundation.h> @interface DeepLinkBridge : NSObject + (instancetype)shared; - (void)enqueuePayload:(NSString *)json; - (void)setUnityReady; - (BOOL)isUnityReady; @end // DeepLinkBridge.m #import "DeepLinkBridge.h" #import <UnityFramework/UnityFramework.h> @interface DeepLinkBridge () @property (nonatomic, strong) NSMutableArray<NSString *> *pendingPayloads; @property (nonatomic, assign) BOOL unityReady; @end @implementation DeepLinkBridge + (instancetype)shared { static DeepLinkBridge *instance; static dispatch_once_t onceToken; dispatch_once(&onceToken, ^{ instance = [[DeepLinkBridge alloc] init]; instance.pendingPayloads = [NSMutableArray array]; }); return instance; } - (void)enqueuePayload:(NSString *)json { if (self.unityReady) { [self sendToUnity:json]; } else { [self.pendingPayloads addObject:json]; } } - (void)setUnityReady { self.unityReady = YES; NSArray *pending = [self.pendingPayloads copy]; [self.pendingPayloads removeAllObjects]; for (NSString *json in pending) { [self sendToUnity:json]; } } - (void)sendToUnity:(NSString *)json { const char *objectName = "DeepLinkManager"; const char *methodName = "OnDeepLinkReceived"; const char *param = [json UTF8String]; UnitySendMessage(objectName, methodName, param); } @endC#侧在场景加载完成后，通过一个空的GameObject调用原生层的setUnityReady，触发补发。这一步做对了，冷启动参数丢失这个问题就算彻底根治了。
4. C# 层接收与分发：冷启动、热启动、参数落地一个不能少
原生层的活干完，轮到Unity侧的接收端。C#层要做的事包括：接收JSON、缓存未消费的参数、区分冷启动和热启动、去重、路由分发到具体业务。
我习惯在一个挂到DontDestroyOnLoad空物体上的DeepLinkManager单例里集中处理。代码结构大致如下：
using System; using System.Collections.Generic; using UnityEngine; public class DeepLinkManager : MonoBehaviour { public static DeepLinkManager Instance { get; private set; } // 冷启动兜底：静态字段，确保场景切换、管理器重建时参数不丢 private static string _pendingRawPayload; private readonly Queue<DeepLinkPayload> _payloadQueue = new Queue<DeepLinkPayload>(); private bool _coreReady; private void Awake() { if (Instance != null) { Destroy(gameObject); return; } Instance = this; DontDestroyOnLoad(gameObject); if (!string.IsNullOrEmpty(_pendingRawPayload)) { OnDeepLinkReceived(_pendingRawPayload); _pendingRawPayload = null; } } public void OnDeepLinkReceived(string json) { DeepLinkPayload payload = DeepLinkPayload.Parse(json); if (payload == null) return; if (_coreReady) { Dispatch(payload); } else { _payloadQueue.Enqueue(payload); CoreReadyEvent += DispatchPending; } } public void NotifyCoreReady() { _coreReady = true; DispatchPending(); } private void DispatchPending() { while (_payloadQueue.Count > 0) { DeepLinkPayload payload = _payloadQueue.Dequeue(); Dispatch(payload); } } private void Dispatch(DeepLinkPayload payload) { // 去重：同一路由 1 秒内只分发一次 if (IsDuplicate(payload)) return; Debug.Log($"[DeepLink] Dispatch route={payload.Route} params={payload.RawParams}"); // 这里根据 payload.Route 分发到活动页、邀请、归因等业务模块 } }这里有个经验：_pendingRawPayload静态字段非常关键。因为Unity场景切换时，如果DontDestroyOnLoad没保住，或者热更新框架重载了程序集，Manager会被重建。静态字段在程序域存续期间不会丢失，比实例字段稳得多。
关于JSON解析，要提醒一个Unity老坑：JsonUtility对字典类型支持很差，不能直接解析params这种嵌套JSON对象。两个方案：一是包Newtonsoft.Json，这是最省事的；二是让原生层把参数拍平成route=xxx&key=value的格式再透传。我目前生产环境走的是Newtonsoft，因为业务要的字段结构越来越复杂，拍平到后面没法维护。
冷启动和热启动在C#侧看起来是同一套代码，但因为时序不同，要注意各自的场景：
冷启动时，Unity引擎初始化阶段原生层缓存了参数，等C#侧准备好了再补发。这个回调到OnDeepLinkReceived时，游戏可能刚进主场景，也可能还在启动画面。不能一收到就立刻切场景，得等核心模块初始化完成。我在代码里用一个_coreReady标记配合队列，逻辑上叫“延迟到安全时机分发”。
热启动时，App从后台被唤起，Unity引擎还在运行，消息能立刻到达。但这时候玩家可能正卡在战斗结算界面，或者停在某个UI弹窗前。直接弹个邀请面板把当前流程打断，体验非常差。建议在Dispatch加一个UI路由拦截和优先级机制，比如战斗场景下只做数据记录，不做界面跳转，切到主城后再消费。
关于去重，除了原生层的时间戳去重，C#层最好也做一道。原因很简单：有些第三方SDK会在启动时主动重放一次Deep Link，加上系统的补调，同一参数进三次都正常。我用一个字典记最近投递的URL和到达时间，时间差小于2秒的直接丢弃。
分发到业务模块时也有一点要提醒：不要在主线程里做重逻辑。路由分发本身很快，但如果路由要拉活动配置、请求服务器、加载资源，一定要丢到业务层的异步流程里。有些团队图省事，在分发处直接同步加载场景，卡顿明显，在线上的反馈很糟糕。
5. 真实踩坑记录：aasa 不生效、微信内打不开、回调两次、参数丢半截
这一节全是我实际踩出来的坑，基本覆盖了接手Deep Link需求后一周内可能遇到的所有问题。
坑一：apple-app-site-association文件配了但就是不生效。这个文件有三个常见的无声杀手：服务器返回的Content-Type不是application/json而是text/plain或application/octet-stream，iOS不认；文件位置放错，应该放在域名根目录或.well-known下面；域名做了重定向，比如跳转到www子域，或者CDN节点切换了域名。验证方式是在Safari直接访问https://yourdomain.com/apple-app-site-association，看能不能原样看到JSON、响应头Content-Type对不对。如果返回的是HTML错误页，那肯定不行。
坑二：iOS 13之后的Safari“打开”横幅不出来。系统对Universal Links的处理机制决定了，如果用户之前在Safari里手动打开过同一个域名下的链接，系统会记住这个偏好，之后不再自动唤起App，而是停留在网页里。测试时特别容易碰到：第一次测还有横幅，第二次就没了，以为是自己改坏了。解决方式：换一个没访问过的新路径，或者清掉Safari历史记录再测。
坑三：微信内置浏览器里Universal Links直接失效。微信的WebView不遵循Safari对Universal Links的唤起行为，所以分享出去的活动页在微信里打开，点击“打开游戏”按钮大部分情况没反应。标准解法是先引导用户跳到Safari，或者调用微信OpenSDK的拉起能力，这需要配置微信开放平台那边的Universal Links，逻辑跟普通H5点击不一样。很多团队上线后收到“微信里打不开”的客诉，基本都栽在这里，建议提前写进FAQ。
坑四：同一个Universal Links被回调两次。前面提到进程不在时，系统可能先走didFinishLaunchingWithOptions再补调continueUserActivity。玩家侧的表现就是游戏里连续弹两个一样的邀请面板，后台日志看是两个一模一样的Deep Link到达。原生层做1秒时间窗去重，或者C#层再做一道，都能解决。
坑五：参数变成一串乱码或者后半截没了。链接里有中文、emoji、&、#这类字符时，直接在url.query字符串上自己切割很容易出事。用NSURLComponents的queryItems取解码后的值是最稳的。原生层序列化成JSON时还要注意，如果参数本身有引号或者换行，直接用字符串拼接会破坏JSON结构，必须用NSJSONSerialization。
坑六：UnitySendMessage静默失败。原生层调了UnitySendMessage("DeepLinkManager", "OnDeepLinkReceived", "xxx")，C#侧什么都没收到，而且Xcode控制台没有任何报错。原因无非三种：GameObject名字写错、方法名写错、方法不是public。还有一种是Unity引擎还没Ready，消息发出去没人接。我们工程里在原生侧封装了一个带返回值的方法，由C#侧主动拉取缓存，而不是单纯靠推，等于多了一条保底通道。
坑七：落地页没安装App时跳转App Store的逻辑不干净。用URL Scheme做主投递时，未安装的场景会弹出“无法打开网页”，用户体验极差。H5工程通常用定时器检测App是否被唤起，超时后跳App Store。但iOS的Safari对页面切后台的判断很飘，定时器经常误判。Universal Links天然解决这个问题：未安装时直接在Safari打开你的网页，你可以在网页里放App Store下载按钮，不需要炸弹降级。所以现在的买量落地页都要求域名下的Universal Links能正常返回页面，而不是被App“截胡”。
这些坑我整理成了一张速查表，接到告警时按图索骥特别有用：
| 现象 | 大概率原因 | 排查入口 |
|---|---|---|
| 指定路径点击无效 | aasa没配好或Content-Type错误 | Safari直接访问aasa文件 |
| Safari没“打开”横幅 | 用户偏好记忆 | 换新路径或清历史 |
| 游戏内重复弹窗 | 双入口回调两次 | 原生层时间窗去重 |
| 中文参数乱码 | 直接切割query字符串 | 改用NSURLComponents |
| 微信里打不开 | 微信WebView不支持Universal Links | 引导Safari打开 |
| C#未收到消息 | UnitySendMessage时机或名称问题 | 原生层缓存+主动拉取 |
6. 上线前验收清单：一件件核对，晚上才睡得着
按我现在的习惯，每次给Unity手游接完iOS Deep Link，上线前会从头到尾过一遍下面这些项，缺哪项补哪项。
首先是域名和服务器配置。确认apple-app-site-association文件能通过HTTPS直接访问，Content-Type正确，路径匹配规则符合预期。对应的App ID已经在Apple Developer后台开启了Associated Domains。Xcode工程的Entitlements里applinks:前缀的域名正确，和证书里的Team ID拼出来的appID和aasa文件里的记录完全一致。
接着验证原生层。用一个测试链接分别在三种场景下打点：App完全退出后点击、App在后台点击、App在前台点击。每种都要看AppDelegate是否进入对应入口，enqueuePayload是否被调用，UnityReady之前消息是否被正确缓存。这一步可以在Xcode控制台打日志验证，断点打在sendToUnity:方法里，能直观看到消息有没有发出去。
然后是Unity层。需要在启动流程里确认两件事：DeepLinkManager的Awake没有丢失静态缓存，NotifyCoreReady在核心模块初始化完成后被调用。然后分别测冷启动和热启动的路由分发，确认去重逻辑生效，重复点击不会重复弹窗。把参数里的中文、特殊字符都塞一遍测试，确认解析没有乱码。
还有一个容易漏的环节：如果游戏接入了热更新或者程序集重载，DeepLinkManager的重建时序会变化，静态字段保底就是为这种场景准备的。在热重载后再发一条测试深链，确认消息不丢。
最后是渠道矩阵测试。把链接分别放到Safari、备忘录、短信、邮件、微信、QQ、企业微信里点一遍。每一条记录唤起是否成功、参数是否完整。微博、抖音这类第三方App的内置浏览器也值得测一下，它们的行为跟微信可能不完全一样。测试结果整理成一张兼容表，产品、运营各留一份，后续客诉时能迅速判断是不是已知问题。
打包自动化这块也建议一起固化。我之前手改Xcode工程被冲掉过太多次，现在用PostProcessBuild脚本自动完成三件事：往Info.plist写入URL Scheme、往Entitlements写Associated Domains、把Unity工程里的UnityAppController替换成处理了Deep Link的版本。出包后自动执行一遍检查脚本，把关键配置项的值打出来。这样每次提审前都能批量核对，不用靠人工记。
最后再分享一个小习惯：我会在原生层留一个环境开关，打开后所有Deep Link链路日志打到Xcode控制台，从系统回调、原生解析、队列缓存一直到UnitySendMessage每一行都有。C#侧同样留一个类似的宏开关，把接收、解析、分发三条链路全打出来。上线前的真机联调把这个开关打开跑一遍，快速定位问题；正式包里关掉，避免日志刷屏。这套链路日志救过我很多次，尤其当QA报告“某个渠道的深链偶尔丢参数”时，两边日志一对，问题基本当场就能圈定。
