Skip to content

iOS 端快速接入 ​

下载 Demo

按本指南依次完成 SUDGI SDK 和广告能力接入、SDK 初始化及用户鉴权后,即可启动游戏。


一、 引入 SDK 与工程配置 ​

1. 引入 SDK ​

CocoaPods ​

在 Podfile 的宿主 App Target 中添加:

ruby
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.0Google 版本说明
Carty:CartySDK固定为 1.10.0Carty 更新日志
TopOn: TPNiOS固定为 6.5.73TopOn iOS 接入说明
MAX:AppLovinSDK配套 13.6.3,CocoaPods 约束 ~> 13.6.3MAX iOS 接入说明
Taku:AnyThinkiOS固定为 6.5.83Taku iOS 接入说明

二、广告能力接入 ​

完成依赖引入后,按所选广告源配置宿主应用,并在 SDK 初始化前处理适用的用户同意流程。

宿主配置 ​

AdMob App ID ​

适用条件:使用 AdMob。修改位置:宿主 App Target 的 Info.plist。

xml
<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 仅演示格式,接入时需补齐清单。

xml
<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>cstr6suwn9.skadnetwork</string>
    </dict>
    <!-- 这里只展示 Google 的一个 ID;请按下方来源补齐实际接入广告源的清单。 -->
</array>
广告源接入时使用的 ID 清单
AdMobGoogle 与第三方买方 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,添加用途说明,并按产品实际用途修改文案。

xml
<key>NSUserTrackingUsageDescription</key>
<string>用于向您展示更相关的广告内容</string>

接入位置二:宿主授权流程。已通过 UMP 处理 ATT 时复用该流程;否则引入 AppTrackingTransparency 并手动申请,不要重复申请。以下仅为 ATT 调用示例,所需授权流程处理完成后再执行 SDK 初始化。

objectivec
#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 和隐私状态;以下值仅演示写法,不是默认授权。

objectivec
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。

objc
// 1. userSignature 由您的业务服务器生成并下发
NSString *userSignature = @"业务后端下发的签名字符串";

// 2. 建立用户合法会话
[SUDOP authWithUserSignature:userSignature completion:^(NSError * _Nullable error) {
    if (!error) {
        NSLog(@"鉴权成功");
    }
}];

认证成功后,SDK 会通过用户 ping 检测认证失效。请在首次 auth 前注册账号级 setAuthInvalidatedListener: 监听,并由宿主统一获取新签名、串行重新授权。SDK 不自动获取签名或重试;首次进入游戏须等待授权成功,运行中恢复成功后保留现有游戏。退出账号或切换环境时结束旧恢复流程并反初始化,重新接入时重新注册监听。


五、极速启动游戏 ​

直接传入 gameID,SDK 将自动处理资源下载、校验和渲染。

objc

[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。


六、销毁与资源释放 ​

当用户退出游戏页面时,直接通过句柄销毁实例。

objc
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 同意。