变现SDK iOS接入文档

变现SDK iOS接入文档

前言

  • 开发环境下手动方式导入SDK资源进行集成的步骤,配置相对复杂,需要仔细阅读文档和Demo工程。
  • 个推变现SDK可通过个推广告配置动态下发并展示广告,可精确查询投放信息等。
  • 支持iOS9.0及以上。
  • 本文适用SDK版本: 2.1.0.0及以后。
  • 请参考GetuiBXSdk Demo工程。
  • 获取资源包:请联系技术支持QQ:3007288200

集成GetuiBXSdk: ipa增量约为500KB;
目前支持广告SDK:

广告SDK 最低版本 单独集成的ipa增量
穿山甲 3.3.1.5 2.5M
广点通 4.11.12 2.6M
百度联盟 4.73 0.7M
变现猫 3.2.0 0.6M
InMobi 7.5.0 1.3M

1. 创建个推应用

2. CocoaPods集成(推荐)

  • Podfile
# Uncomment the next line to define a global platform for your project
platform :ios, '9.0'

target 'BXDemo' do
  # Comment the next line if you don't want to use dynamic frameworks
  # use_frameworks!

  # 方式1:一键集成所有支持的广告平台(推荐)
  pod "GetuiBXSDK"

  # 方式2:挑选需要的广告平台
  pod "GetuiBXSDK/csj"
  pod "GetuiBXSDK/gdt"
  pod "GetuiBXSDK/inmobi"
  pod "GetuiBXSDK/bd"
  pod "GetuiBXSDK/bxm"

  # 方式3:自己指定广告平台SDK,可能存在兼容性问题
  pod "GetuiBXSDK/core"              #【必选】
  pod 'Bytedance-UnionAD', '3.3.1.5' #使用自己指定的广告平台
  pod "GDTMobSDK", '4.11.12'         #使用自己指定的广告平台
  pod "InMobiSDK-China", '7.5.0'     #使用自己指定的广告平台
end
  • 可用 "pod outdated" 命令查看是否有最新版本或者有依赖冲突导致不能升级到最新版本

  • 在项目的Info.plist中添加 NSAllowsArbitraryLoads 禁用ATS限制。

3. 手动集成

变现iOS SDK资料包结构

GTBX_IOS_SDK/
  |- readme.txt   (SDK资料包说明)
  |- document      (SDK接入文档)
  |- BXDemo-Pods   (cocoapods集成demo)
  |- BXDemo-Manual (手工集成demo)
  |- GtBxSdkLib/  (sdk资料包)
  |    |- GetuiBXSdk.framework(个推变现SDK)
  |    |- Vendor/ (存放所有的第三方SDK依赖库。不需要集成的广告SDK请删除对应平台的文件、并在xcode工程中删除其引用) 
  |    |        |- libGTCommonSDK-1.1.1.0.a(个推基础库,集成多个个推sdk时,请保留一个最高版本的libGTCommonSDK即可)

使用SDK需添加依赖项:
AdSupport.framework
AVFoundation.framework
CoreLocation.framework
CoreTelephony.framework
CoreMotion.framework
MessageUI.framework
QuartzCore.framework
SafariServices.framework
Security.framework
SystemConfiguration.framework
WebKit.framework
CoreMedia.framework
libc++.tbd
libresolv.9.tbd
libsqlite3.tbd
libxml2.2.tbd
libz.1.1.3.tbd

导入SDK资源

  • 打开BXDemo工程,将GtBxSdkLib添加到项目工程目录下:

  • 如果不需要集成其中的部分SDK,请在工程中使用Move to Trash彻底删除它
  • 确保代码目录GtBxSdkLib/Vendor下已经不存在任何相关文件

库引用检查

  • 在Build Settings -> Other Linker Flags 添加 "-ObjC"

  • Framework Search PathsLibrary Search Paths添加 "$(SRCROOT)/../GtBxSdkLib",并选择递归引入recursive

禁用ATS限制

  • 在项目的Info.plist中添加 NSAllowsArbitraryLoads 禁用ATS限制。

4. 初始化SDK

+ (void)startSdkWithKey:(GetuiBXSdkKey *)key delegate:(id<GetuiBXSdkDelegate>)delegate;

参数:

  • key: GetuiBXSdkKey实例,登记第三方广告平台的appid和个推应用的appid
  • delegate:个推SDK回调代理

说明:

  • 初始化个推服务,通过GetuiBXSdkDelegate回调个推SDK初始化的错误信息以及第三方广告SDK的初始化错误信息。
  • 该方法需要在主线程中调用。

头文件:

  • GetuiBXSdk.h

接口调用示例:

#import <GetuiBXSdk/GetuiBXSdk.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    // Override point for customization after application launch.
    GetuiBXSdkKey *key = [GetuiBXSdkKey new];
    // 请修改成在 www.getui.com 上申请的 变现SDK信息
    key.getui = @"请替换成 个推变现 的appid";
    // 请修改成在 各家广告平台 上申请的 开发者信息
    key.csj = @"请替换成 穿山甲 的appid";
    key.gdt = @"请替换成 广点通 的appid";
    key.bd = @"请替换成 百度联盟 的appid";
    key.inmobi = @"请替换成 inmobi 的appid";
    [GetuiBXSdk startSdkWithKey:key delegate:self];
    return YES;
}

// SDK发生错误时将会回调错误信息
- (void)GetuiBXSdkDidOccurError:(NSError *)error {
    /*
     参数说明
     error.code: 请看最后的常见错误码 GetuiBXSdkError 说明
     41001     缺少Appid
    */
    NSLog(@"GetuiBXSdkDidOccurError %@", error);
}

SDK启动后,将会打印当前第三方SDK集成情况信息:
GetuiBXSdk Info:
当前版本:BX-IOS-x.x.x.x
已集成SDK:
穿山甲-x.x.x.x
广点通-x.x.x
百度联盟-x.x
变现猫-x.x.x
InMobi-x.x.x

5. Debug模式

    [GetuiBXSdk setDebug];

说明:

  • 开启Debug模式,广告位配置默认过期,每次都会向服务端请求当前的广告位配置。
  • 此功能默认关闭,打开之后会增加网络请求和加载耗时影响用户体验,请只在开发调试中打开debug模式,发布之前关闭

头文件:

  • GetuiBXSdk.h

6. 获取版本号

    [GetuiBXSdk version];//BX-IOS-2.1.0.0

返回:

  • 集成的变现SDK版本号

头文件:

  • GetuiBXSdk.h

7. 设置标签

+ (void)setTags:(NSArray *)tags completion:(void (^)(BOOL isSuccess, NSError *error))completion;

参数:

  • tags: 标签个数不能太多,每个tag也不能太长(具体限制请参考官网说明文档),tag中不能包含以下特殊字符:"|", ",", "\n"
  • completion:设置结果回调

说明:

  • 设置用户标签,设置标签为覆盖模式

头文件:

  • GetuiBXSdk.h

接口调用示例:

    NSArray *tags = @[@"001", @"002"];
    [GetuiBXSdk setTags:tags completion:^(BOOL isSuccess, NSError *error) {
        NSLog(@"setTags:%@ error:%@", isSuccess?@"成功":@"失败", error?:@"");
    }];

8. Banner广告

GetuiBXBanner: 常用于APP界面顶部、底部或中部展现的多样式广告

- (instancetype)initWithAdId:(NSString *)adId
                       frame:(CGRect)frame
                  controller:(UIViewController *)controller
                       param:(GetuiBXParamObject *)param;

参数:

  • adId: 个推广告位Id
  • frame:banner广告frame
  • controller:当前vc,若不设定,可能导致广告点击无法弹出广告详情
  • param:参数实例

说明:

  • 初始化Banner广告

头文件:

  • GetuiBXBanner.h

接口调用示例:

    GetuiBXParamObject *param = [GetuiBXParamObject new];
    [param timeout:5000];//设置超时时长
    NSString *adId = kBanner;
    if(self.banner) {
        //移除Banner广告
        [self.banner remove];
        self.banner = nil;
    }
    self.banner = [[GetuiBXBanner alloc] initWithAdId:adId frame:CGRectMake(0, 100, [UIScreen mainScreen].bounds.size.width, 120) controller:self param:param];
    self.banner.gtDelegate = self;
    [self.banner loadAndShow:self.view];

回调示例:

- (void)GetuiBXComponentInitFail:(GetuiBXBanner *)component error:(NSError *)error {
    // 组件加载失败
    NSLog(@"demo-%s, error:%@", __FUNCTION__, error);
}

- (void)GetuiBXComponentAdFailShow:(GetuiBXBanner *)component error:(NSError *)error {
    // 组件展示失败
    NSLog(@"demo-%s, error:%@", __FUNCTION__, error);
}

- (void)GetuiBXComponentAdLoadSuccess:(GetuiBXBanner *)component {
    // 组件加载成功
    NSLog(@"demo-%s", __FUNCTION__);
}

- (void)GetuiBXComponentAdDidShow:(GetuiBXBanner *)component ad:(id)instance {
    // 组件已展示
    NSLog(@"demo-%s", __FUNCTION__);
}

- (void)GetuiBXComponentAdDidClick:(GetuiBXBanner *)component ad:(id)instance {
    // 组件被点击
    NSLog(@"demo-%s", __FUNCTION__);
}

- (void)GetuiBXComponentAdDidClose:(GetuiBXBanner *)component ad:(id)instance {
    // 组件被关闭
    NSLog(@"demo-%s", __FUNCTION__);
    if (self.banner) {
          //移除Banner广告
          [self.banner remove];
      }
}

- (void)GetuiBXComponentAdDidCloseDetail:(GetuiBXBanner *)component ad:(id)instance {
    // 广告详情关闭
    NSLog(@"demo-%s", __FUNCTION__);
}

-(void)GetuiBXComponentAdVideoFinish:(GetuiBXBanner *)component ad:(id)instance {
    // 视频播放结束
    NSLog(@"demo-%s", __FUNCTION__); 
}

9. 开屏广告

GetuiBXSplashAd: 用于APP开机、后台切回前台等展现的全屏广告

- (instancetype)initWithAdId:(NSString *)adId container:(UIWindow *)keyWindow param:(GetuiBXParamObject *)param;

参数:

  • adId: 个推广告位Id
  • keyWindow: 当前keywindow
  • param:参数实例

说明:

  • 初始化开屏广告

头文件:

  • GetuiBXSplashAd.h

接口调用示例:

    GetuiBXParamObject *param = [GetuiBXParamObject new];
    [param timeout:5000];
    NSString *adId = kSplash;
    self.splash = [[GetuiBXSplashAd alloc] initWithAdId:adId
                                              container:UIApplication.sharedApplication.windows[0]
                                                  param:param];
    self.splash.gtDelegate = self;
    [self.splash loadAdData];

回调示例:

- (void)GetuiBXComponentAdLoadSuccess:(GetuiBXSplashAd *)component {
    NSLog(@"demo-%s", __FUNCTION__);
    //广告数据加载成功,展示开屏页
    [self.splash showAd];
}

10. 插屏广告

GetuiBXInterstitialAd: 用于各种场景下弹出的全屏广告

- (instancetype)initWithAdId:(NSString *)adId adSize:(CGSize)adSize params:(GetuiBXParamObject *)params;

参数:

  • adId: 个推广告位Id
  • adSize: 插屏大小
  • param:参数实例

说明:

  • 初始化插屏广告

头文件:

  • GetuiBXInterstitialAd.h

接口调用示例:

    GetuiBXParamObject *param = [GetuiBXParamObject new];
    [param timeout:5000];
    NSString *adId = kIntersitial;
    self.ad = [[GetuiBXInterstitialAd alloc] initWithAdId:adId adSize:CGSizeMake(300, 450) params:[GetuiBXParamObject.alloc timeout:10000]];
    self.ad.gtDelegate = self;
    [self.ad loadAdData];

回调示例:

- (void)GetuiBXComponentAdLoadSuccess:(GetuiBXInterstitialAd *)component {
    NSLog(@"demo-:%s", __FUNCTION__);
    //广告数据加载成功,展示插屏
    [self.ad showAdFromRootViewController:self];
}

11. 激励视频广告

GetuiBXRewardVideoAd: 常用于用户观看全屏视频赢取奖励的场景

- (instancetype)initWithAdId:(NSString *)adId params:(GetuiBXParamObject *)params;

参数:

  • adId: 个推广告位Id
  • param:参数实例

说明:

  • 初始化激励视频广告

头文件:

  • GetuiBXRewardVideoAd.h

接口调用示例:

    GetuiBXParamObject *param = [GetuiBXParamObject new];
    [param timeout:5000];
    NSString *adId = kReward;
    self.rewardVideoAd = [[GetuiBXRewardVideoAd alloc] initWithAdId:adId params:[[GetuiBXParamObject alloc] timeout:10000]];
    self.rewardVideoAd.gtDelegate = (id) self;
    [self.rewardVideoAd loadAdData];

回调示例:

- (void)GetuiBXComponentAdLoadSuccess:(GetuiBXRewardVideoAd *)component {
    //激励视频广告数据加载完毕,展示激励视频
    NSLog(@"demo-%s, 是否有效:%@", __FUNCTION__, @(self.rewardVideoAd.isAdValid));
    [self.rewardVideoAd showAdWithController:self];
}

12. 信息流广告

GetuiBXNativeAd: 用于APP推荐页、详情页中的原生图文和视频广告

- (instancetype)initWithAdId:(NSString *)adId params:(GetuiBXNativeAdParams *)params;

参数:

  • adId: 个推广告位Id
  • param:参数实例

说明:

  • 初始化信息流广告,开发者可以通过此接口获取已渲染好的广告View
  • 更多实际场景参考Demo

头文件:

  • GetuiBXNativeAd.h

接口调用示例:

    //请求原生广告数据
    CGSize size = CGSizeMake(BX_SCREEN_WIDTH, 338);
    GetuiBXNativeAdParams *params = [[GetuiBXNativeAdParams alloc] timeout:10000];
    params.viewController = self;
    params.adSize = size;
    self.nativeAd = [[GetuiBXNativeAd alloc] initWithAdId:adId params:params];
    self.nativeAd.gtDelegate = self;
    [self.nativeAd loadAdData];

回调示例:

- (void)GetuiBXComponentAdLoadSuccess:(GetuiBXNativeAd *)component {
    //广告数据加载成功,获取广告view,渲染
    NSLog(@"demo-%s", __FUNCTION__);
    [self.expressAdViews addObjectsFromArray:self.nativeAd.adViews];
    [self.expressAdViews enumerateObjectsUsingBlock:^(GetuiBXNativeAdView *expressView, NSUInteger idx, BOOL *_Nonnull stop) {
        [expressView render];
    }];
    [self.tableView reloadData];

}

13. Draw信息流广告

GetuiBXDrawAd: 类似抖音的竖版视频信息流,与视频产品完全融为一体

- (instancetype)initWithAdId:(NSString *)adId params:(GetuiBXNativeAdParams *)params;

参数:

  • adId: 个推广告位Id
  • param:参数实例

说明:

  • 初始化Draw广告
  • 使用方式同GetuiBXNativeAd

头文件:

  • GetuiBXDrawAd.h

14. 按钮广告

GetuiBXButton:

- (instancetype)initWithAdId:(NSString *)adId
                       frame:(CGRect)frame
                  controller:(UIViewController *)controller
                       param:(GetuiBXParamObject *)param;

参数:

  • adId: 个推广告位Id
  • frame:按钮frame
  • controller:当前vc,若不设定,可能导致广告点击无法弹出广告详情
  • param:参数实例

说明:

  • 初始化按钮广告

头文件:

  • GetuiBXButton.h

接口调用示例:

    NSString *adId = kButton;
    GetuiBXParamObject *param = [GetuiBXParamObject new];
    [param timeout:5000];

    GetuiBXButton *btn = [[GetuiBXButton alloc] initWithAdId:adId frame:CGRectMake(100, 150, 80, 80) controller:self param:param];
    btn.gtDelegate = self;
    [btn loadAdData];
    self.btn = btn;

回调示例:

- (void)GetuiBXComponentAdLoadSuccess:(GetuiBXButton *)component {
    //广告数据加载成功,展示按钮
    NSLog(@"demo-%s", __FUNCTION__);
    [self.btn showToView:self.view];
}

15. 浮标广告

GetuiBXFloat:

- (instancetype)initWithAdId:(NSString *)adId
                       frame:(CGRect)frame
                  controller:(UIViewController*)controller
                       param:(GetuiBXParamObject *)param;

参数:

  • adId: 个推广告位Id
  • frame:按钮frame
  • controller:当前vc,若不设定,可能导致广告点击无法弹出广告详情
  • param:参数实例

说明:

  • 初始化浮标广告

头文件:

  • GetuiBXFloat.h

接口调用示例:

    NSString *adId = kFloat;
    GetuiBXParamObject *param = [GetuiBXParamObject new];
    [param timeout:5000];

    GetuiBXFloat *floatAd = [[GetuiBXFloat alloc] initWithAdId:adId frame:CGRectMake(100, 150, 80, 80) controller:self param:param];
    floatAd.gtDelegate = self;
    [floatAd loadAdData];
    self.floatAd = floatAd;

回调示例:

- (void)GetuiBXComponentAdLoadSuccess:(GetuiBXFloat *)component {
    //广告数据加载成功,展示浮标
    NSLog(@"demo-%s", __FUNCTION__);
    [self.floatAd showToView:self.view];
}

16. 自渲染广告

GetuiBXAd:

- (instancetype)initWithAdId:(NSString *)adId
                   imageSize:(GetuiAdSize)imageSize
                   param:(GetuiBXParamObject *)param;

参数:

  • adId: 个推广告位Id
  • imageSize:GetuiAdSize枚举,广告图片尺寸
  • param:参数实例

说明:

  • 初始化自渲染广告, 开发者可以通过获取广告数据内容,定制不同的展示UI

头文件:

  • GetuiBXAd.h

接口调用示例:

    //初始化GetuiBXAdTouch
    self.touch = [GetuiBXAdTouch new];

    //初始化自渲染广告
    NSString *adId = kCustom;
    GetuiBXParamObject *param = [GetuiBXParamObject new];
    [param timeout:5000];

    GetuiBXAd *ad = [[GetuiBXAd alloc] initWithAdId:adId imageSize:GetuiAdSize_Banner600_388 param:param];
    ad.gtDelegate = self;
    // 广告数据一次最多获取3条
    [ad loadAdWithCount:3];
    self.ad = ad;

回调示例:

- (void)GetuiBXComponentAdLoadSuccess:(GetuiBXAd *)component {
    //广告数据加载成功
    NSLog(@"demo-%s", __FUNCTION__);
    if (![component isKindOfClass:[GetuiBXAd class]]) {
        return;
    }
    NSArray *adArray = component.list;
    if (adArray.count > 0) {
           GetuiBXAdObject *object = adArray[0];//获取广告数据实例
           self.titleLabel.text = object.title;//设置UI
           self.touch.gtDelegate = self;
           //注册UI视图的点击事件
           [self.touch registerData:object viewController:self clickableViews:@[self.adView]];
       }
}

17. 常见错误码

初始化接口、设置标签接口、以及加载各种广告接口的常见错误码

    // 41000~接口调用错误
    GetuiBXSdkErrorAppIdMissing     = 41001, // 缺少Appid
    //        setTag接口错误码
    GetuiBXSdkErrorTagLocal         = 41101, // setTags本地校验错误
    GetuiBXSdkErrorTagNetwork       = 41102, // setTags网络错误
    GetuiBXSdkErrorTagServer        = 41103, // setTags服务端返回错误

    // 42000~广告配置错误
    GetuiBXSdkErrorAdConfig         = 42001, // 获取广告配置失败
    GetuiBXSdkErrorAdDailylimit     = 42002, // 广告组当日超限
    GetuiBXSdkErrorAdHourlylimit    = 42003, // 广告组小时超限

    // 43000~广告组件错误
    GetuiBXSdkErrorLoadFailed       = 43001, // 广告组件初始化失败
    GetuiBXSdkErrorSDKLoadFailed    = 43002, // 第三方SDK初始化失败
    GetuiBXSdkErrorAdLoadFailed     = 43003, // 广告数据加载失败
    GetuiBXSdkErrorAdInvalid        = 43004, // 广告无效

文档中心搜索