SDK 接入指南

媒体侧把 yimeng 集成到 App、初始化、调用 5 种广告位的完整流程。

环境要求

项	版本
iOS Deployment Target	14.0+
Xcode	14+（在 Xcode 26 验证）
语言	Objective-C / Swift（OC 桥接）

一、引入 SDK

CocoaPods（推荐）

在业务工程的 Podfile 中添加：

然后执行：

pod install

之后打开业务工程的 .xcworkspace，在代码中引入：

#import <yimeng/yimeng.h>

yimeng_ios_release 是二进制发布仓库，只包含对外接入所需的 yimeng.xcframework、yimeng.podspec 和对外说明，不包含 SDK 源码。
当前 Gitea HTTPS 证书与域名不匹配，CocoaPods 使用 https://git.zhaomuqingyun.com/... 会拉取失败；证书修复前请使用上面的 HTTP 地址，或在具备 SSH key 的环境中使用 SSH 地址。

XCFramework 手动接入

如果不使用 CocoaPods，也可以使用发版产物中的 yimeng.xcframework 手动接入。

把 yimeng.xcframework 拖进自己的 App target，General → Frameworks, Libraries, and Embedded Content 里选 Do Not Embed（静态 framework）。

必要的依赖

SDK 内部依赖以下系统 framework，Pod 接入会自动 link；手动接入时如果宿主工程未自动带出，请在 Link Binary With Libraries 中补齐：

Foundation / UIKit

AVFoundation（视频播放）

AdSupport / AppTrackingTransparency（IDFA）

CoreTelephony / SystemConfiguration（运营商/网络类型）

SafariServices（落地页）

CoreMotion（开屏摇一摇）

Info.plist 配置

<key>NSUserTrackingUsageDescription</key>
<string>用于个性化广告投放</string>

<!-- 如果对接的接口是 http 或落地页含 http -->
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

二、初始化 SDK

在 AppDelegate 或 SceneDelegate 早期阶段调用一次。仅两个必填参数，其他自动从 Info.plist 取。

#import <yimeng/yimeng.h>

QLSdkConfig *config = QLSdkConfig.builder
                        .setMediaId(@"YOUR_MEDIA_ID")
                        .setMediaSecret(@"YOUR_MEDIA_SECRET")
                        .setDebug(YES)              // 调试期打开，会输出请求/响应详细日志
                        .build;

[QLSdk initSdkWithConfig:config
                 success:^{
    NSLog(@"SDK 初始化成功");
} failure:^(NSInteger code, NSString *message) {
    NSLog(@"SDK 初始化失败 code=%ld msg=%@", (long)code, message);
}];

appName / appVersion / appVersionCode / bundleIdentifier 都由 SDK 从 Info.plist 的 CFBundleDisplayName / CFBundleShortVersionString / CFBundleVersion / CFBundleIdentifier 自动读取，不需要传。

隐私合规（可选）

继承 QLCustomController 覆写对应方法，在 init 之前通过 [QLSdk setCustomController:] 设进去：

@interface MyPrivacy : QLCustomController @end
@implementation MyPrivacy
- (BOOL)isAllowSDKObtainIDFA      { return NO; }   // 关闭 IDFA 采集
- (BOOL)isAllowSDKObtainLocation  { return NO; }
- (NSDictionary<NSString *, NSNumber *> *)mediaLocation {
    return @{
        @"latitude": @(39.916527),    // 纬度
        @"longitude": @(116.397128),  // 经度
    };
}
- (NSInteger)personalizedState    { return 1; }    // 1 关闭个性化推荐
@end

[QLSdk setCustomController:[MyPrivacy new]];

mediaLocation 仅在 isAllowSDKObtainLocation 返回 NO 时读取，用于宿主自行提供经纬度。字典 key 约定如下：

key	含义	类型
`latitude`	纬度	`NSNumber`，double
`longitude`	经度	`NSNumber`，double

未提供定位时返回 nil 即可。

三、加载与展示广告

所有广告位都遵循同一套模式：

用 QLAdSlot.builder 链式配置广告位参数

通过 [QLSdk get] 拿到 id<QLAdNative>，调用对应 loadXxxAd:delegate:

在 Load delegate 的 success 回调里拿到广告对象

设置广告对象自己的 interactionDelegate / delegate，调用 showXxx 展示

广告位参数说明

QLAdSlot 不要求每种广告位把所有字段都传一遍。除 slotId 外，其余字段都有默认值，应按广告位类型选择性配置。

参数	开屏	Banner	插屏	激励视频	原生模板	说明
`slotId`	必填	必填	必填	必填	必填	媒体配置的广告位 ID
`expressViewAcceptedSize` / `adSize`	推荐	推荐	通常不传	通常不传	推荐	Banner / 原生模板尺寸；开屏可传容器尺寸。`setAdSize` 是原生模板更直观的别名
`countdownTime`	可选	不传	不传	不传	不传	开屏倒计时，限制为 3-15 秒
`countdownVisibility`	可选	不传	不传	不传	不传	是否显示开屏倒计时
`rewardName`	不传	不传	不传	建议	不传	激励奖励名称
`rewardAmount`	不传	不传	不传	建议	不传	激励奖励数量
`userId`	不传	不传	不传	按业务需要	不传	激励奖励关联用户标识
`mediaExtra`	不传	不传	不传	按业务需要	不传	激励奖励透传信息
`playMuted`	不传	不传	不传	可选	不传	激励视频初始是否静音，默认开启
`adCount`	不传	不传	不传	不传	可选	原生模板请求数量，默认 1
`imageAcceptedSize`	通常不传	通常不传	通常不传	通常不传	通常不传	未指定模板尺寸时的素材尺寸兜底
`basePrice`	按竞价需要	按竞价需要	按竞价需要	按竞价需要	按竞价需要	仅明确使用底价竞价时配置
`codeId`	不传	不传	不传	不传	不传	当前以 `slotId` 为主，不需同时传
`orientation`	默认竖屏	默认竖屏	默认竖屏	默认竖屏	默认竖屏	确需横屏请求时才修改
`autoPlay` / `selfRender` / `adLoadType` / `expressViewColor` / `expressViewPadding`	使用默认值	使用默认值	使用默认值	使用默认值	使用默认值	当前媒体接入通常不需要配置

最小配置建议：

开屏：slotId，可选 expressViewAcceptedSize、countdownTime。

Banner：slotId、expressViewAcceptedSize。

插屏：只传 slotId。

激励视频：slotId，建议补充 rewardName、rewardAmount，按业务需要补充 userId、mediaExtra。

原生模板：slotId、adSize，需要多条时再传 adCount。

接入方确认清单

请接入方按实际广告位逐项确认，未使用的参数不要传：

广告位	接入方必须确认	可选确认	不需要确认
开屏	`slotId` 是否正确	是否需要指定容器尺寸、倒计时秒数、是否显示倒计时	奖励参数、`adCount`
Banner	`slotId` 是否正确、Banner 宽高	是否需要轮播展示	奖励参数、倒计时参数
插屏	`slotId` 是否正确、展示控制器	是否需要自定义竞价底价	奖励参数、尺寸参数
激励视频	`slotId` 是否正确、奖励名称、奖励数量	用户标识、透传信息、默认静音状态	倒计时、Banner 尺寸、`adCount`
原生模板	`slotId` 是否正确、模板宽高	请求条数 `adCount`、模板内边距和颜色	奖励参数、开屏倒计时

接入方确认完成后，建议只提交每个广告位实际使用的字段，避免把其他广告位参数复制过来。

获取 eCPM

广告加载成功后，可通过广告对象读取本次广告价格：

- (void)onSplashAdLoadSuccess:(id<QLSplashAd>)ad {
    NSInteger ecpm = [ad getEcpm]; // 单位：分
    NSLog(@"eCPM=%ld 分", (long)ecpm);
}

QLSplashAd / QLBannerAd / QLInteractionAd / QLRewardVideoAd / QLNativeExpressAdView 均支持 getEcpm。getEcmp 是兼容别名，返回值一致。

开屏 Splash

QLAdSlot *slot = QLAdSlot.builder
    .setSlotId(@"8000188")
    .setExpressViewAcceptedSize(self.view.bounds.size.width, self.view.bounds.size.height)
    .setCountdownTime(5)        // 倒计时秒数，3-15
    .setCountdownVisibility(YES) // 是否显示倒计时
    .build;

[[QLSdk get] loadSplashAd:slot delegate:self];

// QLSplashAdLoadDelegate
- (void)onSplashAdLoadSuccess:(id<QLSplashAd>)ad {
    ad.interactionDelegate = self;
    [ad showAdInViewController:self container:self.splashContainer];
}
- (void)onSplashAdLoadError:(QLAdError *)error { /* ... */ }

横幅 Banner

QLAdSlot *slot = QLAdSlot.builder
    .setSlotId(@"8000191")
    .setExpressViewAcceptedSize(width, 80)
    .build;
[[QLSdk get] loadBannerExpressAd:slot delegate:self];

- (void)onBannerAdLoadSuccess:(id<QLBannerAd>)ad {
    ad.interactionDelegate = self;
    [self.container addSubview:ad.bannerView];
}

插屏 Interstitial

QLAdSlot *slot = QLAdSlot.builder.setSlotId(@"8000189").build;
[[QLSdk get] loadInteractionExpressAd:slot delegate:self];

- (void)onInteractionAdLoadSuccess:(id<QLInteractionAd>)ad {
    ad.delegate = self;
    [ad showInteractionAdFromViewController:self];
}

激励视频 Reward Video

QLAdSlot *slot = QLAdSlot.builder
    .setSlotId(@"8000262")
    .setRewardName(@"金币")
    .setRewardAmount(100)
    .setUserId(@"user_demo")
    .setPlayMuted(NO)             // 是否默认静音
    .build;
[[QLSdk get] loadRewardVideoAd:slot delegate:self];

- (void)onRewardVideoAdLoadSuccess:(id<QLRewardVideoAd>)ad {
    ad.delegate = self;
    [ad showRewardVideoAdFromViewController:self];
}

- (void)rewardVideoAd:(id<QLRewardVideoAd>)ad
        verifyReward:(BOOL)verified
               extra:(NSDictionary *)extra {
    if (verified) {
        // 看完了，下发奖励
    }
}

原生模板 Native Express

原生模板加载成功后返回的对象就是 QLNativeExpressAdView，它本身是 UIView，不再需要从广告对象里取 expressAdView。接入时先通过 setAdSize(width, height) 传入模板尺寸；SDK 会把这个尺寸设置为广告 View 的默认尺寸，并在 render 成功后通过 size 返回最终渲染尺寸。媒体侧仍负责把 View 添加到自己的容器中，并设置最终位置。

QLAdSlot *slot = QLAdSlot.builder
    .setSlotId(@"YOUR_NATIVE_SLOT_ID")
    .setAdCount(3)
    .setAdSize(width, 280)
    .build;
[[QLSdk get] loadNativeExpressAd:slot delegate:self];

- (void)onNativeExpressAdsLoadSuccess:(NSArray<QLNativeExpressAdView *> *)views {
    for (QLNativeExpressAdView *adView in views) {
        adView.delegate = self;
        [adView render];
    }
}
- (void)nativeExpressAdViewRenderSuccess:(QLNativeExpressAdView *)adView size:(CGSize)size {
    // 如果使用 AutoLayout，也可以将 adView 约束到你的 cell/container。
    adView.frame = CGRectMake(0, 0, size.width, size.height);
    [self.stack addArrangedSubview:adView];
}

四、回调全景

协议	关键回调
`QLSplashAdLoadDelegate`	`onSplashAdLoadSuccess:` / `onSplashAdLoadError:`
`QLSplashAdInteractionDelegate`	`splashAdRenderSuccess:` / `splashAdDidShow:` / `splashAdDidClick:` / `splashAdDidSkip:` / `splashAdCountdownDidFinish:` / `splashAdDidDismiss:closeType:`
`QLBannerAdInteractionDelegate`	`bannerAdDidShow:index:` / `bannerAdDidClick:index:`
`QLInteractionAdDelegate`	`interactionAdDidShow:` / `interactionAdDidClick:` / `interactionAdDidDismiss:`
`QLRewardVideoAdDelegate`	`rewardVideoAdDidShow:` / `rewardVideoAdVideoStart:` / `rewardVideoAdVideoComplete:` / `rewardVideoAd:verifyReward:extra:` / `rewardVideoAdDidClose:` / `rewardVideoAdRenderFailed:error:`
`QLNativeExpressAdViewDelegate`	`nativeExpressAdViewRenderSuccess:size:` / `nativeExpressAdViewDidShow:` / `nativeExpressAdViewDidClick:` / `nativeExpressAdViewDidDismiss:`

五、错误码

QLAdError.code 可能取的值（见 QLErrorCode.h）：

Code	含义	何时出现
`QLInitErrorIDSecretNotConfigured`	mediaId/secret 没传	init 阶段
`QLAdErrorCodeNotInitialized`	SDK 还没 init 完	load 阶段
`QLAdErrorCodeInvalidSlotId`	slot id 为空	load 阶段
`QLAdErrorCodeNetworkFailed`	bid 请求失败	load 阶段
`QLAdErrorCodeResponseParseFailed`	响应解密/JSON 解析失败	load 阶段
`QLAdErrorCodeNoFill`	后端没填充	load 阶段
`QLAdErrorCodeRenderFailed`	渲染失败	show 阶段
`QLAdErrorCodeMaterialLoadFailed`	素材下载/解码失败	show 阶段
`QLAdErrorCodeContainerInvalid`	容器 nil 或不在窗口上	show 阶段

一盟广告 iOS SDK接入文档

SDK 接入指南#

环境要求#

一、引入 SDK#

CocoaPods（推荐）#

XCFramework 手动接入#

必要的依赖#

Info.plist 配置#

二、初始化 SDK#

隐私合规（可选）#

三、加载与展示广告#

广告位参数说明#

接入方确认清单#

获取 eCPM#

开屏 Splash#

横幅 Banner#

插屏 Interstitial#

激励视频 Reward Video#

原生模板 Native Express#

四、回调全景#

五、错误码#