广告聚合SDK-Unity(C#)

1 文档修订记录

文档版本	文档更新日期	文档更新内容
3.3.79	2024.12.05	1.启用iOS广告聚合SDK；2.「5 包体导出与测试」章节更新广告配置和打包说明
3.3.36	2022.01.05	初版

2 接入准备

推荐C# 以上版本，如果游戏是4及以下版本，可能会无法支持新特性

推荐Unity2018及以上版本

2.1 添加文件

• 将文件FYBase.unitypackage与FYADMediation.unitypackage先后导入到您的Unity工程的Assets文件夹下
• 导入方式：打开UNITY工程，菜单栏Assets=>Import Package=>Custom Package... ，之后选择文件导入工程

2.2 配置DLL文件平台属性

UNITY项目中，选择对应Dll文件，在Inspector面板=>Select platforms for plugin 勾选对应平台

如果已经配置，请忽略此步骤

• Assets\Plugins\FYBase\FYBase.dll勾选"Any Platform",并勾选"iOS"和“Android”以排除这2平台
• Assets\Plugins\FYBase\Android\FYBase.dll选择平台为"Android",注意"Any Platform"不要打钩
• Assets\Plugins\FYBase\iOS\FYBase.dll选择平台为"iOS",注意"Any Platform"不要打钩
• Assets\Plugins\FYADMediation\FYADMediation.dll选择平台为"Any Platform"

2.3 添加SDK配置

1.打开"星云平台->对接中心->SDK对接->SDK 列表->基础接入参数"，找到 App ID、App Key、Company ID

2.在UNITY打开星云配置界面

3.将 App ID、App Key 、Company ID 填入对应输入框，选择游戏屏幕朝向，点击确定，完成配置

2.4 配置游戏内展示位ID

• 游戏内展示位ID，用于标识和区分游戏中不同的广告展示位

• 对接前需要在星云后台先配置好游戏内展示位ID，对接时要传递给SDK接口，请前往星云后台进行配置：对接中心->广告位管理->游戏内展示位管理

2.5 开启调试模式

1.将配置界面中的Debug勾选并点击确定，即可开启「调试模式」；取消勾选并点击确定，即关闭「调试模式」。

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

2.6 引入命名空间

游戏代码中引入以下命名空间，开始接入。

using FYADMediation;

3 游戏交互示范

3.1 初始化

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

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

• 在进入游戏后先调一下广告预加载

• 点击游戏中的获取奖励按钮，先调用IsRewardLoad，判断广告加载成功，再调用ShowReward

• 如果IsRewardLoad返回加载失败，游戏做一个类似"广告未加载"的提示

• 当观看广告完成后，收到"下发奖励"回调，再发放奖励给玩家

• 流程示例：
  

• 代码示例

// 在进入游戏后先调一下广告预加载
FYADMediationBridge.Instance.LoadReward(placementId);

// 在广告按钮点击时调用以下逻辑

bool isLoaded = FYADMediationBridge.Instance.IsRewardLoad(placementId);

if (isLoaded)
{
    // 加载成功，展示广告
    FYADMediationBridge.Instance.ShowReward(placementId);
}
else {
    // 加载失败，游戏提示广告展示失败
    Alert.Show("广告未加载");
}

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

• 进入游戏某页面时，先调用IsRewardLoad，判断广告加载成功，再显示奖励按钮
• 观看广告完成后，收到"下发奖励"回调，再发放奖励给玩家
• 流程示例：
  

4 客户端接口与回调

接口接入的要诀?

• 必接接口一定要接入，选接接口根据需要接入
• 必传参数一定要传，能传的参数尽量都传

接口的回调何时注册?

• 第一种方式：在初始化回调成功后注册其余的回调
• 第二种方式：在每次调用对应接口前都预先注册对应的回调
• 综合使用：先使用第一种方式，之后如需改变再重新注册

4.1客户端回调

1.初始化回调FYAMInitCallback

• 使用方式：

FYADMediationBridge.Instance.FYAMInitCallback = new FYAMInitCallback((info) =>
{
    //TODO: 初始化成功，可预加载广告
    //例如: FYADMediationBridge.Instance.LoadReward(placementId);
}, (info) =>
{
    //TODO: 初始化失败
    //info.message 失败原因
});

2.激励视频广告回调FYAMRewardCallback

• 使用方式：

FYADMediationBridge.Instance.FYAMRewardCallback = new FYAMRewardCallback(info =>
{
    //TODO: 下发奖励
    //info.placementId 获取游戏内展示位ID，用来对该展示位下发奖励
}, info =>
{
    //TODO: 展示成功
}, info =>
{
    //TODO: 展示失败
    //info.message 失败原因
}, info =>
{
    //TODO: 广告点击
}, info =>
{
    //TODO: 广告关闭
}, info =>
{
    //TODO: 加载失败
    //info.message 失败原因

    // *禁止在此处调用加载广告接口，以防止游戏卡顿
}, info =>
{
    //TODO: 加载成功
});

4.2 初始化(必接)

1.方法

• void DoInit(string gameVersion)

2.说明

• 游戏需要在刚启动游戏的时候调用

3.调用

FYADMediationBridge.Instance.DoInit(gameVersion);

4.参数

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

5.回调

• 初始化回调FYAMInitCallback

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

1.方法

• void LoadReward(string placementId)

2.说明

• 用来预加载激励视频广告，为后续成功展示广告做准备
• 调用时机：在展示广告之前的某个时机提前调用此接口（不用每次展示广告都调，只要提前某个时机调一次就行）

3.调用

FYADMediationBridge.Instance.LoadReward(placementId);

4.参数

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

5.回调

• 激励视频广告回调FYAMRewardCallback

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

1.方法

• void ShowReward(string placementId)

2.说明

• 用来拉起激励视频广告
• 在调用此接口之前，需确保对应游戏内展示位ID的广告已加载

3.调用

FYADMediationBridge.Instance.ShowReward(placementId);

4.参数

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

5.回调

• 激励视频广告回调FYAMRewardCallback

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

1.方法

• bool IsRewardLoad(string placementId)

2.说明

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

3.调用

bool isLoaded = FYADMediationBridge.Instance.IsRewardLoad(placementId);
/*例如: 
if (isLoaded)
{
    // 加载成功，展示广告
    FYADMediationBridge.Instance.ShowReward(placementId);
}
else {
    // 加载失败，游戏提示广告展示失败
}*/

4.参数

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

5.返回值	返回值	类型	说明
isLoaded	bool	true:已加载成功，false:已加载失败

5 包体导出与测试

5.1 iOS

5.1.1 导出母包Xcode工程

• 将Unity项目导出为Xcode工程，设置好开发证书，编译运行到iPhone手机上进行联调测试
• 注意：此工程为母包Xcode工程，只能用来做联调测试，此时触发广告展示接口，展示的广告为广告聚合用来调试用的虚拟广告界面。如需正式上架渠道平台，还需使用"iOS本地打包工具"输出正式版渠道的Xcode工程。

5.1.2 广告配置

• 打开广告聚合开关：

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

• 广告聚合配置：

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

• 配置广告位：

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

• 第三方广告渠道配置说明请查看：广告聚合产品使用手册

5.1.3 输出正式版渠道Xcode工程

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

5.1.4 Topon广告测试说明：

• 如果Topon还没有配置正式的广告，可以先使用他们的测试广告来进行测试，测试步骤如下：
  1. 打开应用的广告追踪，路径：iPhone->设置->隐私->跟踪->允许App请求跟踪，并将你游戏的隐私开关打开
  2. 在游戏界面中，唤起星云的调试模式。唤起方式：在游戏界面中，按顺序按音量键：上下上上上下下下上上上下下下上下。成功唤起后可以看到调试工具悬浮球
  3. 重启游戏（杀进程重启）
  4. 再次点击展示广告，可以拉起测试广告，可以当成正常广告来测试下发奖励等流程

5.2 Andorid

5.2.1 导出Android工程

• 方式一：使用Unity打包Android APK调试；方式二：将UNITY项目导出为Android Studio工程，然后就可以在Android Studio开发工具上调试了
• 注意：此母包只能用来做联调测试，此时触发广告展示接口，展示的广告为广告聚合用来调试用的虚拟广告界面。如需正式上架渠道平台，还需使用"Android在线打包工具"输出正式版渠道的APK。

5.2.2 广告配置

• 打开广告聚合开关：

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

• 广告聚合配置：

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

• 配置广告位：

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

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

5.1.3 输出正式版渠道Apk

• 星云开放平台打开"Android在线打包工具"，选择母包APK，勾选配置好的渠道，输出正式版渠道的APK
• "Android在线打包工具"路径：星云开放平台->对接中心->渠道打包->打包工具
• 详细说明请查看：Android在线打包工具使用教程

5.1.4 Topon广告测试说明：

• 如果Topon还没有配置正式的广告，可以先使用他们的测试广告来进行测试，测试步骤如下：
  1. 在游戏界面中，唤起星云的调试模式。唤起方式：在游戏界面中，按顺序按音量键：上下上上上下下下上上上下下下上下。成功唤起后可以看到调试工具悬浮球
  2. 重启游戏（杀进程重启）
  3. 再次点击展示广告，可以拉起测试广告，可以当成正常广告来测试下发奖励等流程

6 F&Q

6.1 导出Android Studio项目报错

该情况有可能是因为UNITY配置界面未配置完成，请查看该文档的添加SDK配置部分，重新操作一次