广告 AD iOS SDK 接入文档(新)

概述

本文档描述了 iOS 开发者如何集成 AD SDK(后面简称为 AdSdk),通过集成 AdSdk 展示广告创造收益。 AdSdk 提供了以下几种广告形式:SplashAd(开屏广告)、RewardVideoAd(激励视频广告)、BannerAd(横幅广告)、NativeExpressAd(原生广告)、InterstitialAd(插屏广告)、DrawVideoAd(Draw 视频广告)、快手短视频等。

术语介绍

AppId:应用 id,10位字符串。【注意】调试时请使用测试 appId:1100000000;外发版本请替换成正式 appId,否则不会产生收益。

UnitId:广告位 id,广告类型缩写后紧跟从1开始的编号,如开屏广告位 s1,激励视频广告位 rv1。一般情况下使用默认的广告位 id 即可,需要分配额外的广告位时,请联系客户经理。

AdId:广告 id,全局唯一,相同素材的广告每次请求也不会重复。所有广告回调返回的参数都包含广告 id。

UserId:用户 id,接入方定义的用户唯一标识,传入时可以哈希脱敏,主要用于排查问题。

SDK 集成

安装CocoaPods

CocoaPods是一个Swift和Objective-C项目的依赖管理器。它拥有超过49,000个第三方库,超过3,000,000个app都在使用cocoaPods做依赖管理,CocoaPods可以帮助你优雅的扩展你的项目。 如果您未安装过cocoaPods,可以通过以下命令行进行安装。更多详情请访问CocoaPods官网

$ sudo gem install cocoapods

配置Podfile文件

在您的工程文件所在文件夹下有一个名为Podfile的文件。如果您第一次使用CocoaPods,可以在通过以下命令初始化一个Podfile文件:

$ pod init

修改Podfile文件,将pod与source添加到Podfile中,如下所示:

source 'https://gitee.com/mobad/Specs.git'
source 'https://cdn.cocoapods.org/'

platform :ios, '9.0'

target 'BLMAdDemo' do
  pod 'BLMAdSdk', '~> 3.0.3'

  pod 'BLMAdapterCsj', '~> 1.0.1'
  pod 'Ads-CN', '~> 4.3.0.5'

  pod 'BLMAdapterGdt', '~> 1.0.1'
  pod 'GDTMobSDK', '~> 4.13.53'

  pod 'BLMAdapterKs', '~> 1.0.1'
  pod 'KSAdSDKFull', '~> 3.3.28'

  pod 'BLMAdapterSig', '~> 1.0.1'
  pod 'SigmobAd-iOS', '~> 4.1.0'
end

通过CocoaPods安装SDK前,确保CocoaPods索引已经更新。可以通过运行以下命令来更新索引:

$ pod repo update

运行命令进行安装:

$ pod install

也可以将上述两条命令合成为如下命令:

$ pod install --repo-update

隐私配置

info.plist 配置

  • App Transport Security Settings -> Allow Arbitrary Loads:YES
  • 项目设置: targets -> build settings -> Enable Bitcode -> NO
  • iOS 14申请IDFA权限
    Privacy - Tracking Usage Description -> 用于向您投放个性化广告
    同时,在初始化广告SDK的时候,增加:
#pragma mark - 申请IDFA权限
#import <AdSupport/AdSupport.h>
#import <AppTrackingTransparency/AppTrackingTransparency.h>

#warning - iOS 15,申请广告权限弹窗,要在applicationDidBecomeActive执行
- (void)applicationDidBecomeActive:(UIApplication *)application {
    if (@available(iOS 14, *)) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
        }];
    }
}

SDK App Store 隐私信息说明

根据苹果App Store隐私规则(《用户隐私和数据使用》以及《应用商店上的应用程序隐私详细信息》),自2020年12月8日起,新App和App更新需向App Store Connect提交App隐私信息的答复。为便于开发者掌握SDK收集的数据类型、使用目的,为开发者提供如下说明文档,以便开发者在其App隐私信息答复中补充SDK数据收集和使用情况。

App Store隐私规则

SDK 初始化

开发者需要在app启动时调用以下代码来初始化 AdSdk。

[BLMAdSdkManager setAppId:kAppId]; // 应用程序 id
[BLMAdSdkManager setUserId:userId]; // 用户 id
[BLMAdSdkManager setDebug:NO]; // 是否 debug

登录时请设置 userId:

[BLMAdSdkManager setUserId:userId];

退出登录请重置 userId:

[BLMAdSdkManager setUserId:nil];

开屏广告接入

开屏广告以 App 启动作为曝光时机,提供 5s 的可感知广告展示。用户可以点击广告跳转到目标页面;或者点击右上角的“跳过”按钮,跳转到 app 主页。

调用示例如下:

self.splashAdManager = [[BLMSplashAdManager alloc] initWithUnitId:@"s1"];
self.splashAdManager.delegate = self;
CGSize screenSize = [UIScreen mainScreen].bounds.size;
[self.splashAdManager loadAdWithWidth:screenSize.width height:screenSize.height - kBottomViewHeight];

BLMSplashAdDelegate 说明:

@protocol BLMSplashAdDelegate <NSObject>

- (void)splashAdDidLoad:(BLMSplashAd *)ad;  // 广告加载成功

- (void)splashAdFailToLoadWithError:(NSError *)error; // 广告加载失败

- (void)splashAdWillVisible:(BLMSplashAd *)ad; // 广告页面展示

- (void)splashAdDidClick:(BLMSplashAd *)ad; // 广告被点击

- (void)splashAdDidClose:(BLMSplashAd *)ad; // 广告被关闭

- (void)splashAdDidFail:(BLMSplashAd *)ad error:(NSError *)error; // 广告展示出错

@end

【强烈建议】 App 切到后台超过三分钟返回时加载开屏,以提升开屏广告的曝光量。加载开屏广告具体示例详见 Demo 中的 AppDelegate 或 SplashViewController。

激励视频广告接入

激励视频广告是指将短视频融入到 app 场景当中,用户观看完激励视频广告后可以得到一些应用内奖励。使用场景包括但不限于: 1、游戏等应用内观看视频广告获得游戏内金币等:用户必须观看完整视频才能获取奖励; 2、积分类应用接入。

调用示例如下:

self.rewardVideoAdManager = [[BLMRewardVideoAdManager alloc] initWithUnitId:@"rv1"];
self.rewardVideoAdManager.delegate = self;
if (autoShow) {
    [self.rewardVideoAdManager loadAndShowAdFromRootViewController:self];
} else {
    [self.rewardVideoAdManager loadAd];
}

BLMRewardVideoAdDelegate 说明:

@protocol BLMRewardVideoAdDelegate <NSObject>

- (void)rewardVideoAdDidLoad:(BLMRewardVideoAd *)ad; // 广告加载成功

- (void)rewardVideoAdFailToLoadWithError:(NSError *)error; // 广告加载失败

- (void)rewardVideoAdWillVisible:(BLMRewardVideoAd *)ad; // 广告页面将要展示

- (void)rewardVideoAdDidVisible:(BLMRewardVideoAd *)ad; // 广告页面展示成功

- (void)rewardVideoAdDidReward:(BLMRewardVideoAd *)ad transId:(NSString * _Nullable)transId;  // 广告奖励有效性回调,可以给用户发放奖励

- (void)rewardVideoAdDidClick:(BLMRewardVideoAd *)ad; // 广告被点击

- (void)rewardVideoAdDidPlayFinish:(BLMRewardVideoAd *)ad; // 广告播放完毕

- (void)rewardVideoAdDidClose:(BLMRewardVideoAd *)ad; // 广告被关闭

- (void)rewardVideoAdDidFail:(BLMRewardVideoAd *)ad error:(NSError *)error; // 广告展示出错

@end

加载激励视频广告具体示例详见 Demo 中的 RewardVideoViewController。

横幅广告接入

Banner 广告(横幅广告)位于 app 顶部、中部、底部任意一处,横向贯穿整个app页面;当用户与 app 互动时,Banner 广告会停留在屏幕上,并可在一段时间后自动刷新。

调用示例如下:

self.bannerAdManager = [[BLMBannerAdManager alloc] initWithUnitId:@"b1"];
self.bannerAdManager.delegate = self;
CGFloat width = self.view.width - 40;
CGFloat height = width * 100 / 640;
self.bannerViewFrame = CGRectMake((self.view.width - width) / 2,
                                  self.view.height - height - 40,
                                  width,
                                  height);
[self.bannerAdManager loadAdWithWidth:width height:height viewController:self];

BLMBannerAdDelegate 说明:

@protocol BLMBannerAdDelegate <NSObject>

- (void)bannerAdDidLoad:(BLMBannerAd *)ad; // 广告加载成功

- (void)bannerAdFailToLoadWithError:(NSError *)error; // 广告加载失败

- (void)bannerAdWillVisible:(BLMBannerAd *)ad; // 广告页面展示

- (void)bannerAdDidClick:(BLMBannerAd *)ad; // 广告被点击

- (void)bannerAdDidClose:(BLMBannerAd *)ad; // 广告被关闭

- (void)bannerAdDidFail:(BLMBannerAd *)ad error:(NSError *)error; // 广告展示出错

@end

加载 Banner 广告具体示例详见 Demo 中的 BannerViewController。

原生广告接入

原生模板广告,支持图文和视频样式,开发者不用自行对广告样式进行编辑和渲染,可直接调用相关接口获取广告 view。

调用示例如下:

self.nativeAdManager = [[BLMNativeAdManager alloc] initWithUnitId:@"n1"];
self.nativeAdManager.delegate = self;
CGFloat width = self.view.width - 40;
CGFloat height = 0;
[self.nativeAdManager loadAdWithWidth:width height:height count:count];

BLMNativeAdDelegate 说明:

@protocol BLMNativeAdDelegate <NSObject>

- (void)nativeAdDidLoad:(NSArray<BLMNativeAd *> *)ads; // 广告加载成功

- (void)nativeAdFailToLoadWithError:(NSError *)error; // 广告加载失败

- (void)nativeAdRenderSuccess:(BLMNativeAd *)ad; // 广告渲染成功

- (void)nativeAdWillVisible:(BLMNativeAd *)ad; // 广告页面展示

- (void)nativeAdDidClick:(BLMNativeAd *)ad; // 广告被点击

- (void)nativeAdDidClose:(BLMNativeAd *)ad; // 广告被关闭

- (void)nativeAdDidFail:(BLMNativeAd *)ad error:(NSError *)error; // 广告展示出错

@end

加载原生广告具体示例详见 Demo 中的 NativeViewController。

插屏广告接入

插屏广告是移动广告的一种常见形式,在应用开流程中弹出,当应用展示插页式广告时,用户可以选择点击广告,访问其目标网址,也可以将其关闭,返回应用。

调用示例如下:

self.interstitialAdManager = [[BLMInterstitialAdManager alloc] initWithUnitId:@"i1"];
self.interstitialAdManager.delegate = self;
CGFloat width = self.view.width - 40;
CGFloat height = width * 300 / 200;
if (autoShow) {
    [self.interstitialAdManager loadAndShowAdFromRootViewController:self width:width height:height];
} else {
    [self.interstitialAdManager loadAdWithWidth:width height:height];
}

BLMInterstitialAdDelegate 说明:

@protocol BLMInterstitialAdDelegate <NSObject>

- (void)interstitialAdDidLoad:(BLMInterstitialAd *)ad; // 广告加载成功

- (void)interstitialAdFailToLoadWithError:(NSError *)error; // 广告加载失败

- (void)interstitialAdWillVisible:(BLMInterstitialAd *)ad; // 广告页面展示

- (void)interstitialAdDidClick:(BLMInterstitialAd *)ad; // 广告被点击

- (void)interstitialAdDidClose:(BLMInterstitialAd *)ad; // 广告被关闭

- (void)interstitialAdDidFail:(BLMInterstitialAd *)ad error:(NSError *)error; // 广告展示出错

@end

加载插屏广告具体示例详见 Demo 中的 InterstitialViewController。

全屏插屏广告接入

全屏插屏广告是移动广告的一种常见形式,在应用流程中弹出,当应用展示插页式广告时,用户可以选择点按广告,访问其目标网址,也可以将其关闭,返回应用。

调用示例如下:

self.fullScreenInterstitialAdManager = [[BLMFullScreenInterstitialAdManager alloc] initWithUnitId:@"fi1"];
self.fullScreenInterstitialAdManager.delegate = self;
if (autoShow) {
    [self.fullScreenInterstitialAdManager loadAndShowAdFromRootViewController:self];
} else {
    [self.fullScreenInterstitialAdManager loadAd];
}

BLMFullScreenInterstitialAdDelegate 说明:

@protocol BLMFullScreenInterstitialAdDelegate <NSObject>

- (void)fullScreenInterstitialAdDidLoad:(BLMFullScreenInterstitialAd *)ad; // 广告加载成功

- (void)fullScreenInterstitialAdFailToLoadWithError:(NSError *)error; // 广告加载失败

- (void)fullScreenInterstitialAdWillVisible:(BLMFullScreenInterstitialAd *)ad; // 广告页面展示

- (void)fullScreenInterstitialAdDidClick:(BLMFullScreenInterstitialAd *)ad; // 广告被点击

- (void)fullScreenInterstitialAdDidClose:(BLMFullScreenInterstitialAd *)ad; // 广告被关闭

- (void)fullScreenInterstitialAdDidFail:(BLMFullScreenInterstitialAd *)ad error:(NSError *)error; // 广告展示出错

@end

加载全屏插屏广告具体示例详见 Demo 中的 FullScreenInterstitialViewController。

Draw 视频广告接入

竖版视频信息流广告,该广告适合在竖版全屏视频流中使用,接入方可以控制视频暂停或继续播放,默认视频播放不可干预。

调用示例如下:

self.drawVideoAdManager = [[BLMDrawVideoAdManager alloc] initWithUnitId:@"dv1"];
self.drawVideoAdManager.delegate = self;
CGFloat width = self.view.width;
CGFloat height = self.view.height;
[self.drawVideoAdManager loadAdWithWidth:width height:height count:count];

BLMDrawVideoAdDelegate 说明:

@protocol BLMDrawVideoAdDelegate <NSObject>

- (void)drawVideoAdDidLoad:(NSArray<BLMDrawVideoAd *> *)ads; // 广告加载成功

- (void)drawVideoAdFailToLoadWithError:(NSError *)error; // 广告加载失败

- (void)drawVideoAdWillVisible:(BLMDrawVideoAd *)ad; // 广告页面展示

- (void)drawVideoAdDidClick:(BLMDrawVideoAd *)ad; // 广告被点击

- (void)drawVideoAdDidStart:(BLMDrawVideoAd *)ad; // 广告播放开始

- (void)drawVideoAdDidPause:(BLMDrawVideoAd *)ad; // 广告播放暂停

- (void)drawVideoAdDidResume:(BLMDrawVideoAd *)ad; // 广告播放恢复

- (void)drawVideoAdDidStop:(BLMDrawVideoAd *)ad; // 广告播放完毕

- (void)drawVideoAdDidFail:(BLMDrawVideoAd *)ad error:(NSError *)error; // 广告展示出错

@end

加载 Draw 视频广告具体示例详见 Demo 中的 DrawVideoViewController。

快手短视频接入

AdSdk 将快手短视频封装成了 UIViewController。

self.drawFeedAdManager = [[BLMDrawFeedManager alloc] initWithUnitId:@"df1"];
self.drawFeedAdManager.delegate = self;
UIViewController *vc = [self.drawFeedAdManager createDrawFeedViewController];
[self addChildViewController:vc];
vc.view.frame = self.view.bounds;
[self.view addSubview:vc.view];

BLMDrawFeedDelegate 说明:

@protocol BLMDrawFeedDelegate <NSObject>

- (void)drawFeedDidLoad; // 视频流加载成功

- (void)drawFeedFailToLoadWithError:(NSError *)error; // 视频流加载失败

- (void)drawFeedVideoDidStartPlayWithVideoId:(NSString *)videoId videoType:(BLMDrawFeedType)videoType; // 视频播放开始

- (void)drawFeedVideoDidPauseWithVideoId:(NSString *)videoId videoType:(BLMDrawFeedType)videoType; // 视频播放暂停

- (void)drawFeedVideoDidResumeWithVideoId:(NSString *)videoId videoType:(BLMDrawFeedType)videoType; // 视频播放恢复

- (void)drawFeedVideoDidEndPlayWithVideoId:(NSString *)videoId videoType:(BLMDrawFeedType)videoType; // 视频播放完成

- (void)drawFeedVideoDidFailedToPlayWithVideoId:(NSString *)videoId videoType:(BLMDrawFeedType)videoType error:(NSError *)error; // 视频播放出错

@end

接入快手短视频具体示例详见 Demo 中的 DrawFeedViewController。