讯飞广告 SDK · iOS（IFLYADLib）

讯飞广告 SDK（IFLYADLib）是科大讯飞消费者 BG「AI 营销 - ADX」面向 iOS 媒体的广告变现 SDK。一次接入即可投放开屏、Banner、插屏、自渲染信息流、激励视频五类广告，支持 CocoaPods 与 Swift Package Manager，内置隐私清单（PrivacyInfo.xcprivacy）、ATT 合规、服务端竞价（S2S）与 Header Bidding。

本文是面向接入方（媒体开发者）的对外接入文档：从环境要求、安装、隐私合规，到逐类广告的完整调用链与回调、错误码、最佳实践，按行业规范组织，照着做即可跑通。

三个仓库分别是什么

这个项目对外有三套产物，请根据需要选用——接入方通常只需要"公开库"或"定制库"中的一套：

选择建议：常规媒体接入用公开库 IFLYADLib；需要避免与其他广告库符号冲突、或要求资源自包含/动态库交付的，用定制库 YSIFLYADLib。两者 API 形态一致，仅命名与交付方式不同（详见 公开库与定制库差异）。

能力一览

环境要求

安装 SDK

方式一：CocoaPods（推荐）

公开库 IFLYADLib 支持"按广告形式可组合接入"：Core 必选，其余格式按需选用，VideoUI（视频播放容器）由依赖关系自动带入。只接入需要的格式可显著减小包体。

完整 Podfile 示例：

source 'https://cdn.cocoapods.org/'
platform :ios, '13.0'

target 'YourApp' do
  use_frameworks!

  # 全量：五类广告 + VideoUI + 内置资源
  pod 'IFLYADLib', '6.0.7'

  # 或按需组合（Core 隐式必选；Splash / Interstitial / Reward 会自动带入 VideoUI）
  # pod 'IFLYADLib/Splash', '6.0.7'
  # pod 'IFLYADLib/Banner', '6.0.7'
  # pod 'IFLYADLib/NativeFeed', '6.0.7'
end

pod install --repo-update

可选 subspec：Core（必选）、Banner、Splash、Interstitial、NativeFeed、Reward、Full（默认，等于全选）。

方式二：Swift Package Manager

在 Xcode File › Add Package Dependencies… 中输入仓库地址，选择版本 6.0.7，按需勾选 product：

https://github.com/LJMcarryu/IFLYADLib_iOS

可选 product 与 subspec 同名：Core（必选）、Banner、Splash、Interstitial、NativeFeed、Reward、Full。

导入头文件

统一使用伞头即可（6.0.3 起伞头用 __has_include 守卫，全量与按格式部分安装都能正常编译，自动只导入已安装格式的入口类）：

#import <IFLYADLib/IFLYADLib.h>

隐私与合规

App Tracking Transparency（ATT）

iOS 14+ 读取 IDFA 前需请求用户授权。建议在 applicationDidBecomeActive: 或首个前台时机发起：

#import <AppTrackingTransparency/AppTrackingTransparency.h>

- (void)applicationDidBecomeActive:(UIApplication *)application {
    if (@available(iOS 14, *)) {
        if (ATTrackingManager.trackingAuthorizationStatus == ATTrackingManagerAuthorizationStatusNotDetermined) {
            [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
                NSLog(@"ATT status: %ld", (long)status);
            }];
        }
    }
}

Info.plist 需补充用途说明：

<key>NSUserTrackingUsageDescription</key>
<string>用于向你展示更相关的广告内容</string>

未授权时 IDFA 读取应返回空，由 SDK 走非个性化链路。媒体侧可把 IDFA 通过 IFLYAdRequestConfig.idfa 传入（见下一节）。

个性化与日志开关

// 媒体侧个性化推荐开关（记录媒体侧状态）
[IFLYAdConfig setPersonalizedEnabled:YES];

// SDK 日志：Debug 默认开启，正式上线前建议关闭
[IFLYAdConfig setLogEnabled:NO];

隐私清单要点

SDK 已内置 PrivacyInfo.xcprivacy：声明 NSPrivacyTracking = YES，追踪域名包含 voiceads.cn 等；采集数据类型涵盖 DeviceID、ProductInteraction、AdvertisingData（用户关联、用于追踪）与 OtherDiagnosticData；并声明了 UserDefaults（CA92.1）、文件时间戳（C617.1）、系统启动时间（35F9.1）、磁盘可用空间（E174.1）等 Required Reason API。提审前请确认隐私清单已随包合入。

初始化与请求配置

全局初始化

在 AppDelegate 启动时完成全局配置（无需 appId/secret，广告位粒度由 adUnitId 区分）：

#import <IFLYADLib/IFLYADLib.h>

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [IFLYAdConfig setPersonalizedEnabled:YES];
    [IFLYAdConfig setLogEnabled:NO];   // 正式环境关闭
    return YES;
}

统一请求配置 IFLYAdRequestConfig

每次加载广告可传入一个 IFLYAdRequestConfig，用于竞价底价、超时、设备标识等。常用字段：

封装一个工具方法复用：

+ (IFLYAdRequestConfig *)sharedRequestConfig {
    IFLYAdRequestConfig *config = [[IFLYAdRequestConfig alloc] init];
    config.settleType = @1;          // RTB
    config.bidFloor = @0.01;         // 底价 0.01 元/千次
    config.interactStatus = @1;      // 开启互动
    config.requestTimeout = @5;      // 5 秒超时
    config.appName = NSBundle.mainBundle.infoDictionary[@"CFBundleDisplayName"];
    config.appVersion = NSBundle.mainBundle.infoDictionary[@"CFBundleShortVersionString"];
    config.idfa = [self currentIDFAStringOrNil];   // ATT 未授权返回 nil
    return config;
}

通用接入范式

五类广告共享同一套生命周期：创建实例 → 设置 delegate → 发起加载 → 收到就绪回调后展示 → 用完销毁。理解这条主线，任意一种广告都能照搬。

IFLYBannerAd *ad = [[IFLYBannerAd alloc] initWithAdUnitId:adUnitId]; ad.delegate = self; ad.currentViewController = self;

[ad loadAdWithRequestConfig:[MyAds sharedRequestConfig]];

if ([ad isAdValid]) { [ad showInView:self.container]; }

ad.delegate = nil; [ad destroy];

生命周期状态 IFLYAdState：Idle → Loading → Loaded → Ready → Showing → Exposed → Closed → Destroyed，异常进入 Failed。其中信息流（NativeFeed）没有 Ready 阶段，Loaded 之后直接进入绑定（bind），其余四类才经过 Ready（即 didReady）。

通用约束（适用于全部广告类型）：

• 强持有广告对象：用属性持有，loadAd 后不要让对象被提前释放。
• delegate 为弱引用：在 dealloc / 退出页面前把 delegate = nil，再 destroy，避免野指针回调。
• 先 didReady 后展示：didLoad 仅表示响应解析成功，素材未必下载完；didReady（或对应"就绪"回调）才可展示。
• 一次性消费：广告已展示 / 已关闭 / 已销毁后不可再次 loadAd，需新建实例。
• 替换真实广告位：示例中的 adUnitId 仅供演示，上线前替换为平台分配的正式广告位。

下面逐类给出完整调用链与关键回调。

开屏广告 Splash

开屏不走 present，而是直接加到 window 上展示，带倒计时、跳过与可选的"摇一摇/扭一扭"互动。

@interface SplashVC () <IFLYSplashAdDelegate>
@property (nonatomic, strong) IFLYSplashAd *splashAd;
@end

@implementation SplashVC

- (void)loadAd {
    IFLYSplashAd *ad = [[IFLYSplashAd alloc] initWithAdUnitId:adUnitId];
    ad.delegate = self;
    ad.currentViewController = self;
    self.splashAd = ad;
    [ad loadAdWithRequestConfig:[MyAds sharedRequestConfig]];
}

// 主素材就绪，可以展示
- (void)splashAdDidReady:(IFLYSplashAd *)ad {
    if (![ad isAdValid]) return;

    IFLYSplashAdConfig *config = [[IFLYSplashAdConfig alloc] init];
    config.traceDuration = 5;                 // 倒计时秒数（3–5，默认 5）
    config.mediumBottomView = [self logoView]; // 底部自定义 Logo 区
    config.muteOnStart = YES;                  // 视频起播静音
    config.showNoAds = NO;                     // 是否显示"免除广告"按钮
    [ad showAdFromRootViewController:self config:config];
}

- (void)splashAdDidExpose:(IFLYSplashAd *)ad { /* 曝光计费成立 */ }
- (void)splashAdDidClick:(IFLYSplashAd *)ad { /* 点击 */ }
- (void)splashAdDidSkip:(IFLYSplashAd *)ad  { /* 用户跳过 */ }
- (void)splashAdDidClose:(IFLYSplashAd *)ad { [self enterApp]; }   // 关闭后进主界面
- (void)splashAd:(IFLYSplashAd *)ad didFailWithError:(IFLYAdError *)error {
    NSLog(@"开屏失败 %ld %@", (long)error.errorCode, error.errorDescription);
    [self enterApp];
}

- (void)dealloc {
    self.splashAd.delegate = nil;
    [self.splashAd destroy];
}
@end

IFLYSplashAdConfig 关键属性：traceDuration（倒计时 3–5s）、mediumBottomView（底部自定义视图）、customWindow（自定义承载 window）、headingInteractionEnabled（摇一摇/扭一扭）、showNoAds（"免除广告"按钮）、muteOnStart / muteButtonHidden。

主要回调（IFLYSplashAdDelegate）：

Banner 广告

Banner 展示到媒体提供的容器中，容器宽度需 > 0，高度为 0 时按素材自适应。

@interface BannerVC () <IFLYBannerAdDelegate>
@property (nonatomic, strong) IFLYBannerAd *bannerAd;
@end

@implementation BannerVC

- (void)loadAd {
    IFLYBannerAd *ad = [[IFLYBannerAd alloc] initWithAdUnitId:adUnitId];
    ad.delegate = self;
    ad.currentViewController = self;
    ad.closeButtonVisible = YES;     // 右上角关闭按钮
    self.bannerAd = ad;
    [ad loadAdWithRequestConfig:[MyAds sharedRequestConfig]];
}

- (void)bannerAdDidReady:(IFLYBannerAd *)ad {
    if ([ad isAdValid]) {
        [ad showInView:self.bannerContainer];   // 展示到容器
    }
}

- (void)bannerAdDidClose:(IFLYBannerAd *)ad { [self.bannerContainer removeFromSuperview]; }
- (void)bannerAd:(IFLYBannerAd *)ad didFailWithError:(IFLYAdError *)error {
    NSLog(@"Banner 失败 %ld %@", (long)error.errorCode, error.errorDescription);
}

- (void)dealloc {
    self.bannerAd.delegate = nil;
    [self.bannerAd destroy];
}
@end

主要回调（IFLYBannerAdDelegate）：bannerAdDidLoad:、bannerAdDidReady:（可 showInView:）、bannerAdDidExpose:、bannerAdDidClick:、bannerAdDidClose:（用户关闭）、bannerAd:didFailWithError:。

插屏广告 Interstitial

插屏以 present 方式弹出，支持半屏 / 全屏两种样式，图片与视频素材。

@interface InterstitialVC () <IFLYInterstitialAdDelegate>
@property (nonatomic, strong) IFLYInterstitialAd *interstitialAd;
@end

@implementation InterstitialVC

- (void)loadAd {
    IFLYInterstitialAd *ad = [[IFLYInterstitialAd alloc] initWithAdUnitId:adUnitId];
    ad.delegate = self;
    ad.currentViewController = self;
    self.interstitialAd = ad;
    [ad loadAdWithRequestConfig:[MyAds sharedRequestConfig]];
}

- (void)interstitialAdDidReady:(IFLYInterstitialAd *)ad {
    if (![ad isAdValid]) return;

    IFLYInterstitialAdConfig *config = [[IFLYInterstitialAdConfig alloc] init];
    config.presentationStyle = IFLYInterstitialPresentationStyleHalfScreen; // 或 FullScreen
    config.muteOnStart = YES;
    [ad showAdFromRootViewController:self config:config];
}

- (void)interstitialAdDidClose:(IFLYInterstitialAd *)ad { /* 关闭 */ }
- (void)interstitialAd:(IFLYInterstitialAd *)ad didFailWithError:(IFLYAdError *)error {
    NSLog(@"插屏失败 %ld %@", (long)error.errorCode, error.errorDescription);
}

- (void)dealloc {
    self.interstitialAd.delegate = nil;
    [self.interstitialAd destroy];
}
@end

展示样式枚举：

typedef NS_ENUM(NSInteger, IFLYInterstitialPresentationStyle) {
    IFLYInterstitialPresentationStyleHalfScreen = 0,  // 半屏（默认）
    IFLYInterstitialPresentationStyleFullScreen = 1,  // 全屏
};

主要回调（IFLYInterstitialAdDelegate）：interstitialAdDidLoad:、interstitialAdDidReady:、interstitialAdDidShow:、interstitialAdDidRender: / didFailToRenderWithError:、interstitialAdDidExpose:、interstitialAdDidClick:、视频事件（interstitialAdDidStartPlay: / interstitialAdDidPlayFinish: / interstitialAd:didFailToPlayWithError: 等）、interstitialAdDidClose:、interstitialAd:didFailWithError:。

信息流广告 Native Feed

信息流是自渲染：SDK 只回传素材数据（adData），由媒体侧用自己的原生控件排版，再通过 IFLYNativeFeedAdViewBinder 把容器、点击区、关闭按钮、视频承载视图交还给 SDK 完成曝光与点击监测。SDK 不会向你的容器添加任何 UI。

@interface NativeVC () <IFLYNativeFeedAdDelegate>
@property (nonatomic, strong) IFLYNativeFeedAd *nativeAd;
@end

@implementation NativeVC

- (void)loadAd {
    IFLYNativeFeedAd *ad = [[IFLYNativeFeedAd alloc] initWithAdUnitId:adUnitId];
    ad.delegate = self;
    ad.currentViewController = self;
    ad.muteOnStart = YES;
    self.nativeAd = ad;
    [ad loadAdWithRequestConfig:[MyAds sharedRequestConfig]];
}

// 1) 请求成功：读取素材数据，用媒体侧控件自行渲染
- (void)nativeFeedAdDidLoad:(IFLYNativeFeedAd *)ad {
    IFLYNativeFeedAdData *data = ad.adData;
    self.titleLabel.text = data.title;
    self.descLabel.text  = data.desc ?: data.content;
    [self.ctaButton setTitle:(data.actionText ?: @"查看详情") forState:UIControlStateNormal];
    // 按 data.materialType 渲染单图 / 三图 / 视频；图片地址见 data.imageURLs，视频见 data.videoURL

    // 2) 渲染完成后绑定给 SDK
    IFLYNativeFeedAdViewBinder *binder = [[IFLYNativeFeedAdViewBinder alloc] init];
    binder.containerView = self.adContainer;                                  // 必填
    binder.renderViews   = @[self.mediaContainer, self.titleLabel, self.descLabel, self.ctaButton];
    binder.clickViews    = @[self.mediaContainer, self.ctaButton];           // 可点击区
    binder.closeView     = self.closeButton;
    binder.videoView     = ad.hasVideoTemplate ? self.mediaContainer : nil;  // 视频素材必填

    IFLYAdError *error = nil;
    if (![ad bindAdWithViewBinder:binder error:&error]) {
        NSLog(@"信息流绑定失败 %ld %@", (long)error.errorCode, error.errorDescription);
    }
}

- (void)nativeFeedAdDidRender:(IFLYNativeFeedAd *)ad {
    if (ad.hasVideoTemplate) { [ad startPlay]; }
}

- (void)nativeFeedAdDidClose:(IFLYNativeFeedAd *)ad { /* 用户关闭 */ }

// 列表 cell 复用前务必解绑
- (void)prepareForReuse {
    [self.nativeAd unbindAd];
}

- (void)dealloc {
    self.nativeAd.delegate = nil;
    [self.nativeAd destroy];
}
@end

素材类型枚举：

typedef NS_ENUM(NSInteger, IFLYNativeFeedAdMaterialType) {
    IFLYNativeFeedAdMaterialTypeUnknown     = 0,
    IFLYNativeFeedAdMaterialTypeSingleImage = 1,  // 单图
    IFLYNativeFeedAdMaterialTypeThreeImages = 2,  // 三图
    IFLYNativeFeedAdMaterialTypeVideo       = 3,  // 视频
};

IFLYNativeFeedAdViewBinder 关键字段：containerView（必填）、renderViews、clickViews、closeView、videoView（视频素材必填），以及语义视图 titleView / descView / iconView / imageView / adSourceView / ctaView。

IFLYNativeFeedAdData 常用字段：materialType、title、desc、content、actionText、iconURL、imageURLs、videoURL、videoCoverURL、videoDuration、ecpm，并提供 isMaterialComplete 校验素材是否满足渲染要求。

主要回调（IFLYNativeFeedAdDelegate）：nativeFeedAdDidLoad:（自渲染）、nativeFeedAdDidRender:（绑定成功）/ didFailToRenderWithError:、nativeFeedAdDidExpose:、nativeFeedAdDidClick:、视频事件、nativeFeedAdDidClose:、nativeFeedAd:didFailWithError:。

复用要点：列表场景在 cell 复用前必须调用 unbindAd 清理绑定状态；绑定为一次性消费，unbindAd 不会把对象复位为可重新绑定。

激励视频广告 Reward

用户观看完整视频后发放奖励。发奖以 didRewardEffective: 回调为准，didClose: 仅表示广告关闭，不等同于发奖。

@interface RewardVC () <IFLYRewardVideoAdDelegate>
@property (nonatomic, strong) IFLYRewardVideoAd *rewardAd;
@end

@implementation RewardVC

- (void)loadAd {
    IFLYRewardVideoAd *ad = [[IFLYRewardVideoAd alloc] initWithAdUnitId:adUnitId];
    ad.delegate = self;
    ad.currentViewController = self;
    self.rewardAd = ad;
    [ad loadAdWithRequestConfig:[MyAds sharedRequestConfig]];
}

- (void)rewardVideoAdDidReady:(IFLYRewardVideoAd *)ad {
    if (![ad isAdValid]) return;
    IFLYRewardVideoAdConfig *config = [[IFLYRewardVideoAdConfig alloc] init];
    config.muteOnStart = YES;
    [ad showAdFromRootViewController:self config:config];
}

// 激励发放生效 —— 在这里给用户发奖
- (void)rewardVideoAd:(IFLYRewardVideoAd *)ad didRewardEffective:(NSDictionary *)info {
    [self grantRewardToUser];
}

- (void)rewardVideoAdDidClose:(IFLYRewardVideoAd *)ad { /* 关闭，不在此发奖 */ }
- (void)rewardVideoAd:(IFLYRewardVideoAd *)ad didFailWithError:(IFLYAdError *)error {
    NSLog(@"激励失败 %ld %@", (long)error.errorCode, error.errorDescription);
}

- (void)dealloc {
    self.rewardAd.delegate = nil;
    [self.rewardAd destroy];
}
@end

主要回调（IFLYRewardVideoAdDelegate）：rewardVideoAdDidLoad:、rewardVideoAdDidReady:、rewardVideoAdDidShow:、rewardVideoAdDidExpose:、rewardVideoAdDidClick:、视频事件、rewardVideoAd:didRewardEffective:（发奖准绳）、rewardVideoAdDidClose:、rewardVideoAd:didFailWithError:。

服务端竞价与 Header Bidding

客户端获取 SDK 竞价 Token（S2S）

NSError *error = nil;
NSString *sdkToken = [IFLYAdSDK getSdkTokenWithAdUnitId:@"YOUR_AD_UNIT_ID" error:&error];
if (!sdkToken) {
    NSLog(@"获取 SDK Token 失败: %@", error);
}
// 将 sdkToken 上送你的服务端，向 ADX 发起服务端竞价，拿到 rspToken 后回传客户端

用服务端竞价结果加载（所有广告类型通用）

[splashAd       loadAdWithServerBiddingToken:rspToken];
[bannerAd       loadAdWithServerBiddingToken:rspToken];
[interstitialAd loadAdWithServerBiddingToken:rspToken];
[nativeAd       loadAdWithServerBiddingToken:rspToken];
[rewardAd       loadAdWithServerBiddingToken:rspToken];

Header Bidding 胜负通知

if (ad.bidInfo.winNoticeAvailable) {
    [ad sendBidResultWithType:IFLYAdBidResultTypeWin reason:@"win"];
} else {
    [ad sendBidResultWithType:IFLYAdBidResultTypeLoseBidLower reason:@"loss"];
}

竞价结果类型 IFLYAdBidResultType：Win = 100、LoseBidLower = 101、LoseCreativePending = 102、LoseCreativeRejected = 103、LosePriorityLower = 104、Error = 105、Timeout = 106。

错误码

所有失败统一通过各广告的 ...didFailWithError: 回调返回 IFLYAdError，读取 error.errorCode 与 error.errorDescription。错误码按段划分：

服务端（70xxx）

通用客户端（71xxx）

各广告专属段：激励视频 712xx、Banner 713xx、插屏 714xx、信息流 715xx、开屏 716xx（例如 71203 激励未就绪、71308 Banner 未就绪、71406 插屏未就绪、71505 信息流未就绪、71603 开屏未就绪；以及各类"已展示/已过期/已销毁/素材无效"等细分码）。

公开库与定制库差异

定制库 YSIFLYADLib 与公开库 API 形态一致，但做了白标改造，主要差异如下：

定制库安装（CocoaPods 经 raw podspec 直连）：

source 'https://cdn.cocoapods.org/'
platform :ios, '13.0'

target 'YourApp' do
  use_frameworks!
  pod 'YSIFLYADLib', :podspec => 'https://raw.githubusercontent.com/LJMcarryu/YSIFLYADLib_iOS/6.0.7/YSIFLYADLib.podspec'
end

SPM：https://github.com/LJMcarryu/YSIFLYADLib_iOS.git，版本 6.0.7，product YSIFLYADLib。

调用对照（以开屏为例）：

// 公开库（方法名无前缀，与前文主线一致：统一传 IFLYAdRequestConfig）
IFLYSplashAd *ad = [[IFLYSplashAd alloc] initWithAdUnitId:@"xxx"];
[ad loadAdWithRequestConfig:[MyAds sharedRequestConfig]];
// …didReady 后：[ad showAdFromRootViewController:self config:config];

// 定制库（类名加 YS 前缀、方法加 ysifly_ 前缀，调用形态与公开库一致）
YSIFLYSplashAd *ad = [[YSIFLYSplashAd alloc] initWithAdUnitId:@"xxx"];
[ad ysifly_loadAdWithRequestConfig:[MyAds sharedRequestConfig]];
// …didReady 后：[ad ysifly_showAdFromRootViewController:self config:config];

最佳实践

• 提前加载、就绪展示：开屏/激励等强曝光场景建议提前发起 loadAd，在 didReady 后再展示，缩短用户等待。
• 每次展示新建实例：广告对象一次性消费，展示/关闭后请重新 initWithAdUnitId: 创建。
• 正确释放：退出页面或 dealloc 时先 delegate = nil 再 destroy；信息流 cell 复用前 unbindAd。
• 失败要兜底：开屏/插屏在 didFailWithError: 与 didClose: 都要保证业务流程继续（如进入主界面）。
• 激励发奖只认回执：仅在 didRewardEffective: 发奖，避免重复或漏发。
• 上线前收尾：关闭 setLogEnabled:、替换正式广告位、确认隐私清单与 ATT 文案已就绪。

常见问题

版本与支持

从 6.0.0 升级到 6.0.7：业务 API 无变化，可改为按广告形式组合接入；CocoaPods 直接升级版本号即可，无需改业务代码。

• 公开库：github.com/LJMcarryu/IFLYADLib_iOS · 通过 Issue 反馈问题（暂不接受外部 PR；安全漏洞请私密上报）
• 定制库：github.com/LJMcarryu/YSIFLYADLib_iOS
• 各仓库均自带可运行示例工程（公开库 IFLYADLibSimple、定制库 YSIFLYADLibSimple），覆盖全部广告类型，可对照源码接入。