ios moblink integration (iOS MobTech MobLink 集成 skill)

面向 iOS 工程的 MobTech MobLink 集成 skill。默认先扫描工程，优先使用 CocoaPods，以最小改动完成场景还原依赖接入、Info.plist 配置、隐私合规、getMobId 制作场景、恢复代理回调和项目内说明文档落地。

iOS MobLink 集成 Skill

当用户希望把 MobTech MobLink 集成到 iOS 工程，或者排查已有 MobLink 接入问题时，使用本 skill。

适用场景

当用户提到以下任一主题时，使用本 skill：

• iOS MobLink 集成
• MobTech MobLink 接入
• iOS 深度链接 / Deeplink
• iOS 场景还原
• mob_linksdk_pro
• MobLink Info.plist 配置
• MobLink 隐私合规
• uploadPrivacyPermissionStatus 调用时机
• getMobId / MLSDKScene / MobLink setDelegate:
• IMLSDKWillRestoreScene / UIViewController+MLSDKRestore
• MobLink 扩展业务主动控制器
• 帮我在 iOS 项目里增加场景还原能力
• 帮我把 MobLink 接进现有 iOS 工程

如果用户问题明确与 iOS MobLink 接入、工程配置、场景制作、场景还原、隐私合规或扩展业务采集控制有关，应优先使用本 skill。

输出语言

• 默认使用中文与用户沟通
• 代码、配置键名、类名、命令名保持原文
• 回答尽量短，先给结论，再给动作

官方资料

优先使用以下线上资料，不依赖本机资料路径：

• MobTech 文档中心
• MobLink 产品简介
• 创建应用流程
• MobLink 后台与项目配置
• iOS 集成指南
• iOS SDK API
• iOS 合规指南
• MobLink 扩展业务功能设置
• Web 集成
• App Store Connect 后台隐私数据项配置
• 其它 App 数据采集主动控制器配置
• MobLink 隐私政策

已确认的官方事实

以下信息已经可作为执行依据，不需要再猜测：

• 官方支持手动导入 SDK 和 CocoaPods 两种集成方式
• 默认开发环境要求为 Xcode 9.1.0+、iOS 8.0+
• CocoaPods 依赖为 pod 'mob_linksdk_pro'
• 手动导入需要 MobLinkPro.framework 与 MOBFoundation.framework
• 工程需要链接 libsqlite3、libz1.2.5、libc++
• Info.plist 需要配置 MOBAppKey 与 MOBAppSecret
• 严格合规方案要求默认 plist 中增加 MOBNetLater = 2
• uploadPrivacyPermissionStatus 是 MobSDK 业务起点，必须在用户同意隐私政策后、使用 SDK 能力前调用
• 可通过 uploadPrivacyPermissionStatus:onResult: 回传隐私授权结果
• 可通过 uploadPrivacyPermissionStatus:privacyDataDelegate:onResult: 同时接入 MOBFoundationPrivacyDelegate 主动控制器
• 需要在 App 启动链路中调用 [MobLink setDelegate:self] 设置场景恢复代理
• 制作场景使用 MLSDKScene 和 [MobLink getMobId:result:]
• iOS 3.0.0 以上推荐使用 [MLSDKScene sceneForPath:params:]
• 需要恢复的控制器可实现 UIViewController+MLSDKRestore 中的 initWithMobLinkScene:
• 场景还原回调 IMLSDKWillRestoreScene:Restore: 一旦实现，必须执行 restoreHandler
• MobLink iOS 扩展业务支持地域精细化运营、脱敏设备唯一性标识、网络链路选择与优化
• 扩展业务主动控制器通过自定义类遵守 MOBFoundationPrivacyDelegate 实现

文档未明确，需向用户确认

以下内容在当前资料里没有被稳定、明确地定义，禁止猜：

• 是否支持 Swift Package Manager
• 是否需要 Privacy Manifest 或额外苹果隐私文件
• 用户项目应该使用 CocoaPods 还是已存在的手动导入体系
• 用户是否本次就要配置 URL Scheme、Universal Link 或 Associated Domains
• MobLink 后台里的 iOS 页面名称、渠道标识、路径与业务控制器映射关系
• 项目中应该在哪个业务入口制作 MobId 和拼接分享链接
• Web 端是否已经集成 MobLink JS 模块

如果缺这些信息且会阻塞安全修改，必须明确写：

文档未明确，需向用户确认

默认执行策略

• 默认集成方式：CocoaPods
• 默认先扫描工程，再给改动方案
• 默认优先复用工程已有隐私弹窗、App 启动入口和路由体系
• 默认先生成最小 Excel 模板，再等用户填写
• 默认不在 Excel 中收集 Bundle ID、Target 名称、Info.plist 路径、入口类名，因为这些应由扫描工程自动推断
• 默认不在 Excel 中收集业务控制器路径、分享入口、Web 落地页和恢复路由位置，这些必须结合工程扫描后逐步确认
• 默认不在 Excel 中收集扩展业务主动控制器配置；仅在 README 中保留官方文档链接，真正需要时再串行确认
• 默认不主动启用扩展业务主动控制器；仅当用户明确需要限制位置、IDFA、IDFV、WiFi、IP 等采集时才进入该分支
• 默认不运行 pod install、xcodebuild 或其他会改动依赖状态的命令，先展示计划，再执行
• 默认不把 Pods/ 提交进项目；如项目未忽略 Pods/，补充 .gitignore，保留 Podfile 与 Podfile.lock
• 一次只问用户一个阻塞问题

执行流程

严格按以下顺序推进：

1. 先扫描工程，再判断接入方式。
2. 先生成或读取配置模板，再确定静态配置。
3. 先展示最小改动计划，再修改文件。
4. 依赖安装前先征求确认。
5. 基础 SDK 与隐私合规完成后，再进入场景制作和场景还原业务接线。
6. 完成后补项目内说明文档。

第一步：扫描工程

优先扫描以下内容：

• .xcodeproj / .xcworkspace
• Podfile
• Podfile.lock
• Package.swift
• AppDelegate / SceneDelegate / SwiftUI @main
• Info.plist
• 现有 URL Scheme、Associated Domains、Universal Link 配置
• 现有路由、分享、网页落地页、深链处理代码
• 隐私政策弹窗或同意回调位置
• Objective-C / Swift / 混编类型，以及是否已有 Bridging Header
• 是否已有 MobLink、MobLinkPro、MOBAppKey、MOBAppSecret、MOBNetLater、uploadPrivacyPermissionStatus
• .gitignore 是否忽略 Pods/
• .xcworkspace 是否包含 contents.xcworkspacedata

推荐命令：

• rg --files -g '*.xcodeproj' -g '*.xcworkspace' -g 'Podfile' -g 'Podfile.lock' -g 'Package.swift' -g '*Info.plist' -g '*.entitlements' -g '.gitignore'
• rg --files -g '*.m' -g '*.h' -g '*.mm' -g '*.swift'
• rg -n 'MobLink|MobLinkPro|MLSDKScene|IMLSDKRestoreDelegate|IMLSDKWillRestoreScene|UIViewController\\+MLSDKRestore|MOBAppKey|MOBAppSecret|MOBNetLater|uploadPrivacyPermissionStatus|CFBundleURLSchemes|com.apple.developer.associated-domains|SWIFT_OBJC_BRIDGING_HEADER'

扫描后先给一段简短结论，至少包含：

• 当前工程依赖方式
• 当前入口结构
• 当前代码语言形态：Objective-C / Swift / 混编
• Swift 工程是否已有 Bridging Header
• 是否已有 MobLink 残留
• 是否已经有隐私同意链路
• 是否已有深链、Universal Link 或路由体系
• CocoaPods 状态：是否有有效 Podfile、Podfile.lock、Pods/、*.xcworkspace/contents.xcworkspacedata
• 下一步是生成模板还是读取已有 MobLink_iOS_Config.xlsx

第二步：生成并读取配置模板

2-1 模板生成

如果 {path} 下还没有 MobLink_iOS_Config.xlsx：

1. 运行本 skill 目录下的 assets/generate_excel_template.py
2. 将生成的 assets/MobLink_iOS_Config_Template.xlsx 复制到 {path} 下
3. 在 {path} 下命名为 MobLink_iOS_Config.xlsx

2-2 向用户说明填写项

必须明确告诉用户只需要填写这些最小字段：

• appKey
• appSecret
• needUniversalLink

同时明确说明以下内容不需要填表：

• Bundle ID
• Target
• Info.plist 路径
• App 启动入口类名
• 隐私弹窗类名
• 场景恢复代理方法位置
• 业务控制器路径
• getMobId 调用入口
• Web 落地页地址
• 扩展业务主动控制器配置

其中工程信息应由 Agent 扫描后推断；业务落点、页面路径和 Web 配置必须在基础接入完成后按单个阻塞问题逐步确认。

2-3 配置校验

读取 MobLink_iOS_Config.xlsx 后，至少校验：

• appKey：必填，按字符串处理，不做数值推断
• appSecret：必填，按字符串处理，不做数值推断
• needUniversalLink：必须明确是 是 / 否

如不合法，列出具体问题并要求用户修正，不要继续改工程。

第三步：扫描后推断工程接入点

读取配置后，再次结合工程做推断：

• 优先识别主要 App Target
• 推断 Objective-C / Swift / 混编
• 记录当前工程要使用 Objective-C 示例、Swift 示例还是两者都需要
• Swift 工程需检查是否已有 {Target}-Bridging-Header.h 与 SWIFT_OBJC_BRIDGING_HEADER
• 定位疑似隐私同意回调位置，后续仍必须向用户确认
• 推断当前是否已有 CocoaPods 体系
• 推断当前是否已有 URL Scheme、Associated Domains、Universal Link 或 App 内路由代码
• 推断最合适的场景恢复代理持有者，优先为 App 启动入口或现有深链路由中心

如果存在多个候选入口，只问一个阻塞问题：

我找到多个可能的场景恢复入口：A、B。你希望 MobLink 恢复回调接到哪一个？

第四步：展示最小修改计划

修改前必须展示计划并等待用户确认。

计划至少覆盖：

• Podfile：添加 pod 'mob_linksdk_pro'
• Info.plist：添加或更新 MOBAppKey、MOBAppSecret、MOBNetLater = 2
• 系统库：提示 Xcode 需链接 libsqlite3、libz1.2.5、libc++
• App 启动入口：导入 MobLink/MobSDK 头文件，设置 MobLink delegate
• 隐私同意回调：在用户同意后调用 uploadPrivacyPermissionStatus
• 场景恢复代理：实现或接线 IMLSDKRestoreDelegate
• 项目内说明文档：生成 MobLink_README.md

如果用户选择 needUniversalLink = 是，计划中只写“检查并补充 Associated Domains / URL Scheme 的项目配置建议”，不要猜具体域名；具体 Host 必须从 MobLink 后台配置或用户提供的信息确认。

第五步：执行基础 SDK 接入

5-1 Podfile

优先在已有 App Target 的 target 块中添加：

ruby

pod 'mob_linksdk_pro'

如果已有该依赖，不重复添加。

如果项目没有 Podfile，先说明将创建最小 Podfile，并展示内容等待确认。

如果项目明确使用手动导入，不强行改为 CocoaPods；改为输出手动集成检查清单：

• MobLinkPro.framework
• MOBFoundation.framework
• libsqlite3
• libz1.2.5
• libc++

5-2 Info.plist

写入或更新：

• MOBAppKey = Excel 中的 appKey
• MOBAppSecret = Excel 中的 appSecret
• MOBNetLater = 2

保留已有无关配置。

5-3 App 启动入口

Objective-C 工程优先使用：

objc

#import <MobLinkPro/MobLink.h>
#import <MobLinkPro/IMLSDKRestoreDelegate.h>

在合适入口调用：

objc

[MobLink setDelegate:self];

如果 AppDelegate 需要承载恢复代理，声明应包含：

objc

<IMLSDKRestoreDelegate>

Swift 工程若需要调用 Objective-C SDK：

• 优先复用现有 Bridging Header
• 没有 Bridging Header 时，先展示新增方案并等待确认
• Header 中只加入实际需要的 MobLink 头文件，不导入无关 SDK

第六步：隐私合规接线

必须在用户同意隐私政策后、使用 MobLink 能力前调用。

在插入任何隐私授权代码前，必须先向用户说明：

text

根据 MobTech 隐私合规要求和中国区 App 上架规范，使用 MobLink 需要在用户同意隐私政策后才能初始化或使用 SDK。

你需要在 App 中：
1. 首次启动时展示《隐私政策》弹窗
2. 用户点击“同意”按钮后，调用隐私授权代码
3. 用户点击“不同意”则不应调用 MobLink SDK

请告知我：用户点击隐私政策“同意”按钮的回调代码在哪个文件、哪个方法中？

如果扫描工程已经找到明显候选位置，只能问：

我找到疑似隐私同意回调：{file}:{method}。是否把 MobLink 隐私授权回传放在这里？

用户未确认前，不得把 uploadPrivacyPermissionStatus 接入按钮、启动入口或任何占位方法。

通用方案：

objc

#import <MOBFoundation/MobSDK+Privacy.h>

[MobSDK uploadPrivacyPermissionStatus:YES onResult:^(BOOL success) {
    // 业务逻辑不要依赖 success，建议调用后继续业务流程
}];

如果用户明确需要限制扩展业务数据采集，再接入主动控制器：

objc

#import <MOBFoundation/MOBFoundation.h>

MobCustomController *privacyDataService = [MobCustomController new];
[MobSDK uploadPrivacyPermissionStatus:YES privacyDataDelegate:privacyDataService onResult:^(BOOL success) {
}];

主动控制器可覆盖的数据项包括：

• 地理位置：isLocInfoEnable / getLoc
• IDFA：isIdfaEnable / getIdfa
• IDFV：isIdfvEnable / getIdfv
• WiFi：isWiFiInfoEnable / getSSID / getBSSID
• IP：isIpEnable / getCellIpv4 / getCellIpv6 / getWifiIpv4 / getWifiIpv6

如果项目已有隐私同意链路，应先向用户确认“是否把调用放在这里”，不要同时再问别的问题。

第七步：制作场景

基础 SDK 接入完成后，才进入业务接线。

如果用户尚未指定制作 MobId 的业务入口，先问一个问题：

请告诉我哪个页面或按钮需要生成 MobLink 场景链接。

用户未确认 API 插入位置前，不得把 getMobId 接入示例按钮、占位方法或任意业务方法。确认后再展示将要修改的文件和方法。

获取 MobId 的核心示例：

objc

#import <MobLinkPro/MobLink.h>
#import <MobLinkPro/MLSDKScene.h>

NSMutableDictionary *customParams = [NSMutableDictionary dictionary];
customParams[@"key"] = @"value";
MLSDKScene *scene = [MLSDKScene sceneForPath:@"已在 MobLink 后台配置的渠道标识" params:customParams];

[MobLink getMobId:scene result:^(NSString *mobId, NSString *domain, NSError *error) {
    if (mobId.length > 0) {
        // mobId 可拼接到推广链接；domain 为后台生成的 Universal Link
    }
}];

注意：

• sceneForPath: 的 path 必须与 MobLink 后台配置一致
• params 用于场景还原时回传业务参数
• Web 落地页必须按官方 Web 集成文档接入 JS 模块，才能实现网页到 App 的场景衔接

第八步：场景还原

8-1 控制器恢复初始化

需要恢复的控制器可实现：

objc

#import <MobLinkPro/MLSDKScene.h>
#import <MobLinkPro/UIViewController+MLSDKRestore.h>

- (instancetype)initWithMobLinkScene:(MLSDKScene *)scene
{
    if (self = [super init]) {
        self.scene = scene;
    }
    return self;
}

如果控制器使用 xib 初始化，必须用对应 xib 初始化方式，不要直接套用默认 init。

8-2 恢复代理回调

实现代理时，一旦实现 IMLSDKWillRestoreScene:Restore:，必须执行 restoreHandler：

objc

- (void)IMLSDKWillRestoreScene:(MLSDKScene *)scene Restore:(void (^)(BOOL isRestore, RestoreStyle style))restoreHandler
{
    NSLog(@"MobLink restore path: %@", scene.path);
    restoreHandler(YES, MLDefault);
}

可选实现：

• IMLSDKCompleteRestore:
• IMLSDKNotFoundScene:

如果用户希望自行路由恢复场景，可将 restoreHandler(NO, MLDefault) 与项目路由逻辑结合，但必须先展示方案并等待确认。

第九步：依赖安装与验证

如果改了 Podfile，先问用户是否运行：

sh

pod install

运行后验证：

• .xcworkspace 是否生成或更新
• Podfile.lock 是否包含 mob_linksdk_pro
• Xcode 工程是否从 .xcworkspace 打开

如用户允许构建，再运行合适的 xcodebuild 命令；否则只给手动验证清单。

第十步：生成项目内说明文档

完成后在用户项目根目录生成 MobLink_README.md，内容至少包括：

• 本次修改文件
• 已配置的 Info.plist 项
• 隐私同意调用位置
• 场景制作入口
• 场景还原入口
• 仍需在 MobLink 后台、Web 端或 Apple Developer 后台确认的事项
• 官方文档地址清单

验收清单

交付前至少检查：

• Podfile 中 mob_linksdk_pro 未重复
• Info.plist 中存在 MOBAppKey、MOBAppSecret、MOBNetLater = 2
• 用户拒绝隐私政策时不会调用 MobLink 能力
• 用户同意隐私政策后先调用 uploadPrivacyPermissionStatus
• MobLink setDelegate: 已接入
• IMLSDKWillRestoreScene:Restore: 如已实现，必定调用 restoreHandler
• Swift 工程的 Bridging Header 配置有效
• MobLink_README.md 已写入官方文档链接

常见问题处理

• 如果场景恢复失败，优先检查后台 iOS 页面名称、渠道标识、path 和控制器恢复实现是否一致。
• 如果回调没有触发，优先检查 setDelegate: 是否在启动早期执行，delegate 生命周期是否有效。
• 如果 mobId 为空，检查 appKey、appSecret、隐私授权回传和网络请求结果。
• 如果 Web 到 App 无法衔接，检查 Web 集成文档、落地页 JS 模块、Universal Link 或 Scheme 配置。
• 如果合规检查失败，优先检查隐私政策文本、首次冷启动弹窗、MOBNetLater = 2 和 uploadPrivacyPermissionStatus 时机。