章鱼广告 SDK-iOS 接入文档

注意：

• 本 SDK 最低兼容版本 iOS 12.0
• 集成前请和章鱼广告 SDK 人员确认 SDK 版本号
• 竞胜竞败回传：章鱼广告平台根据媒体传回来的竞胜竞败价格，通过相应算法自动提高出价来获得广告曝光，媒体 RTB 时一定要调用，否则会导致价格出不上去。

一、导入 SDK 依赖

.1 压缩包目录结构

文件目录	目录说明
Octopus/libs/***.framework	SDK 的 framework 文件.
OctopusSdkDemo	示例工程, 用来方便媒体参考接入.
章鱼广告 SDK-iOS 接入文档.html	章鱼广告 SDK-iOS 接入文档.

1.2 导入 SDK 文件

1.2.1 在 app 目录下新建 libs 文件夹 1.2.2 将 Octopus/libs 目录下的文件拷贝到 libs 文件夹下.

1.3 设置文件引用方式

• 选择 [Target] -> [Build Settings] -> [Linking] -> [Other Linker flags]
• 添加-ObjC -lc++

1.4 添加网络访问权限

工程 plist 文件设置，

• 点击右边的 information Property List 后边的 "+" 展开。
• 添加 App Transport Security Settings，
• 先点击左侧展开箭头，再点右侧加号，Allow Arbitrary Loads 选项自动加入，
• 修改值为 YES；

1.5 添加依赖类库

AdSupport.framework

2 pod 方式安装 sdk

https://gitee.com/zy_octopus/octopus_ios_sdk

二、SDK 初始化

2.1 初始化 SDK

注意：

• 1 初始化 SDK 方法的调用必须在调用请求广告接口之前，AppId 由运营人员提供
• 2 建议在应用程序启动的时候调用章鱼广告 SDK 的初始化
• 3 在主线程中调用 SDK 的初始化方法

2.2 代码示例

导入头文件

#import <OctopusAdDemo/OctAdManager.h>

初始化-不带隐私设置

// 根据AppID和隐私设置初始化SDK，隐私设置可为空
[OctAdManager configureWithApplicationID: @"app_id"];

初始化-带隐私设置

// 根据AppID和隐私设置初始化SDK，隐私设置可为空，为空时SDK内部自动获取IDFA

//隐私不为空时，isLimitPersonalAds的默认值是NO，SDK内部会自动获取IDFA； isLimitPersonalAds = YES时， SDK内部不会自动获取IDFA

//可以使用该方法设置IDFA，使用该方法设置时，请将isLimitPersonalAds设置为YES， 禁止sdk内部自动生成IDFA
[OctAdManager setupIDFA:idfa];

OctPrivacyModel *privacyModel = [[OctPrivacyModel alloc] init];
privacyModel.isLimitPersonalAds = NO;

[OctAdManager configureWithApplicationID:@"app_id" andPrivacy:privacyModel];

2.3 获取 IDFA

//首先需要在 Info.plist 中配置" NSUserTrackingUsageDescription " 及描述文案，接着使用 AppTrackingTransparency 框架中的 ATTrackingManager 中的 requestTrackingAuthorizationWithCompletionHandler 请求用户权限，在用户授权后再去访问 IDFA 才能够获取到正确信息

//注意，setupIdfa 这个方法需要在 applicationDidBecomeActive 中调用，否则，如果在 didFinishLaunchingWithOptions 这个方法中调用，那么可能不会弹出授权弹窗，最终导致获取不到 idfa

(void)setupIdfa {
    if (@available(iOS 14, *)) {

       // iOS14及以上版本需要先请求权限

       [ATTrackingManager
       requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {

           // 获取到权限后，依然使用老方法获取idfa

           if (status == ATTrackingManagerAuthorizationStatusAuthorized) {
               NSString *idfa = [[ASIdentifierManager sharedManager].advertisingIdentifier UUIDString];
               [OctAdManager setupIDFA:idfa];
           } else {
               NSLog(@"请在设置-隐私-跟踪中允许App请求跟踪");
           }

       }];
   } else {

       // iOS14以下版本依然使用老方法

       // 判断在设置-隐私里用户是否打开了广告跟踪

       if ([[ASIdentifierManager sharedManager] isAdvertisingTrackingEnabled]) {
           NSString *idfa = [[ASIdentifierManager sharedManager].advertisingIdentifier UUIDString];
           [OctAdManager setupIDFA:idfa];
       } else {
           NSLog(@"请在设置-隐私-广告中打开广告跟踪功能");
       }

   }
    }
    ```

#### 2.4 设置CAID

//可以通过这个方法指定CAID，SDK内部将优先使用这个CAID；如果开发者不设置CAID， 那么SDK内部将自动获取CAID。

/**  设置caid
 caid = "[{\"caid\":\"f1ab6f44a868aa02b11475c2566daadd\",\"version\":\"20220111\"},{\"caid\":\"4f2fe9ea7811f5808fbcfe1f6110be90\",\"version\":\"20230330\"}]"
 **/

 + (void)setupCAID:(NSString *)caid;



#### 2.5 竞价结果上报通知

##### 2.5.1 竞价成功通知
//竞价成功时上报接口 secondWinPrice竞价第二名价格，单位是分

- (void)sendWinNotice:(NSInteger)secondWinPrice;

##### 2.5.2 竞价失败通知
//竞价失败时上报接口 winPrice 胜出者价格 单位分 lossReason 竞价失败原因 winBidder 胜出者 （非必填）

- (void)sendLossNotice:(OctAdBiddingFailReason)lossReason winnerPirce:(NSInteger)winPrice winBidder:(NSString * _Nullable )bidder;

## 三、开屏广告
#### 3.1 开屏广告接口说明
``` objc
// 设置开屏广告的代理
@property (nonatomic, weak)id<OctAdSplashDelegate> delegate;

// 开屏初始化
- (instancetype)initWithSlotId:(NSString *)slotId;

// 开屏初始化, 可以指定超时时间，单位：s
- (instancetype)initWithSlotId:(NSString *)slotId timeOut:(double)timeoutInterval;

// 加载开屏广告
- (void)loadAd;

// 展示广告
- (void)showAdsInWindow:(UIWindow *)window;

// 获取广告返回价格
- (int)getPrice;

3.2 开屏广告接口说明

@optional

**
 @return 展示下部logo位置，需要给传入view设置尺寸。
 */
- (UIView *)octad_splashBottomView;

/**
 广告加载成功
 */
- (void)octad_splashAdSuccess:(OctAdSplash *)splashAd;

/**
 广告展示
 */
- (void)octad_splashAdDidVisible:(OctAdSplash *)splashAd;

/**
 广告加载失败
 */
- (void)octad_splashAd:(OctAdSplash *)splashAd didFailWithError:(NSError * _Nullable)error;

/**
 SDK渲染开屏广告点击回调
 */
- (void)octad_splashAdDidClick:(OctAdSplash *)splashAd;

/**
 SDK渲染开屏广告关闭回调，当用户点击广告时会直接触发此回调，建议在此回调方法中直接进行广告对象的移除操作
 */
- (void)octad_splashAdDidClose:(OctAdSplash *)splashAd;

/**
 倒计时为0时会触发此回调
 */
- (void)octad_splashAdCountdownToZero:(OctAdSplash *)splashAd;

3.3 开屏广告示例

self.splash = [[OctAdSplash alloc] initWithSlotId:@"slotId"];
self.splash.delegate = self;
[self.splash loadAd];


- (void)octad_splashAdSuccess:(id)splashAd {
    NSLog(@"广告加载成功");
    [self.splash showAdsInWindow:[UIApplication sharedApplication].keyWindow];
}

四、原生（信息流）广告

4.1 原生广告接口说明

// controller 展示view的控制器或者弹出落地页的需要的控制器，此参数不能为空
@property (nonatomic, weak) UIViewController *controller;

// 设置原生广告的代理
@property (nonatomic, weak)id<OctAdNativeDelegate> delegate;

// 原生初始化
- (instancetype)initWithSlotId:(NSString *)slotId;
// isSelfRender：是否是自渲染。 默认为NO； 如果设置为YES， 那么就需要开发者自己渲染视图了， nativeAdViews将无效
- (instancetype)initWithSlotId:(NSString *)slotId isSelfRender:(BOOL)isSelfRender;

// 加载广告
- (void)loadAd;

// 获取广告返回价格
- (int)getPrice;

// 广告加载成功后获得的 原生广告数据模型（使用model数据，自定义View样式）
@property (nonatomic, strong, readonly) NSArray<OctNativeAdDataModel *> *adDataModels;

// 广告加载成功后获得的 View广告（数组内部为加载完成的View形式广告，直接add到目标View）
@property (nonatomic, strong, readonly) NSArray *nativeAdViews;

//是否是自渲染。 默认为NO； 如果设置为YES， 那么就需要开发者自己渲染视图了， nativeAdViews将无效
@property (nonatomic, readonly) BOOL isSelfRender;

4.2 原生广告回调说明

// 加载成功
- (void)octad_nativeSuccessToLoad:(OctAdNative *)nativeAd;

// 加载失败
- (void)octad_nativeAd:(OctAdNative *)nativeAd didFailWithError:(NSError * _Nullable)error;

// 广告曝光
- (void)octad_nativeDidVisible:(OctAdNative *)nativeAd;

// 广告点击
- (void)octad_nativeAdViewDidClick:(OctAdNative *)nativeAd;

// 广告关闭
- (void)octad_nativeAdViewDidClose:(OctAdNative *)nativeAd;

// 广告落地页关闭
- (void)octad_nativeAdViewWillCloseOtherView:(OctAdNative *)nativeAd;

4.3 原生广告示例代码

self.nativeAd = [[OctAdNative alloc] initWithSlotId:@"slotid"];
self.nativeAd.delegate = self;
self.nativeAd.controller = self;
[self.nativeAd loadAd];

- (void)octad_nativeSuccessToLoad:(OctAdNative *)nativeAd {
    NSLog(@"广告加载成功");
    UIView *adView = adModel.nativeAdViews.firstObject;
    [self.adView removeFromSuperview];
    self.adView = adView;
    [self.view addSubview:adView];
}

// 广告关闭
- (void)octad_nativeAdViewDidClose:(OctAdNative *)nativeAd {
    NSLog(@"广告关闭");
    [self.adView removeFromSuperview];
}

五、原生（信息流）自渲染广告

原生自渲染广告与原生模板广告的接口是一样的，在加载成功后取的是 adDataModels 属性里面的值，使用 OctNativeAdDataModel。 **注意：**需要在 Model 中进行容器和可点击 view 的绑定，否则会缺失曝光和点击回调

5.1 原生自渲染广告 OctNativeAdDataModel 说明

@interface OctNativeAdDataModel : NSObject
//  按钮文字
@property (nonatomic, strong, readonly) NSString *octAction;
//  广告标题
@property (nonatomic, strong, readonly) NSString *octHeadline;
//  广告图片素材
@property (nonatomic, strong, readonly) NSArray *octImages;
//  广告文字素材
@property (nonatomic, strong, readonly) NSArray *octTexts;
//  广告视频素材
@property (nonatomic, strong, readonly) NSArray *octVideos;
//  广告素材宽
@property (nonatomic, assign, readonly) NSInteger octWidth;
//  广告素材高
@property (nonatomic, assign, readonly) NSInteger octHeight;
// 由于广告法规定，必须添加logo，（建议：广告图片放置在广告的左下角，logo放置在广告的右下角）
//  广告图片，当此字符串不为空时，加载adLabelURL的图片。
@property (nonatomic, strong, readonly) NSString *octLabelURL;
//  广告文字，当adLabelURL为空时，使用adLabel的文字
@property (nonatomic, strong, readonly) NSString *octLabel;
//  logo图片，当此字符串不为空时，加载logoURL的图片。
@property (nonatomic, strong, readonly) NSString *octLogoURL;
//  logo文字，当logoURL为空时，使用logoLabel的文字
@property (nonatomic, strong, readonly) NSString *octLogoLabel;

// 绑定展示视图和广告点击View（该视图点击可以跳转到落地页）
- (void)bindVieWithContainer:(UIView *)containerView clickableViews:(NSArray *)clickableViews;
// 添加关闭视图（该视图点击，可以关闭广告）
- (void)addADCloseTarget:(UIView*)targetView;
/**
 SDK内部方法，无需调用与使用
 */
- (instancetype)initWithData:(OctSDKResponseModel *)octAdResponse;

@end

5.2 原生广告回调说明

// 加载成功
- (void)octad_nativeSuccessToLoad:(OctAdNative *)nativeAd;

// 加载失败
- (void)octad_nativeAd:(OctAdNative *)nativeAd didFailWithError:(NSError * _Nullable)error;

// 广告曝光
- (void)octad_nativeDidVisible:(OctAdNative *)nativeAd;

// 广告点击
- (void)octad_nativeAdViewDidClick:(OctAdNative *)nativeAd;

// 广告关闭
- (void)octad_nativeAdViewDidClose:(OctAdNative *)nativeAd;

// 广告落地页关闭
- (void)octad_nativeAdViewWillCloseOtherView:(OctAdNative *)nativeAd;

5.3 原生广告示例代码

self.nativeAd = [[OctAdNative alloc] initWithSlotId:"slotid" isSelfRender:YES];
self.nativeAd.delegate = self;
self.nativeAd.controller = self;
[self.nativeAd loadAd];

- (void)octad_nativeSuccessToLoad:(OctAdNative *)nativeAd {
    NSLog(@"广告加载成功");
     OctNativeAdDataModel *adModel = nativeAd.adDataModels.firstObject;
    UIImageView *adView = [[UIImageView alloc] initWithFrame:CGRectMake(0, 200, 300, 200)];
    [self downloadDataWithURLString:adModel.octImages.firstObject andSolveBlock:^(NSData *data) {
        UIImage *image = [[UIImage alloc] initWithData:data];
        adView.image = image;
    }];
    adView.center = CGPointMake(self.view.center.x, adView.center.y);
    [adModel bindVieWithContainer:adView clickableViews:@[adView]];
    [self.view addSubview:adView];
}

六、插屏广告

6.1 插屏广告接口说明

// 插屏初始化
- (instancetype)initWithSlotId:(NSString *)slotId;

// 加载广告
- (void)loadAd;

// 获取广告返回价格
- (int)getPrice;

// 广告是否加载成功
- (BOOL)isLoaded;

// 展示广告
- (void)showAdsInViewController:(UIViewController *)viewController;

6.2 插屏广告回调说明

// 加载成功
- (void)octad_intersititalSuccessToLoad:(OctAdIntersitital *)intersititalAd;

// 加载失败
- (void)octad_intersitital:(OctAdIntersitital *)intersititalAd didFailWithError:(NSError * _Nullable)error;

// 广告曝光
- (void)octad_intersititalDidVisible:(OctAdIntersitital *)intersititalAd;

// 广告点击
- (void)octad_intersititalAdViewDidClick:(OctAdIntersitital *)intersititalAd;

// 广告关闭
- (void)octad_intersititalDidClose:(OctAdIntersitital *)intersititalAd;

// 广告落地页关闭
- (void)octad_intersititalWillCloseOtherView:(OctAdIntersitital *)intersititalAd;

6.3 插屏广告示例代码

self.interstitialAd = [[OctAdIntersitital alloc] initWithSlotId:@"广告位id"];
self.interstitialAd.delegate = self;
[self.interstitialAd loadAd];

- (void)octad_intersititalSuccessToLoad:(OctAdIntersitital *)intersititalAd {
    NSLog(@"插屏广告加载成功");
    [self.interstitialAd showAdsInViewController:self];
}

七、激励视频广告

7.1 激励视频广告接口说明

// 激励视频初始化
- (instancetype)initWithSlotId:(NSString *)slotId;

// 加载广告
- (void)loadAd;

// 获取广告返回价格
- (int)getPrice;

// 广告是否加载成功
- (BOOL)isLoaded;

// 展示广告
- (void)showAdsInViewController:(UIViewController *)viewController;

7.2 激励视频广告回调说明

// 加载成功
- (void)octad_rewardVideoSuccessToLoad:(OctAdRewardVideo *)rewardVideo;

// 加载失败
- (void)octad_rewardVideo:(OctAdRewardVideo *)rewardVideo didFailWithError:(NSError * _Nullable)error;

// 广告曝光
- (void)octad_rewardVideoDidVisible:(OctAdRewardVideo *)rewardVideo;

// 广告点击
- (void)octad_rewardVideoAdViewDidClick:(OctAdRewardVideo *)rewardVideo;

// 广告关闭
- (void)octad_rewardVideoDidClose:(OctAdRewardVideo *)rewardVideo;

// 广告播放完成
- (void)octad_rewardVideoDidFinished:(OctAdRewardVideo *)rewardVideo;

// 广告发放奖励
- (void)octad_rewardVideoDidReward:(OctAdRewardVideo *)rewardVideo;

7.3 原生广告示例代码

self.rewardVideoAd = [[OctAdRewardVideo alloc] initWithSlotId:@"广告位id"];
self.rewardVideoAd.delegate = self;
[self.rewardVideoAd loadAd];

// 加载成功
- (void)octad_rewardVideoSuccessToLoad:(OctAdRewardVideo *)rewardVideo {
    NSLog(@"激励视频广告加载成功");
    [self.rewardVideoAd showAdsInViewController:self];
}

// 广告发放奖励
- (void)octad_rewardVideoDidReward:(OctAdRewardVideo *)rewardVideo {
    NSLog(@"激励视频广告发放奖励");
}

八、横幅广告

8.1 横幅广告接口说明

// 横幅初始化
- (instancetype)initWithSlotId:(NSString *)slotId;

// 加载广告
- (void)loadAd;

// 获取广告返回价格
- (int)getPrice;

// 广告是否加载成功
- (BOOL)isLoaded;

8.2 横幅广告回调说明

// 加载成功
- (void)octad_bannerSuccessToLoad:(OctAdBanner *)bannerAd;

// 加载失败
- (void)octad_banner:(OctAdBanner *)bannerAd didFailWithError:(NSError * _Nullable)error;

// 广告曝光
- (void)octad_bannerDidVisible:(OctAdBanner *)bannerAd;

// 广告点击
- (void)octad_bannerAdViewDidClick:(OctAdBanner *)bannerAd;

// 广告关闭
- (void)octad_bannerDidClose:(OctAdBanner *)bannerAd;

// 广告落地页关闭
- (void)octad_bannerWillCloseOtherView:(OctAdBanner *)bannerAd;

8.3 横幅广告示例代码

self.bannerAd = [[OctAdBanner alloc] initWithSlotId:@"广告位id"];
self.bannerAd.delegate = self;
self.bannerAd.controller = self;
[self.bannerAd loadAd];

- (void)octad_bannerSuccessToLoad:(OctAdBanner *)bannerAd {
    NSLog(@"广告加载成功");
    UIView *adView = bannerAd.adViews.firstObject;
    CGRect frame = adView.frame;
    frame.origin.y = 200;
    adView.frame = frame;
    adView.center = CGPointMake(self.view.center.x, adView.center.y);
    [self.adView removeFromSuperview];
    self.adView = adView;
    [self.view addSubview:adView];
}