iOS 端快速接入
按本指南依次完成 SUDGI SDK 和广告能力接入、SDK 初始化及用户鉴权后,即可启动游戏。
一、 引入 SDK 与工程配置
1. 引入 SDK
CocoaPods
在 Podfile 的宿主 App Target 中添加:
sdk_version = '3.0.0'
pod 'SUDGI', sdk_version
# 按实际业务选择至少一个广告源
pod 'SUDM/admob', sdk_version
pod 'SUDM/carty', sdk_version
pod 'SUDM/topon', sdk_version
pod 'SUDM/max', sdk_version
pod 'SUDM/taku', sdk_version通过 sdk_version 统一指定 SUDGI 和 SUDM 的配套 SDK 发布版本,升级时修改该变量并同步更新整套 SDK。仅保留实际接入的广告源,然后执行 pod install。CocoaPods 会自动引入其基础组件及对应广告平台 SDK。
手动引入
将 SUDGI.xcframework 拖入工程,在 General 中设置为 Embed & Sign。同时从配套交付包添加广告相关库和资源:
- 公共组件:
SUDCoreKit.xcframework、SUDReport.xcframework;工程中已有时只保留一份。 - 广告核心库:
SUDM.xcframework。 - 所选广告源的 Adapter:
SUDMAdapterAdmob.xcframework、SUDMAdapterCarty.xcframework、SUDMAdapterTopOn.xcframework、SUDMAdapterMax.xcframework、SUDMAdapterTaku.xcframework,按实际业务选择。 - 对应广告平台 SDK、其依赖及随包资源。
将上述库加入宿主 App Target,并按各库交付说明设置链接和嵌入方式。单独提供的资源 Bundle、隐私清单加入 Copy Bundle Resources,已随 Framework 包含的资源无需重复添加。
2. 环境设置
- Other Linker Flags:添加
-ObjC。 - Enable Bitcode:设置为 NO。
- 引入头文件:
#import <SUDGI/SUDGI-umbrella.h>。
3. 三方版本要求
以下为本接入方案的配套版本与依赖约束,不要降低配套版本。升级前请查询官网最新版本及兼容要求,并确认与所用 SUD 组件匹配。
| 三方模块 | 接入基线 / 版本约束 | 版本查询 |
|---|---|---|
AdMob:Google-Mobile-Ads-SDK | 配套 13.7.0,CocoaPods 约束 ~> 13.7.0 | Google 版本说明 |
Carty:CartySDK | 固定为 1.10.0 | Carty 更新日志 |
TopOn: TPNiOS | 固定为 6.5.73 | TopOn iOS 接入说明 |
MAX:AppLovinSDK | 配套 13.6.3,CocoaPods 约束 ~> 13.6.3 | MAX iOS 接入说明 |
Taku:AnyThinkiOS | 固定为 6.5.83 | Taku iOS 接入说明 |
二、广告能力接入
完成依赖引入后,按所选广告源配置宿主应用,并在 SDK 初始化前处理适用的用户同意流程。
宿主配置
AdMob App ID
适用条件:使用 AdMob。修改位置:宿主 App Target 的 Info.plist。
<key>GADApplicationIdentifier</key>
<string>ca-app-pub-XXXXXXXXXXXXXXXX~YYYYYYYYYY</string>替换为 AdMob 控制台对应 iOS 应用的 App ID(格式中包含 ~),不要使用广告单元 ID(格式中包含 /)。
Google 官方调试 App ID 为 ca-app-pub-3940256099942544~1458002511。SDK 资源不会自动将该配置合并到宿主 Info.plist,需要在宿主工程中添加;参见 AdMob iOS 接入说明。
SKAdNetwork
SKAdNetwork 用于不依赖 IDFA 的安装归因,ID 使用带 .skadnetwork 后缀的字符串;参见 AdMob iOS 隐私策略。
修改位置:宿主 App Target 的 Info.plist。按实际接入广告源的要求合并 ID 清单并去重;以下单个 ID 仅演示格式,接入时需补齐清单。
<key>SKAdNetworkItems</key>
<array>
<dict>
<key>SKAdNetworkIdentifier</key>
<string>cstr6suwn9.skadnetwork</string>
</dict>
<!-- 这里只展示 Google 的一个 ID;请按下方来源补齐实际接入广告源的清单。 -->
</array>| 广告源 | 接入时使用的 ID 清单 |
|---|---|
| AdMob | Google 与第三方买方 SKAdNetwork ID 清单 |
用户同意与授权
用户同意
SDK 接收宿主确认的状态,不判断法规是否适用,也不展示同意弹窗。SUDOPPrivacyConfig 不替代 CMP、UMP 或 ATT 流程。
适用条件:需要为广告收集用户同意。接入位置:SDK 初始化之前。
复用宿主 CMP 或隐私流程;使用 Google UMP iOS 时,更新同意信息、展示所需表单,按要求提供隐私选项入口,并在请求广告前检查 UMPConsentInformation.sharedInstance.canRequestAds。
将宿主已确认的各项隐私状态传入下一节初始化参数;canRequestAds 不能直接映射为四项状态全部同意。
ATT
适用条件:App 或广告 SDK 涉及跨 App / 网站追踪或访问 IDFA;iOS 14.5 及以上需先取得 ATT 授权。
接入位置一:宿主 Info.plist,添加用途说明,并按产品实际用途修改文案。
<key>NSUserTrackingUsageDescription</key>
<string>用于向您展示更相关的广告内容</string>接入位置二:宿主授权流程。已通过 UMP 处理 ATT 时复用该流程;否则引入 AppTrackingTransparency 并手动申请,不要重复申请。以下仅为 ATT 调用示例,所需授权流程处理完成后再执行 SDK 初始化。
#import <AppTrackingTransparency/AppTrackingTransparency.h>
// 在主线程、App 前台活跃且没有其他系统授权弹窗时调用。
if (@available(iOS 14.0, *)) {
[ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
dispatch_async(dispatch_get_main_queue(), ^{
// ATT 流程结束后,结合已完成的 CMP 流程继续下一节 SDK 初始化。
// Authorized 才允许追踪;Denied / Restricted 不允许追踪。
// NotDetermined 仍是未决定,不能当作授权;在合适时机由宿主继续处理。
// ATT 状态不能直接当作 GDPR / LGPD 同意状态。
});
}];
} else {
// 无 ATT 接口的系统:按宿主隐私流程继续下一节 SDK 初始化。
}接入广告无需宿主手动读取或传入 IDFA。自身业务确需读取时,仅在授权后使用 AdSupport,不得将全零 IDFA 当作有效标识;同时核对广告 SDK 的实际采集行为。参见 Apple 追踪授权要求。
三、SDK 初始化
完成上方广告依赖、宿主配置和适用的用户同意、ATT 流程后,在 App 启动阶段执行一次 SDK 初始化,并传入宿主已确认的隐私状态。
配置字段和枚举含义见 SUDOPPrivacyConfig。替换示例中的 App ID、App Key 和隐私状态;以下值仅演示写法,不是默认授权。
SUDOPPrivacyConfig *privacyConfig = [[SUDOPPrivacyConfig alloc] init];
// 只赋值宿主已确认的状态;未赋值的字段保持默认 Unset,不应用到广告 SDK。
privacyConfig.gdprConsentStatus = kSUDOPGdprConsentStatusNotApplicable;
privacyConfig.doNotSellStatus = kSUDOPDoNotSellStatusNotApplicable;
privacyConfig.lgpdConsentStatus = kSUDOPLgpdConsentStatusNotApplicable;
privacyConfig.ageRestrictedTreatment = kSUDOPAgeRestrictedTreatmentUnspecified;
SUDOPSDKConfiguration *config = [[SUDOPSDKConfiguration alloc] init];
config.appId = @"YOUR_APP_ID";
config.appKey = @"YOUR_APP_KEY";
config.privacyConfig = privacyConfig;
[SUDOP initializeWithConfiguration:config completion:^(NSError * _Nullable error) {
if (error) {
NSLog(@"SDK 初始化失败: %@", error.localizedDescription);
return;
}
// SDK 初始化成功,继续用户鉴权和启动游戏。
}];初始化接口完整定义见 initializeWithConfiguration。
四、用户鉴权 (auth)
在启动游戏前,必须将业务后端生成的 userSignature 告知 SDK。
// 1. userSignature 由您的业务服务器生成并下发
NSString *userSignature = @"业务后端下发的签名字符串";
// 2. 建立用户合法会话
[SUDOP authWithUserSignature:userSignature completion:^(NSError * _Nullable error) {
if (!error) {
NSLog(@"鉴权成功");
}
}];认证成功后,SDK 会通过用户 ping 检测认证失效。请在首次 auth 前注册账号级 setAuthInvalidatedListener: 监听,并由宿主统一获取新签名、串行重新授权。SDK 不自动获取签名或重试;首次进入游戏须等待授权成功,运行中恢复成功后保留现有游戏。退出账号或切换环境时结束旧恢复流程并反初始化,重新接入时重新注册监听。
五、极速启动游戏
直接传入 gameID,SDK 将自动处理资源下载、校验和渲染。
[SUDOP startGame:@"123" didGameViewCreated:^(UIView * _Nonnull gameView) {
// 2. 挂载视图到 UI
gameView.frame = self.gameContentView.bounds;
[self.gameContentView addSubview:gameView];
} didGameHandleCreated:^(id<SUDRTGameHandle> _Nonnull gameHandle, SUDOPGameInfo * _Nonnull gameInfo) {
// 保存句柄用于后续销毁
self.gameHandle = gameHandle;
// 1. 注册代理以接收游戏事件
[SUDOP registerWrappedClientWithGameHandle:gameHandle clientDelegate:self];
} progress:^(NSInteger progress) {
} completion:^(id<SUDOPGameHandleProvider> _Nullable gameHandleProvider, NSError * _Nullable error) {
if (!error) NSLog(@"游戏已成功运行");
}];游戏运行后,由小游戏通过 sud 广告 API 加载和展示广告,参见 游戏开发示例。SDK 初始化成功不表示广告已加载,游戏侧仍需等待广告对象的 onLoad。
六、销毁与资源释放
当用户退出游戏页面时,直接通过句柄销毁实例。
if (self.gameHandle) {
[self.gameHandle destroy];
self.gameHandle = nil;
NSLog(@"游戏实例已销毁,内存已释放");
}七、发布前检查
- 使用 AdMob 时,将调试 App ID 替换为自己的 App ID。
- 按所用广告源核对最终
Info.plist中的配置;SDK 或广告源升级后重新核对 SKAdNetwork 清单。 - 检查归档中 SDK 的
PrivacyInfo.xcprivacy,并按 App 和第三方 SDK 的实际行为完成 App Store 隐私信息。 - SUDM 的隐私清单当前包含设备标识数据的追踪用途声明;清单不代表已取得 ATT 或 CMP 同意。
