iOS 接入指南

本指南说明 iOS App（Objective-C）如何接入 KeyPuff SDK：安装依赖、初始化，以及各广告格式的接入代码。示例 API 与类名均取自 SDK 源码与 Example 工程。

环境要求

Xcode 14.1 及以上；
iOS 12 及以上；
调试阶段建议使用真机，以便获取 IDFA。

隐私与 ATT

从 iOS 14 开始，IDFA 需用户在系统弹窗中授权（ATT）。请在 Info.plist 中添加用户跟踪用途描述：

xml

<key>NSUserTrackingUsageDescription</key>
<string>该标识符将用于向您投放个性化广告</string>

用户拒绝跟踪授权后，SDK 会在广告请求中携带 donottrack=1，KeyPuff 将不做个性化投放。更多合规要求（先同意后初始化等）见 SDK 合规接入指引。

安装（CocoaPods）

核心 SDK 由 KeyPuff 自建制品仓库分发：Podfile 顶层声明 KeyPuff 私有 specs 仓库（Gitea）+ 官方 CDN，再按坐标引入：

ruby

# Podfile 顶层（source 声明必须在 target 之外）
source 'https://cdn.cocoapods.org/'
source 'https://gitea.example.com/keypuff/specs.git'   # KeyPuff 私有 specs 仓库（以控制台给出的地址为准）

target 'YourApp' do
  use_frameworks!
  platform :ios, '12.0'

  # 核心 SDK（必须，KeyPuff 补丁版：服务基址与密钥已在出包时写入）
  pod 'AdvanceSDK', '5.6.1-kp1'

  # 渠道 adapter（按需，示例；第三方渠道 SDK 来自官方 CDN）：
  # pod 'AdvanceSDK/MercuryAdapter'   # 倍业
  # pod 'AdvanceSDK/CSJAdapter'       # 穿山甲
  # pod 'AdvanceSDK/GDTAdapter'       # 优量汇
  # pod 'AdvanceSDK/KSAdapter'        # 快手
  # pod 'AdvanceSDK/BaiduAdapter'     # 百度
  # pod 'AdvanceSDK/TanxAdapter'      # 阿里 Tanx
  # pod 'AdvanceSDK/SigmobAdapter'    # Sigmob
  # …
end

无法访问 specs 仓库（Gitea）时，也可以直接引用制品仓库上的 podspec：

ruby

pod 'AdvanceSDK', '5.6.1-kp1', :podspec => 'https://repo.creative.zadervice.com/pods-specs/AdvanceSDK/5.6.1-kp1/AdvanceSDK.podspec'

每个 adapter 还需集成对应渠道方的 SDK 依赖。确切的依赖行、specs 仓库地址与版本号以控制台「SDK 中心」按您的应用生成的列表为准（该列表已排除 App 自接的渠道），复制后执行 pod install。

初始化

在应用启动时用 appid（应用 id） 初始化，appid 在控制台「应用与广告位」查看：

objc

// AppDelegate.m —— 应用启动时初始化
#import <AdvanceSDK/AdvanceSDKManager.h>

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [AdvanceSDKManager setAppId:@"100001"];   // 替换为控制台分配的应用 id（appid）
    // [AdvanceSDKManager openDebug:YES];    // 调试日志（仅联调时开启）
    return YES;
}

初始化时机

必须在用户同意 App 隐私政策之后调用初始化，详见 SDK 合规接入指引。

开屏

objc

#import <AdvanceSDK/AdvanceSplash.h>

@interface SplashViewController () <AdvanceSplashDelegate>
@property (strong) AdvanceSplash *splashAd;
@end

_splashAd = [[AdvanceSplash alloc] initWithAdspotId:@"10000001" extra:nil delegate:self]; // 替换为您的 adspotid
_splashAd.viewController = self;
// _splashAd.bottomLogoView = bottomLogoView;   // 可选：底部 Logo
[_splashAd loadAd];

// delegate（@optional）
- (void)onSplashAdDidLoad:(AdvanceSplash *)splashAd {
    if (splashAd.isAdValid) [splashAd showAdInWindow:self.view.window];
}
- (void)onSplashAdFailToLoad:(AdvanceSplash *)splashAd error:(NSError *)error {}
- (void)onSplashAdExposured:(AdvanceSplash *)splashAd {}
- (void)onSplashAdClicked:(AdvanceSplash *)splashAd {}
- (void)onSplashAdClosed:(AdvanceSplash *)splashAd {}

横幅

objc

#import <AdvanceSDK/AdvanceBanner.h>

@interface ViewController () <AdvanceBannerDelegate>
@property (strong) AdvanceBanner *bannerAd;
@end

_bannerAd = [[AdvanceBanner alloc] initWithAdspotId:@"10000002" extra:nil delegate:self];
_bannerAd.adSize = CGSizeMake(375, 120);      // 广告位尺寸
_bannerAd.viewController = self;
[_bannerAd loadAd];

// delegate（@optional）
- (void)onBannerAdDidLoad:(AdvanceBanner *)bannerAd {
    [self.view addSubview:bannerAd.bannerView];   // 广告视图
}
- (void)onBannerAdFailToLoad:(AdvanceBanner *)bannerAd error:(NSError *)error {}
- (void)onBannerAdExposured:(AdvanceBanner *)bannerAd {}
- (void)onBannerAdClicked:(AdvanceBanner *)bannerAd {}
- (void)onBannerAdClosed:(AdvanceBanner *)bannerAd {}

插屏

objc

#import <AdvanceSDK/AdvanceInterstitial.h>

@interface ViewController () <AdvanceInterstitialDelegate>
@property (strong) AdvanceInterstitial *interstitialAd;
@end

_interstitialAd = [[AdvanceInterstitial alloc] initWithAdspotId:@"10000003" extra:nil delegate:self];
// _interstitialAd.muted = YES;   // 视频是否静音，默认 YES
[_interstitialAd loadAd];

// delegate（@optional）
- (void)onInterstitialAdDidLoad:(AdvanceInterstitial *)interstitialAd {
    if (interstitialAd.isAdValid) [interstitialAd showAdFromViewController:self];
}
- (void)onInterstitialAdFailToLoad:(AdvanceInterstitial *)interstitialAd error:(NSError *)error {}
- (void)onInterstitialAdExposured:(AdvanceInterstitial *)interstitialAd {}
- (void)onInterstitialAdClosed:(AdvanceInterstitial *)interstitialAd {}

激励视频

激励视频支持服务端回调验签，如需服务端发奖请先在控制台配置激励回调：

objc

#import <AdvanceSDK/AdvanceRewardVideo.h>

@interface ViewController () <AdvanceRewardVideoDelegate>
@property (strong) AdvanceRewardVideo *rewardVideoAd;
@end

_rewardVideoAd = [[AdvanceRewardVideo alloc] initWithAdspotId:@"10000004" extra:nil delegate:self];

// 服务端验证需要（AdvRewardVideoModel，字段见 AdvanceAdInfo.h）
AdvRewardVideoModel *model = [[AdvRewardVideoModel alloc] init];
model.userId = @"userId";              // 服务端验证必须
model.rewardName = @"金币";             // 激励名称（可选）
model.rewardAmount = 1;                // 激励数量（可选）
model.extra = @"{\"k\":\"v\"}";        // 透传参数（可选）
_rewardVideoAd.rewardVideoModel = model;

[_rewardVideoAd loadAd];

// delegate（@optional）
- (void)onRewardVideoAdDidLoad:(AdvanceRewardVideo *)rewardVideoAd {
    if (rewardVideoAd.isAdValid) [rewardVideoAd showAdFromViewController:self];
}
- (void)onRewardVideoAdDidRewardSuccess:(AdvanceRewardVideo *)rewardVideoAd rewardInfo:(AdvRewardCallbackInfo *)rewardInfo {}
- (void)onRewardVideoAdDidServerRewardFail:(AdvanceRewardVideo *)rewardVideoAd error:(NSError *)error {}
- (void)onRewardVideoAdDidPlayFinish:(AdvanceRewardVideo *)rewardVideoAd {}
- (void)onRewardVideoAdFailToLoad:(AdvanceRewardVideo *)rewardVideoAd error:(NSError *)error {}

信息流（模板渲染）

objc

#import <AdvanceSDK/AdvanceNativeExpress.h>

@interface ViewController () <AdvanceNativeExpressDelegate>
@property (strong) AdvanceNativeExpress *nativeExpressAd;
@end

_nativeExpressAd = [[AdvanceNativeExpress alloc] initWithAdspotId:@"10000005" extra:nil delegate:self];
_nativeExpressAd.adSize = CGSizeMake(self.view.bounds.size.width, 0);   // 高度 0 自适应
_nativeExpressAd.viewController = self;
[_nativeExpressAd loadAd];

// 渲染成功后把广告视图插入自己的布局
- (void)onNativeExpressAdViewRenderSuccess:(UIView *)nativeExpressAdView {
    [self.containerView addSubview:nativeExpressAdView];
}
- (void)onNativeExpressAdSuccessToLoad:(AdvanceNativeExpress *)nativeExpressAd {}
- (void)onNativeExpressAdFailToLoad:(AdvanceNativeExpress *)nativeExpressAd error:(NSError *)error {}
- (void)onNativeExpressAdViewRenderFail:(UIView *)nativeExpressAdView error:(NSError *)error {}
- (void)onNativeExpressAdViewExposured:(UIView *)nativeExpressAdView {}
- (void)onNativeExpressAdViewClicked:(UIView *)nativeExpressAdView {}
- (void)onNativeExpressAdViewClosed:(UIView *)nativeExpressAdView {}

信息流（自渲染）

自渲染需要用返回的素材数据自行完成布局：

objc

#import <AdvanceSDK/AdvanceRenderFeed.h>

@interface ViewController () <AdvanceRenderFeedDelegate>
@property (strong) AdvanceRenderFeed *renderFeedAd;
@end

_renderFeedAd = [[AdvanceRenderFeed alloc] initWithAdspotId:@"10000006" extra:nil delegate:self];
_renderFeedAd.viewController = self;
[_renderFeedAd loadAd];

// 加载成功后拿到广告视图与数据，自行完成布局渲染
- (void)onRenderFeedAdSuccessToLoad:(AdvanceRenderFeed *)renderFeedAd
                         feedAdView:(AdvRenderFeedAdView *)feedAdView
                         feedAdData:(AdvRenderFeedAdData *)feedAdData {
    [self.containerView addSubview:feedAdView];   // 广告视图
    // feedAdData：标题 / 描述 / 图标等素材，用于自渲染布局
}
- (void)onRenderFeedAdFailToLoad:(AdvanceRenderFeed *)renderFeedAd error:(NSError *)error {}
- (void)onRenderFeedAdViewExposured:(AdvRenderFeedAdView *)feedAdView {}
- (void)onRenderFeedAdViewClicked:(AdvRenderFeedAdView *)feedAdView {}
- (void)onRenderFeedAdDidCloseDetailPage:(AdvRenderFeedAdView *)feedAdView {}
- (void)onRenderFeedAdDidPlayFinish:(AdvRenderFeedAdView *)feedAdView {}

全屏视频

objc

#import <AdvanceSDK/AdvanceFullScreenVideo.h>

@interface ViewController () <AdvanceFullScreenVideoDelegate>
@property (strong) AdvanceFullScreenVideo *fullScreenVideoAd;
@end

_fullScreenVideoAd = [[AdvanceFullScreenVideo alloc] initWithAdspotId:@"10000007" extra:nil delegate:self];
// _fullScreenVideoAd.muted = YES;   // 视频是否静音，默认 YES
[_fullScreenVideoAd loadAd];

// delegate（@optional）
- (void)onFullScreenVideoAdDidLoad:(AdvanceFullScreenVideo *)fullscreenVideoAd {
    if (fullscreenVideoAd.isAdValid) [fullscreenVideoAd showAdFromViewController:self];
}
- (void)onFullScreenVideoAdFailToLoad:(AdvanceFullScreenVideo *)fullscreenVideoAd error:(NSError *)error {}
- (void)onFullScreenVideoAdDidPlayFinish:(AdvanceFullScreenVideo *)fullscreenVideoAd {}
- (void)onFullScreenVideoAdClosed:(AdvanceFullScreenVideo *)fullscreenVideoAd {}

Draw 视频

暂不支持

iOS SDK 暂未提供竖版视频（Draw）广告类型（SDK 源码中无对应广告位类）。如需 Draw 变现，请使用 Android 端。

下一步

集成各渠道 adapter：Adapter 集成
激励视频服务端验签：激励视频服务端回调
遇到问题：常见问题

iOS 接入指南 ​

环境要求 ​

隐私与 ATT ​

安装（CocoaPods） ​

初始化 ​

开屏 ​

横幅 ​

插屏 ​

激励视频 ​

信息流（模板渲染） ​

信息流（自渲染） ​

全屏视频 ​

Draw 视频 ​

下一步 ​

iOS 接入指南

环境要求

隐私与 ATT

安装（CocoaPods）

初始化

开屏

横幅

插屏

激励视频

信息流（模板渲染）

信息流（自渲染）

全屏视频

Draw 视频

下一步