DeepAdx iOS 接入文档
本文面向 Objective-C 项目,说明 DeepAdxSDK 的环境要求、集成方式、初始化与各广告位调用。
1. 环境要求
| 项目 | 要求 |
|---|---|
| iOS | 12.0+ |
| Xcode | 建议 14+ |
| CocoaPods | 1.10.0+ |
| 语言 | Objective-C(Swift 见 Swift 接入文档) |
2. 集成方式
2.1 CocoaPods(推荐)
在业务工程 Podfile 中配置:
platform :ios, '12.0'
source 'https://cdn.cocoapods.org/'
# 核心模块(必选)
pod 'DeepAdxSDK', '2.0.6'
# 国内渠道
pod 'DeepAdxSDK/CSJ'
pod 'DeepAdxSDK/GDT'
pod 'DeepAdxSDK/KS'
pod 'DeepAdxSDK/BD'
# 海外渠道
pod 'DeepAdxSDK/GG'
pod 'DeepAdxSDK/PAG'也可一次性引入多个 subspec:
pod 'DeepAdxSDK', '2.0.6', :subspecs => ['Core', 'CSJ', 'GDT', 'KS', 'BD', 'GG', 'PAG']执行安装:
pod install --repo-update说明:新版本发布后,CocoaPods CDN 可能存在数分钟到数十分钟的同步延迟。若暂时拉不到最新版本,可稍后重试
pod install --repo-update,或使用 Git 源临时集成(见下方)。
Git 源集成(CDN 未同步时的备选):
pod 'DeepAdxSDK', :git => 'https://gitee.com/deepadx/deepadx-ios-sdk.git', :tag => '2.0.6', :subspecs => ['Core', 'CSJ', 'GDT', 'KS', 'BD', 'GG', 'PAG']2.2 手动集成
将以下产物拖入工程,并在 Target → Frameworks, Libraries, and Embedded Content 中配置:
DeepAdxCore.xcframeworkDeepAdxAdspot.xcframework- 对应渠道
DeepAdxAdapter_*.xcframework(按需)
3. 头文件导入
#import <DeepAdxCore/DeepAdxCore.h>
#import <DeepAdxAdspot/DeepAdxAdspot.h>按需导入广告位头文件:
#import <DeepAdxAdspot/DeepAdxBanner.h>
#import <DeepAdxAdspot/DeepAdxInterstitial.h>
#import <DeepAdxAdspot/DeepAdxRewardVideo.h>
#import <DeepAdxAdspot/DeepAdxSplash.h>
#import <DeepAdxAdspot/DeepAdxNativeExpress.h>4. SDK 初始化
建议在用户同意隐私政策后,于 AppDelegate 中初始化:
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
[self setupDeepAdx];
return YES;
}
- (void)setupDeepAdx {
// 调试阶段可开启 Debug 日志,上线请降级
[DeepAdxSdkConfig shareInstance].level = DeepAdxLogLevel_Debug;
DeepAdxConfigModel *model = [[DeepAdxConfigModel alloc] init];
model.debugMode = YES; // 线上请改为 NO
// App ID 从 DeepAdx 变现平台获取
[[DeepAdxSdkConfig shareInstance] registerAppID:@"YOUR_APP_ID" withConfig:model];
// 海外广告全局静音 / 音量(可选,可在 registerAppID 前后调用;未调用不干预渠道默认声音)
// 静音:广告不出声。setAdMuted 与 setAdVolume 相互独立,要静音建议两行都调。
// [DeepAdxSdkConfig setAdMuted:YES];
// [DeepAdxSdkConfig setAdVolume:0.f];
[DeepAdxSdkConfig setAdMuted:NO];
[DeepAdxSdkConfig setAdVolume:1.f];
}广告策略:初始化后不会预拉全部广告位策略;各广告位在调用
loadAd/loadAndShowAd时按需加载,并优先使用本地缓存。
合规说明:SDK 不内置 Google UMP 或渠道 Consent 弹窗。请在用户同意隐私政策后初始化;若面向欧盟等需 GDPR 合规的市场,请由 App 自行集成 UMP 或其他合规方案后再调用
registerAppID:。
4.5 广告位 ID(placementId)
同一应用下可有多个同类型广告位。在 DeepAdx 后台「广告单元」创建后会得到 placement_id(如 b3f2a1...)。接入时请始终传入 placementId,以便按广告位加载策略、隔离缓存与频控。
测试用 ID 见 示例测试 ID。
// 激励视频
self.adReward = [[DeepAdxRewardVideo alloc] initWithViewController:self
placementId:@"YOUR_PLACEMENT_ID"];
// Banner(注意方法名为 initWithAdViewController)
self.adBanner = [[DeepAdxBanner alloc] initWithAdViewController:self
placementId:@"YOUR_PLACEMENT_ID"];DeepAdxSplash、DeepAdxInterstitial、DeepAdxNativeExpress 等均提供带 placementId 的构造方法。
5. 广告位接入
5.1 Banner
@interface DemoVC () <DeepAdxBannerDelegate>
@property (nonatomic, strong) DeepAdxBanner *adBanner;
@end
- (void)loadBanner {
self.adBanner = [[DeepAdxBanner alloc] initWithAdViewController:self
placementId:@"YOUR_PLACEMENT_ID"];
self.adBanner.delegate = self;
[self.adBanner loadAndShowAd];
}
#pragma mark - DeepAdxBannerDelegate
- (void)ad_loadSuccessWithAdsType:(adsType)adsType {}
- (void)ad_loadFailure:(NSError *)error withAdsType:(adsType)adsType {}
- (void)ad_exposuredWithAdsType:(adsType)adsType {}
- (void)ad_clickedWithAdsType:(adsType)adsType {}
- (void)ad_didCloseWithAdsType:(adsType)adsType { self.adBanner = nil; }5.2 插屏
@interface DemoVC () <DeepAdxInterstitialDelegate>
@property (nonatomic, strong) DeepAdxInterstitial *adInterstitial;
@end
- (void)loadInterstitial {
self.adInterstitial = [[DeepAdxInterstitial alloc] initWithViewController:self
placementId:@"YOUR_PLACEMENT_ID"];
self.adInterstitial.delegate = self;
[self.adInterstitial loadAd];
}
- (void)showInterstitial {
[self.adInterstitial showAd];
}5.3 激励视频
@interface DemoVC () <DeepAdxRewardVideoDelegate>
@property (nonatomic, strong) DeepAdxRewardVideo *adReward;
@end
- (void)loadReward {
self.adReward = [[DeepAdxRewardVideo alloc] initWithViewController:self
placementId:@"YOUR_PLACEMENT_ID"];
self.adReward.delegate = self;
[self.adReward loadAd];
}
- (void)showReward {
[self.adReward showAd];
}
#pragma mark - DeepAdxRewardVideoDelegate
- (void)ad_rewardVideoOnAdVideoCached {} // 建议缓存完成后再展示
- (void)ad_rewardVideoAdDidRewardEffective {} // 激励达成
- (void)ad_didCloseWithAdsType:(adsType)adsType { self.adReward = nil; }服务端发奖请参考 激励视频服务端回调。
5.4 开屏
@interface DemoVC () <DeepAdxSplashDelegate>
@property (nonatomic, strong) DeepAdxSplash *adSplash;
@end
- (void)loadAndShowSplash {
self.adSplash = [[DeepAdxSplash alloc] initWithViewController:self
placementId:@"YOUR_PLACEMENT_ID"];
self.adSplash.delegate = self;
self.adSplash.timeout = 5;
self.adSplash.showLogoRequire = YES;
[self.adSplash loadAndShowAd];
}5.5 信息流(原生模板)
@interface DemoVC () <DeepAdxNativeExpressDelegate>
@property (nonatomic, strong) DeepAdxNativeExpress *adNative;
@end
- (void)loadNative {
self.adNative = [[DeepAdxNativeExpress alloc] initWithViewController:self
adSize:CGSizeMake(self.view.bounds.size.width, 0)
placementId:@"YOUR_PLACEMENT_ID"];
// 可选:Feed 使用 Medium,列表嵌入用 Small(默认)
// self.adNative.templateStyle = DeepAdxNativeTemplateStyleMedium;
self.adNative.delegate = self;
[self.adNative loadAd];
}
#pragma mark - DeepAdxNativeExpressDelegate
- (void)ad_NativeExpressOnAdLoadSuccess:(NSArray<DeepAdxNativeExpressView *> *)views {
DeepAdxNativeExpressView *first = views.firstObject;
[first render];
[self.view addSubview:first.expressView];
}6. 回调说明
| 回调 | 含义 |
|---|---|
ad_loadSuccess... | 广告加载成功 |
ad_loadFailure... | 加载失败或策略拦截 |
ad_exposured... | 广告曝光 |
ad_clicked... | 广告点击 |
ad_didClose... | 广告关闭 |
加载过程中若某一渠道失败,SDK 会继续尝试其他渠道;请勿在失败回调中过早销毁广告对象,以免中断后续加载。
7. 上线检查清单
- [ ] 已调用
registerAppID:withConfig: - [ ] 初始化在用户同意隐私政策之后
- [ ]
viewController展示时仍有效 - [ ] Banner / 信息流容器有可见尺寸
- [ ] 接入 GG 时已配置
GADApplicationIdentifier(模板 XIB 随DeepAdxSDK/GG的DeepAdxGGTemplates.bundle自动打入 App,无需GGResource.bundle) - [ ] 关闭回调中释放广告实例
8. 常见问题
Q:pod install 找不到 DeepAdxSDK 某版本?
A:确认版本号正确;执行 pod install --repo-update;新版本发布后 CDN 可能有延迟,可暂用 Git 源集成。
Q:广告加载成功但不展示?
A:检查容器视图尺寸、viewController 是否有效、广告视图是否在可见层级。
Q:完整 Demo 在哪?
A:Gitee DeepAdxSDK → Example/DeepAdxDebug(OC)、Example/DeepAdxSwift(Swift)。在线体验:蒲公英 deepadxsdk-ios(内测签名,需已登记设备)。Flutter Demo 见 deepadxsdk-ios-flutter。
