Skip to main content

iOS 原生模版广告接入

请注意：从V2.8.0版本开始支持原生模版广告。

加载广告并注册回调#

原生模版广告加载是通过调用 KLNTemplateAd 类的静态方法 loadWithRequest: completionHandler: 完成的。该方法需要两个参数，一是 KLNTemplateAdRequest 对象，二是加载成功或者失败的回调Block。

加载成功得到 KLNTemplateAd 实例数组后，对每个 KLNTemplateAd 实例可以注册 KLNTemplateAdDelegate 代理对象，KLNTemplateAdDelegate 协议暴露了广告渲染成功、广告渲染失败、广告曝光、广告点击、广告关闭、广告详情页关闭等回调；你也可以给 KLNTemplateAd 实例的 videoController 属性设置代理，获取视频广告播放相关的回调，目前支持视频静音、取消静音、开始/恢复播放、暂停播放、播放结束回调。

通过 KLNTemplateAd 实例，你可以获取和设置模版广告相关信息，比如获取广告渲染view、是否是视频广告等信息；可以设置视频广告的播放策略；通过 调用render 方法来渲染广告。

模版广告请求参数类主要接口#

类名属性&&方法说明
KLNTemplateAdRequestposId广告位置Id，初始化函数initWithPosId:必填参数
adCount请求广告个数。推荐请求1-3个，一次最多请求3个。不填默认为1。
注意：设置了adCount，后台可能不返回广告，也可能返回，最多返回adCount个广告。
adSize请求广告的宽和高，SDK目前忽略设置的高度，建议填0。必填参数。
autoDownloadPolicy视频素材下载策略：控制视频素材下载时机；
默认任意网络环境下自动下载视频
如希望仅WIFI环境下自动下载视频，则可在请求前设置对应的值：KLNVideoDownloadPolicyWifiOnly。
muted视频广告初始化时是否静音播放，默认静音播放。

请注意：

  1. 模版广告的尺寸adSize目前会忽略高度设置，请填写0。请不要随意设置尺寸大小否则有可能出现拉取失败或者广告变形的情况。
  2. 模版广告可同时请求多条广告，最大请求数量为3。
  3. 目前SDK使用WKWebView渲染模版广告，为了避免内存占用过大，建议在合适的时机进行广告移除操作，保证不使用的广告，在合适的时机进行释放处理。

以下示例展示了如何在自己的VC中加载 KLNTemplateAd :

- (void)_onReloadBtnClick{
[self _dismissKeyboard];
KLNTemplateAdRequest *request = [[KLNTemplateAdRequest alloc] initWithPosId:[self posId]];
// request.muted = NO;
request.autoDownloadPolicy = self.videoDownloadPolicy;
request.adCount = self.adCountSlider.value;
request.adSize = CGSizeMake([UIScreen mainScreen].bounds.size.width - 2 * kKLNDemoTemplateCell_horGap , 0);
__weak typeof(self)weakSelf = self;
[KLNTemplateAd loadWithRequest:request completionHandler:^(NSArray<KLNTemplateAd *> * _Nullable adList, NSError * _Nullable error) {
if (adList.count > 0) {
[weakSelf.adList removeAllObjects];//【重要】不能保存太多广告，需要在合适的时机手动释放不用的，否则内存会过大
for (KLNTemplateAd *ad in adList) {
[weakSelf reportBidding:ad];
}
[weakSelf.adList addObjectsFromArray:adList];
for (NSUInteger i = 0; i < weakSelf.adList.count; ++i) {
KLNTemplateAd *ad = weakSelf.adList[i];
ad.delegate = weakSelf;
ad.viewController = weakSelf;
ad.videoAutoPlayPolicy = weakSelf.videoAutoPlayPolicy;
// important: 此处会进行WKWebview的渲染，建议一次最多预加载三个广告，避免内存占用过大
[ad render];
}
}
[self.dataTableView reloadData];
}];
}
#pragma mark - KLNTemplateAdDelegate
- (void)kln_templateAdWillExpose:(KLNTemplateAd *)ad {
KLNDemoLog(@"🌹模版广告曝光 ad:%@", ad);
}
- (void)kln_templateAdDidClick:(KLNTemplateAd *)ad {
KLNDemoLog(@"🌹模版广告点击 ad:%@", ad);
}
- (void)kln_templateAdClosed:(KLNTemplateAd *)ad {
KLNDemoLog(@"🌹模版广告关闭 ad:%@", ad);
[self.adList removeObject:ad];
[self.dataTableView reloadData];
}
- (void)kln_templateAdRenderSuccess:(KLNTemplateAd *)ad {
KLNDemoLog(@"🌹模版广告渲染成功 ad:%@", ad);
[self.dataTableView reloadData];
}
- (void)kln_templateAdRenderFail:(KLNTemplateAd *)ad error:(nonnull NSError *)error {
KLNDemoLog(@"🌹模版广告渲染失败 ad:%@ error:%@", ad, error);
// 如果接入方想在模版广告渲染失败后把广告删除，请加入如下代码
// [self.adList removeObject:ad];
// [self.dataTableView reloadData];
}

完整代码请参考Demo。

展示广告#

1）请在广告加载成功后，调用 render 方法渲染广告；

2）请在广告渲染成功回调 kln_templateAdRenderSuccess: 、渲染失败回调 kln_templateAdRenderFail: 、关闭广告回调kln_templateAdClosed刷新你的列表。

参考如下代码：

- (void)_onReloadBtnClick{
[self _dismissKeyboard];
KLNTemplateAdRequest *request = [[KLNTemplateAdRequest alloc] initWithPosId:[self posId]];
// request.muted = NO;
request.autoDownloadPolicy = self.videoDownloadPolicy;
request.adCount = self.adCountSlider.value;
request.adSize = CGSizeMake([UIScreen mainScreen].bounds.size.width - 2 * kKLNDemoTemplateCell_horGap , 0);
__weak typeof(self)weakSelf = self;
[KLNTemplateAd loadWithRequest:request completionHandler:^(NSArray<KLNTemplateAd *> * _Nullable adList, NSError * _Nullable error) {
if (adList.count > 0) {
[weakSelf.adList removeAllObjects];//【重要】不能保存太多广告，需要在合适的时机手动释放不用的，否则内存会过大
for (KLNTemplateAd *ad in adList) {
[weakSelf reportBidding:ad];
}
[weakSelf.adList addObjectsFromArray:adList];
for (NSUInteger i = 0; i < weakSelf.adList.count; ++i) {
KLNTemplateAd *ad = weakSelf.adList[i];
ad.delegate = weakSelf;
ad.viewController = weakSelf;
ad.videoAutoPlayPolicy = weakSelf.videoAutoPlayPolicy;
// important: 此处会进行WKWebview的渲染，建议一次最多预加载三个广告，如果超过3个会很大概率导致WKWebview渲染失败。
[ad render];
}
}
[self.dataTableView reloadData];
}];
}
- (void)kln_templateAdClosed:(KLNTemplateAd *)ad {
KLNDemoLog(@"🌹模版广告关闭 ad:%@", ad);
[self.adList removeObject:ad];
[self.dataTableView reloadData];
}
- (void)kln_templateAdRenderSuccess:(KLNTemplateAd *)ad {
KLNDemoLog(@"🌹模版广告渲染成功 ad:%@", ad);
[self.dataTableView reloadData];
}
- (void)kln_templateAdRenderFail:(KLNTemplateAd *)ad error:(nonnull NSError *)error {
KLNDemoLog(@"🌹模版广告渲染失败 ad:%@ error:%@", ad, error);
// 如果接入方想在模版广告渲染失败后把广告删除，请加入如下代码
// [self.adList removeObject:ad];
// [self.dataTableView reloadData];
}

具体请参考demo。

主要API#

模版广告请求参数类KLNTemplateAdRequest主要接口#

类名属性说明
KLNTemplateAdRequestposId广告位置Id，初始化函数initWithPosId:必填参数
adCount请求广告个数。推荐请求1-3个，一次最多请求3个。不填默认为1。
注意：设置了adCount，后台可能不返回广告，也可能返回，最多返回adCount个广告。目前只支持设置1个。
adSize请求广告的宽和高，SDK目前忽略设置的高度，建议填0。必填参数。
autoDownloadPolicy视频素材下载策略：控制视频素材下载时机；
默认任意网络环境下自动下载视频
如希望仅WIFI环境下自动下载视频，则可在请求前设置对应的值：KLNVideoDownloadPolicyWifiOnly。
muted视频广告初始化时是否静音播放，默认静音播放。

模版广告类KLNTemplateAd主要接口#

类名属性&&方法说明
KLNTemplateAddelegateKLNTemplateAdDelegate协议代理。接入方可以实现该属性获取广告曝光、点击、关闭等事件。
viewController开发者传入的用来present目标页的ViewController，必填参数。
videoAd是否视频广告。
promotedType返回广告的推广类型：2=下载广告; 3=网页推广广告【2.10.1版本新增】
adView广告view。
videoAutoPlayPolicy
视频广告自动播放策略。默认 KLNVideoAutoPlayPolicyAlways（总是自动播放）。
KLNVideoAutoPlayPolicy类型枚举：
KLNVideoAutoPlayPolicyAlways // 总是自动播放，无论网络条件
KLNVideoAutoPlayPolicyWIFI // WIFI 下自动播放
KLNVideoAutoPlayPolicyNever // 从不自动播放，无论网络条件
requestId广告请求ID
请注意：从V2.11版本新增该字段，接入方可以拼接requestId和creativeID唯一标记一个广告
creativeID广告创意ID
请注意：从V2.11版本新增该字段，接入方可以拼接requestId和creativeID唯一标记一个广告
loadWithRequest: completionHandler:加载模版广告方法。参数：request 模版广告请求对象；completionHandler 广告加载结果回调（成功/失败）。请注意：回调非线程安全。

广告事件回调KLNTemplateAdDelegate主要接口#

类名方法名说明
KLNTemplateAdDelegatekln_templateAdWillExpose:广告曝光回调。业务方可以通过实现该方法，统计曝光量（对账）
kln_templateAdDidClick:广告点击回调。业务方可以通过实现该方法，统计点击量（对账）
kln_templateAdClosed:广告关闭回调。请在此回调方法中进行广告对象的移除操作
kln_templateAdRenderSuccess:广告渲染成功, 此时的 ad.adView.frame.size.height 根据请求广告传入的width完成了动态更新。
kln_templateAdRenderFail:原生模板广告渲染失败。
kln_templateAdDidCloseOtherController:interactionType:广告跳转到其他控制器时，控制器被关闭时调用。
interactionType参数：KLNInteractionType枚举类型，包括Appstore/网页/视频详情页等。

其他说明#

  1. 广告曝光kln_templateAdWillExpose:方法回调的时机需满足以下条件：广告view可见，alpha不小于0.9，曝光面积不小于50%。对于一个广告，只会执行曝光回调一次。