初始化说明

初始化注意事项

当同时接入穿山甲SDK和Cloooud SDK时，请确保初始化参数appID保持一致（穿山甲SDK初始化默认仅首次初始化生效）
Cloooud SDK初始化时机：强烈建议开发者在didFinishLaunchingWithOptions:方法内调用CloooudSDK初始化方法，建议SDK初始化时机越早越好，确保SDK初始化完成后再进行广告的请求处理（除开屏广告外，确保在config回调后再调用广告的请求方法）

目前聚合核心管理类支持以下接口：

// Cloooud SDK 版本

@property (readonly, class) NSString *SDKVersion;

// 初始化Cloooud方法，不初始化将无法使用Cloooud的相关功能

// @param appId 在Cloooud注册的应用ID

// @param config 初始化配置回调

+ (void)setupSDKWithAppId:(NSString *)appId config:(CloooudUserConfig *(^)(CloooudUserConfig *))config;

// 获取初始化时使用的应用ID

+ (NSString *)appID;

// 配置用户分组信息，可随时更新，但用户分组信息更新将触发配置重新加载，请谨慎使用

// @param userInfo 分组信息

+ (void)setUserInfoForSegment:(nonnull CloooudUserInfoForSegment *)userInfo;

// 获取当前主题模式

+ (CloooudAdSDKThemeStatus)themeStatus;

// 获取配置是否已经加载

+ (BOOL)configDidLoad;

// 添加配置加载成功回调，该回调会主动触发配置加载，并且仅会回调一次，监听者从内存总消失则不会回调

// @param observer 配置加载监听者，不会造成强引用，请放心使用

// @param action 加载成功回调

+ (void)addConfigLoadSuccessObserver:(id _Nonnull)observer withAction:(void(^_Nonnull)(id _Nonnull observer))action;

// SDK init后更新extraDeviceMap，主要用于初始化时开发者自己的参数还未生成，需后续传入；该接口会覆盖初始化传入的extraDeviceMap，开发者需自己做增量处理

// @param extraDeviceMap 额外信息

+ (void)updateExtraDeviceMap:(NSDictionary *)extraDeviceMap;

// 设置广告主题，扩展暗黑模式

+ (void)setThemeStatus:(CloooudAdSDKThemeStatus)themeStatus;

// 触发首次预缓存,针对特定广告位

// @param infos 广告对象

// @param interval 指定每轮请求的时间间隔, 允许时间范围:1-10

// @param concurrent 并发请求的广告数, 允许个数范围:1-20

+ (void)preloadAdsWithInfos:(NSArray<__kindof CloooudBaseAd *> *)infos andInterval:(NSInteger)interval andConcurrent:(NSInteger)concurrent;

SDK初始化

初始化代码需尽早执行，最好写在APP启动回调里：

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

// SDK初始化接口

// 设置三方使用的applogID/唯一标识id/设备id等相关信息，如无必要请勿设置其他。用法见接口说明

NSDictionary *didDic = @{ @"device_id": @"1234567" };// !!!建议在初始化时设置; 如需更改后期调用updateExtraDeviceMap

[CloooudAdSDKManager setupSDKWithAppId:@"5000546" config:^CloooudUserConfig *(CloooudUserConfig *c) {

c.logEnable = YES;

c.extraDeviceMap = didDic;

c.advanceSDKConfigPath = [[NSBundle mainBundle] pathForResource:@"config-ios-5000546" ofType:@"json"];

return c;

}];

}

版本查看

[CloooudAdSDKManager SDKVersion];

额外参数

该接口只针对部分有需要的开发者进行赋值调用。如无必要，请不要调用该接口传入无用参数。

注意：接口需要的参数为字典格式的Json字符串，且字段使用提供字段作为key值。

/// extra device data for CloooudAdSDK. Your can call this method anytime. Not required for every developer. Please make sure that it is called only when needed, Now the supported fields are "device_id".The incoming format is an dictionary of json strings,eg:"[{\"device_id\":\"62271333038\"}"
/// @param extraDeviceStr  eg:@"[{\"device_id\":\"62271333038\"}]"
+ (void)setExtDeviceData:(NSString *)extraDeviceStr;

调用示例：

// 设置三方使用的applogID，如无必要请勿设置其他。用法见接口说明
    NSDictionary *didDic = @{@"device_id":@"1234567"};
    NSData *jsonData = [NSJSONSerialization dataWithJSONObject:didDic options:NSJSONWritingPrettyPrinted error:nil];
    NSString *jsonString = [[NSString alloc] initWithData:jsonData encoding:NSUTF8StringEncoding];
    // 去除空格
    jsonString = [jsonString stringByReplacingOccurrencesOfString:@"\r" withString:@""];
    jsonString = [jsonString stringByReplacingOccurrencesOfString:@"\n" withString:@""];
    jsonString = [jsonString stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceAndNewlineCharacterSet]];  //去除掉首尾的空白字符和换行字符使用
    jsonString = [jsonString stringByReplacingOccurrencesOfString:@" " withString:@""];
    // !!!该接口需在setAppID接口之前设置
    [CloooudAdSDKManager setExtDeviceData:jsonString];

主题模式

部分广告SDK已适配了iOS的夜间模式，聚合SDK从v2710开始提供接口来设置广告展示的夜间模式。目前仅适配了穿山甲SDK。

typedef NS_ENUM(NSInteger, CloooudAdSDKThemeStatus) {

CloooudAdSDKThemeStatus_None = -1,

CloooudAdSDKThemeStatus_Normal = 0,

CloooudAdSDKThemeStatus_Night = 1,

};

调用示例：

[CloooudAdSDKManager setupSDKWithAppId:@"5000546" config:^CloooudUserConfig *(CloooudUserConfig *c) {

c.themeStatus = CloooudAdSDKThemeStatus_Night;

return c;

}];

// 初始化后也可以更新主题

[CloooudAdSDKManager setThemeStatus:CloooudAdSDKThemeStatus_Night];

注意:穿山甲需要v3.6.0.0+

扩展设备信息

针对部分媒体需要。如无必要，请勿设置 setExtDeviceData接口即将废弃，请使用新的赋值方式：

初始化时首次赋值

// 设置三方使用的applogID/唯一标识id/设备id等相关信息，如无必要请勿设置其他。用法见接口说明

NSDictionary *didDic = @{ @"key": @"1234567" };// !!!建议在初始化时设置; 如需更改后期调用updateExtraDeviceMap

[CloooudAdSDKManager setupSDKWithAppId:@"5000546" config:^CloooudUserConfig *(CloooudUserConfig *c) {

c.logEnable = YES;

c.extraDeviceMap = didDic;

return c;

}];

初始化后更新值

NSDictionary *didDic = @{ @"key": @"1234567" };

//初始化时开发者extraDeviceMap想包含的信息还未拿到，可以在初始化后再次调用来更新; ！！！该接口会覆盖初始化传入的extraDeviceMap，开发者需自己做增量处理

[CloooudAdSDKManager updateExtraDeviceMap:didDic];

三方SDK个性化设置

每一个Adapter插件库内都包含一个公开的xxxPersonaliseConfigAdapter类(eg:CloooudAdmobPersonaliseConfigAdapter)，adapter提供一个configAdapterWithBlock方法供开发者在该方法内进行某些三方adn的个性化设置，开发者需要在聚合SDK初始化之前针对不同ADN的adapter进行个性化设置。

注意：第三方开发者在这设置一些个性化配置，主要为一些聚合SDK并未统一封装的配置接口(如果聚合SDK已提供，请勿在此设置)；不要在configAdapterWithBlock写初始化代码，聚合SDK已完成初始化

eg：Admob:CloooudAdmobPersonaliseConfigAdapter

// 第三方开发者在这设置一些个性化配置，主要为一些聚合SDK并未统一封装的配置接口(如果聚合SDK已提供，请勿在此设置！！！)

// 不要在configAdapterWithBlock写初始化代码！！！聚合SDK已完成初始化

// !!!该接口需在setAppID接口之前设置

[CloooudUnityPersonaliseConfigAdapter configAdapterWithBlock:^{

[UnityAds setDebugMode:NO];

}];

[CloooudAdmobPersonaliseConfigAdapter configAdapterWithBlock:^{

[GADMobileAds sharedInstance].applicationMuted = YES;

// 支持模拟器

[GADMobileAds sharedInstance].requestConfiguration.testDeviceIdentifiers = @[

kGADSimulatorID,

@"7332fdb574f3388c808b8ef2d459cd32",

@"1ecdf6f84db8765e67fdf03913acb09b",

@"b816051b870e7420f281f67dc9e21bb8"

];

}];

// !!!该接口需在setAppID接口之前设置

[CloooudAdSDKManager setExtDeviceData:jsonString];


[CloooudAdSDKManager setupSDKWithAppId:@"5000546" config:^CloooudUserConfig *(CloooudUserConfig *c) {

c.logEnable = YES;

c.extraDeviceMap = didDic;

return c;

}];

支持自定义回传idfa

// SDK初始化方法
  [CloooudAdSDKManager setupSDKWithAppId:@"5000546" config:^CloooudUserConfig *(CloooudUserConfig *c) {
    // 打开日志开关，线上环境请关闭
    c.logEnable = YES;
    c.testMode = YES;
    // 设定自定义IDFA，根据实际情况设定
    c.customIDFA = @"00000000-0000-0000-0000-000000000001";
    return c;
  }];

Log辅助校验

聚合SDK在打开Log调试的模式下，如果开发者集成的三方SDK不在当前聚合SDK支持范围之内，会日志报错。使用和调试如下。

首先在SDK初始化前打开调试开关

// Whether to open log. default is none.

// ！！！接入调试时设置 Debug模式，在App上线appstore时请关闭该接口，防止影响性能！！！

[CloooudAdSDKManager setLoglevel:CloooudAdSDKLogLevelDebug language:CloooudAdSDKLogLanguageCH];

当开发者集成的三方SDK不符合时，使用"[init]-[error]"过滤即可找到对应Log

【CloooudAdSDK_V4.1.0.2】-[init]-[error]MSDK_V4.1.0.2支持的admob SDK版本范围为[7.64.0,7.69.0]

根据日志可知，当前开发者接入的Admob版本有误，SDK支持的是7.64.0-7.69.0。开发者根据提示接入正确的SDK版本即可

使用示例-全量日志

输入图片说明首先使用"CloooudAdSDK"可过滤得出所有由M打印的日志

CloooudAdSDK_V4.1.0.2 : _后面跟的是SDK版本


2022-01-26 11:32:30.890133+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[init]LogLevelDebug设置成功！

2022-01-26 11:32:30.985843+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[init]SDK接入成功！

2022-01-26 11:32:31.024368+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2_INTERNEL】-[other] 10.1.138.75

2022-01-26 11:32:31.054247+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[init]-[config]开始拉取setting配置...

2022-01-26 11:32:31.060417+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[init]初始化穿山甲广告SDK!

...

2022-01-26 11:32:33.097486+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]广告加载准备完:945494759, 请求类型：1!

2022-01-26 11:32:33.097805+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]Waterfull配置共有5层:(

2022-01-26 11:32:33.097884+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]设置加载总超时：10.000000

2022-01-26 11:32:33.097972+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]开始加载第-299层 !

2022-01-26 11:32:33.098586+0800 CloooudDemo[19610:4756672] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]创建Ad Adapter:gdt---5030722621265924!

2022-01-26 11:32:33.101341+0800 CloooudDemo[19610:4756672] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]-[request][5030722621265924]开始请求第-299(load_sort)层广告:gdt SDKVersion:4.12.3 AdapterVersion:4.12.3!

2022-01-26 11:32:33.297035+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2_INTERNEL】-[nativeAd] [5030722621265924]-[CloooudNativeAdsManager(Connector) adapterAdDidSetUp:]:Cloooud_Gdt_NativeAdAdapter

2022-01-26 11:32:33.300412+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[splashAd]更新loadsort:302

2022-01-26 11:32:33.300467+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[other]所有广告均尝试加载完毕:req_type:1!

2022-01-26 11:32:33.755581+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2_INTERNEL】-[nativeAd] [5030722621265924]-[CloooudNativeAdsManager(Connector) adapterAdManagerDidSuccessToLoad:nativeAds:]: Cloooud_Gdt_NativeAdAdapter

2022-01-26 11:32:33.755724+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]-[fill][5030722621265924]gdt--299--299-3000001.000000(3000001.000000*1.0000000000)-count:3

2022-01-26 11:32:34.099186+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2_INTERNEL】-[nativeAd] timemin

2022-01-26 11:32:34.099724+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]本次广告加载成功:gdt---5030722621265924****gdt---5030722621265924****gdt---5030722621265924****

2022-01-26 11:32:34.099784+0800 CloooudDemo[19610:4756622] 【CloooudAdSDK_V4.1.0.2】-[nativeAd]获取到最优广告个数adViews：3


### 关键字过滤
目前的关键字过滤主要用于在一次聚合加载过程中分门别类地筛选出一些关键信息。在Xcode控制台过滤即可。
一条日志主要有4个核心Tag，其结构为：

// 【0SDK_版本号】-[1当前广告类型]-[2事件类型]-[3代码位] 描述信息

【CloooudAdSDK_V4.1.0.2】-[splashAd]-[request][887410591]开始请求第301(load_sort)层广告:(正常请求)pangle SDKVersion:3.4.2.3 AdapterVersion:3.4.2.3.0!

如上，前两级tag会打印SDK名称，版本和当前加载的广告类型。版本信息属于公共属性不用于过滤，广告类型可用于过滤某一广告类型相关的日志，目前对应的广告类型描述为：

[nativeAd] 原生广告
[rewardvideoAd] 激励视频广告
[fullscreenvideoAd] 全屏视频广告
[interstitialAd] 插屏广告
[bannerAd] banner广告
[splashAd] 开屏广告
[interstitialProAd] 插全屏广告
```
eg：使用"[splashAd]"过滤可以查到开屏广告相关的所有日志：
```
2022-02-01 16:56:31.197219+0800 CloooudDemo[1082:602557] 【CloooudAdSDK_V4.1.0.2】-[splashAd]-[serverBidding]bidding server返回新的waterfall，按新顺序重新加载...

2022-02-01 16:56:31.197314+0800 CloooudDemo[1082:602557] 【CloooudAdSDK_V4.1.0.2】-[splashAd]开始加载第301层 !

2022-02-01 16:56:31.197633+0800 CloooudDemo[1082:602595] 【CloooudAdSDK_V4.1.0.2】-[splashAd]创建Ad Adapter:pangle---887410591!

2022-02-01 16:56:31.197704+0800 CloooudDemo[1082:602595] 【CloooudAdSDK_V4.1.0.2】-[splashAd]-[request][887410591]开始请求第301(load_sort)层广告:(正常请求)pangle adUnitID:887383142 SDKVersion:3.4.2.3 AdapterVersion:3.4.2.3.0!

2022-02-01 16:56:31.206406+0800 CloooudDemo[1082:602557] 【CloooudAdSDK_V4.1.0.2】-[splashAd]-[fill][887410591]-pangle-301-301-0.000000(0.00000*1.0000000000)

2022-02-01 16:56:31.233180+0800 CloooudDemo[1082:602557] 【CloooudAdSDK_V4.1.0.2】-[splashAd]本次广告加载成功

2022-02-01 16:56:31.235491+0800 CloooudDemo[1082:602557] 【CloooudAdSDK_V4.1.0.2】-[splashAd]获取到当前最佳展示广告：pangle-887410591

2022-02-01 16:56:31.535364+0800 CloooudDemo[1082:602557] 【CloooudAdSDK_V4.1.0.2】-[splashAd]-[show_listen][887410591]:pangle


第2级Tag主要用于一些核心事件的过滤，目前支持的事件有：

[init] 初始化相关事件
[request] 加载相关的事件
[fill] 填充成功相关的事件
[fill_fail] 填充失败相关的事件
[show] 展示调用相关的事件
[show_listen] 展示回调相关的事件

eg: - 使用”[request]“过滤, 表示该次聚合请求只请求了两个代码位：

【CloooudAdSDK_V4.1.0.2】-[rewardvideoAd]-[request][90010001]开始请求第-297(load_sort)层广告:pangle adUnitID:887383142 SDKVersion:3.3.6 AdapterVersion:3.3.6!

【CloooudAdSDK_V4.1.0.2】-[rewardvideoAd]-[request][1071335839472208]开始请求第1(load_sort)层广告:gdt adUnitID:887383142 SDKVersion:3.3.6 AdapterVersion:3.3.6!

使用”[fill_fail]“过滤, 信息描述里描述了当次加载失败的具体错误信息：

【CloooudAdSDK_V4.1.0.2】-[rewardvideoAd]-[fill_fail][9454952255]三方广告加载失败:pangle-Error Domain=com.pangle.buadsdk Code=40006 "广告位ID不合法" UserInfo={NSLocalizedDescription=广告位ID不合法}

第3级Tag主要是用代码位过滤，可以过滤出某个代码位下所有相关的事件。 eg：使用代码位"[90010001]"过滤，显示了该次广告加载代码位"90010001"所有的关键事件。


2022-01-26 16:09:07.013675+0800 CloooudDemo[19905:4815662] 【CloooudAdSDK_V4.1.0.2】-[rewardvideoAd]-[request][90010001]开始请求第-297(load_sort)层广告:(正常请求)pangle adUnitID:887383142 SDKVersion:3.3.6 AdapterVersion:3.3.6!

2022-01-26 16:09:07.361134+0800 CloooudDemo[19905:4815612] 【CloooudAdSDK_V4.1.0.2】-[rewardvideoAd]-[fill][90010001]-pangle--297--295-3000405.000000(3000405.000000*1.0000000000)

2022-01-26 16:09:11.830059+0800 CloooudDemo[19905:4815612] 【CloooudAdSDK_V4.1.0.2】-[rewardvideoAd]-[show_listen][90010001]

2022-01-26 16:09:11.832308+0800 CloooudDemo[19905:4815662] 【CloooudAdSDK_V4.1.0.2】-[rewardvideoAd]-[request][90010001]开始请求第-297(load_sort)层广告:(预缓存请求)pangle SDKVersion:3.3.6 AdapterVersion:3.3.6!

2022-01-26 16:09:12.144473+0800 CloooudDemo[19905:4815612] 【CloooudAdSDK_V4.1.0.2】-[rewardvideoAd]-[fill][90010001]-pangle--297--295-3000405.000000(3000405.000000*1.0000000000)


## waterfall加载详情
聚合SDK提供单次waterfall请求后每个代码位的具体错误获取，提升开发者问题排查效率，帮助开发者及时解决线上问题。
### 建议获取时机

1.  广告展示回调时；
2.  无广告返回至总超时回调时；
3.  全部返回报错回调时；

### 返回数据格式
整体上以数组形式返回全部ADN的错误信息，单条错误信息用字典承载，字典格式如下：


| 字段 | 类型 | 说明 |
| --- | --- | --- |
mediation_rit |String |代码位ID
adn_name |String |ADN的名称标识，例如 CSJ
error_message |String |错误信息描述，未获取到有效错误信息将返回 未知错误
error_code |Number |错误码，直接返回ADN抛出的错误码

### 接口说明

@interface CloooudBaseAggregationAd : NSObject

// ADN 加载广告失败原因，建议调用时机：展示广告时/超时时/全部返回报错时

(NSArray<NSDictionary > )waterfallFillFailMessages;

@end


### 使用示例

(void)nativeAdsManager:(CloooudNativeAdsManager _Nonnull)adsManager didFailWithError:(NSError _Nullable)error {

NSLog(@"%s:%@", func, error);

NSArray<NSDictionary > messages = [adsManager waterfallFillFailMessages];

NSLog(@"%@",messages);

}


## 支持本地提前导入配置
可在平台提前下载瀑布流配置导入工程中，如遇到应用首次安装并且网络拉取配置失败，会使用提前导入的配置。 平台下载文件可拖入工程中，在SDK初始化时传入文件路径。 可参功能使用说明文档：配置拉取失败解决方案

[CloooudAdSDKManager setupSDKWithAppId:@"5000546" config:^CloooudUserConfig (CloooudUserConfig c) {

c.advanceSDKConfigPath = [[NSBundle mainBundle] pathForResource:@"config-ios-5000546" ofType:@"json"];

return c;

}];

文档
目录

深色
模式

IOS文档