广告聚合SDK-iOS(OC)

1 文档修订记录

文档版本	文档更新日期	文档更新内容
3.3.79	2024.12.05	初版

2 接入准备

2.1 导入SDK

将下载好的 FYBase、FYADMediation 目录，拷贝到游戏工程目录中并引入

2.2 添加SDK配置

到星云平台的"对接中心->SDK对接->SDK列表->基础接入参数->SDK配置参数"下载如下的配置文件，拷贝到游戏工程目录中并引入：

• iOS SDK配置文件：FYCoreConfig.plist

说明： 「引入」是指在 Xcode 界面右键点击工程列表，选择Add File to 'xxx'，然后在弹出框选择你要添加的文件或文件夹，将其添加到 Xcode 工程内。 以上的文件和文件夹都需要引入到工程，并且保持在工程中只有一份，否则会引起报错。

可选个人信息的配置。如不希望本SDK采集某信息，请将对应字段的值改为0。如允许本SDK采集某信息，请将对应字段的值改为1

(1)在FYCoreConfig.plist中添加如下配置

<key>FY_GAME_PRIVACY</key>
<string>{"basic_device_data":"0","os_version":"0"}</string>

(2)字段名称说明

OS	个人信息类型及字段	用途和目的	是否可选	关闭方式
iOS	设备基础信息（设备型号、硬件信息、屏幕分辨率）	帮用户排查异常时使用，作为异常分析的依据	是	修改配置参数 FY_GAME_PRIVACY 的 basic_device_data 字段值为"0"
iOS	操作系统版本	帮用户排查异常时使用，作为异常分析的依据	是	修改配置参数 FY_GAME_PRIVACY 的 os_version 字段值为"0"
iOS	IDFA（版本3.3.56已去除）	帮用户排查异常时使用，作为异常分析的依据	是

2.3 添加Xcode配置

1.TARGETS -> Build Settings -> Other Linker Flags -> 添加 -ObjC

2.TARGETS -> Build Settings -> Apple LLVM - Language - Objective C -> Weak References in Manual Retain Release -> YES

3.TARGETS -> Build Settings -> Enable Objective-C Exceptions -> YES

4.TARGETS -> Build Settings -> Enable Bitcode -> NO

2.4 开启调试模式

1.将 FYCoreConfig.plist 中的 FY_GAME_DEBUG 的值改为 1，即可开启「调试模式」；FY_GAME_DEBUG 改为 0，即关闭「调试模式」。

2.开启「调试模式」会显示客户端的悬浮球，点击进入调试工具可以查看接口/回调的调用信息，具体调试方法可查看文档。

2.5 引入头文件

在对接代码头部引入头文件：

#import <FYADMediation/FYADMediation.h>

3 游戏交互示范

3.1 初始化

• 在启动游戏后，调用doInit接口
• 初始化成功回调中，调用loadReward，进行广告预加载
  

3.2 激励视频广告对接方式一

• 点击游戏中的获取奖励按钮，先调用isRewardLoad，判断广告加载成功，再调用showReward
• 如果isRewardLoad返回加载失败，游戏做一个类似"广告未加载"的提示，然后调用loadReward再重新加载一次广告
• 当观看广告完成后，收到"下发奖励"回调，再发放奖励给玩家

3.3 激励视频广告对接方式二

• 进入游戏某页面时，先调用isRewardLoad，判断广告加载成功，再显示奖励按钮
• 如果isRewardLoad返回加载失败，请调用loadReward再重新加载一次广告
• 观看广告完成后，收到"下发奖励"回调，再发放奖励给玩家
  

4 客户端接口

接口接入的要诀?

• 必接接口一定要接入，选接接口根据需要接入

• 必传参数一定要传，能传的参数尽量都传

• 所有的生命周期接口一定要接入

4.1 客户端回调

1.说明

• SDK接口在执行以后，会调用相应的回调方法，可以在回调方法中，处理相应的游戏逻辑

2.使用

• 注册以下通知，注册通知可以放在 AppDelegate.m(Unity 为UnityAppController.mm) 的 application:didFinishLaunchingWithOptions: 方法中

//注册通知：广告聚合初始化
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(fyamInitCallback:) name:FYAMInitCallback object:nil];

//注册通知：激励视频广告
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(fyamRewardCallback:) name:FYAMRewardCallback object:nil];

• 实现注册的回调方法，回调方法可以添加在AppDelegate.m(Unity 为UnityAppController.mm) 的末尾处。

-(void)fyamRewardCallback:(NSNotification *)notify {
    FYAMCallback *response = notify.object;
    NSLog(@"###fyamRewardCallback>>response:%@", [response toJSON]);
}

- (void)fyamInitCallback:(NSNotification *)notify {
    FYAMCallback *response = notify.object;
    NSLog(@"###fyamInitCallback>>response:%@", [response toJSON]);
}

4.2 初始化 doInit (必接)

1.说明

• 游戏需要在启动游戏马上调用，若有隐私保护弹窗，请在隐私保护弹窗之后调用
• 调用其他接口之前，请确保初始化回调已完成

2.调用

FYAMInitInfo *fyamInitInfo = [[FYAMInitInfo alloc] init];
fyamInitInfo.gameVersion = @"1.0.0";
[[FYADMediation sharedInstance] doInit:fyamInitInfo];

3.参数

参数名	说明	是否必传
gameVersion	游戏版本号	是

• 回调：fyamInitCallback

4.2 加载激励视频广告 loadReward (必接)

1.说明

• 用来加载激励视频广告
• 需在初始化成功后调用此接口，以完成广告预加载

2.调用

FYAMInfo *info= [[FYAMInfo alloc] init];
info.placementId =@"xxx";
[[FYADMediation sharedInstance] loadReward:info];

3.参数

参数	类型	说明	是否必传
placementId	string	游戏内展示位ID	是

4.回调

• fyamRewardCallback

4.3 展示激励视频广告 showReward (必接)

1.说明

• 用来拉起激励视频广告
• 在调用此接口之前，需确保的广告已加载

2.调用

FYAMInfo *info= [[FYAMInfo alloc] init];
info.placementId =@"xxx";
[[FYADMediation sharedInstance] showReward:info];

3.参数

参数	类型	说明	是否必传
placementId	string	游戏内展示位ID	是

4.回调

• fyamRewardCallback

4.4 激励视频广告是否已加载 isRewardLoad (必接)

1.说明

• 用来判断激励视频广告是否已加载
• 在调用showReward之前，需先调用此接口判断广告是否加载成功
• 如果此接口返回加载失败，需重新调用一次loadReward

2.调用

FYAMInfo *info= [[FYAMInfo alloc] init];
info.placementId =@"reward_1";
NSString *isLoad = [[FYADMediation sharedInstance] isRewardLoad:info];
if ([@"1" isEqualToString:isLoad]) {
    [[FYADMediation sharedInstance] loadReward:info];
} else {
    [[FYADMediation sharedInstance] showReward:info];
}

3.参数

参数	类型	说明	是否必传
placementId	string	游戏内展示位ID	是

4.返回值

类型	说明
string	"0":加载失败/"1":加载成功

5 包体导出与测试

5.1 母包Xcode工程

• 注意：此工程为母包Xcode工程，只能用来做联调测试，此时触发广告展示接口，展示的广告为广告聚合用来调试用的虚拟广告界面。如需正式上架渠道平台，还需使用"iOS本地打包工具"输出正式版渠道的Xcode工程。

5.2 广告配置

• 打开广告聚合开关：

  • 此开关打开之后，打包工具输出的渠道Xcode工程才带有第三方广告平台的代码库，例如官包对应打入的是Topon的代码库
  • 开关打开路径：星云开放平台->对接中心->渠道打包->渠道配置->官方Apple渠道->配置->广告聚合->聚合开关

• 广告聚合配置：

  • 需配置第三方广告平台的app_id、app_key等参数
  • 配置路径：星云开放平台->对接中心->渠道打包->渠道配置->官方Apple渠道->配置->广告聚合

• 配置广告位：

  • 配置"游戏展示位ID"以及"广告位ID"，"游戏展示位ID"即对接代码中要传入的placementId，"广告位ID"即第三方广告平台的广告位ID
  • 配置路径：星云开放平台->对接中心->渠道打包->广告位管理->官方Apple渠道->添加广告位

• 详细说明请查看：广告聚合产品使用手册

5.3 输出正式版渠道Xcode工程

• mac电脑安装并打开"iOS本地打包工具"，选择母包工程，勾选配置好的渠道，输出正式版渠道的Xcode工程
• 双击打开正式版渠道的Xcode工程，编译运行到iPhone手机上进行测试，或者导出正式版ipa上传到appstore
• 详细说明请查看：iOS本地打包工具使用教程
• 下载链接：资源下载-iOS本地打包工具