优聚智汇

简体中文

English

简体中文

English

外观

穿山甲(iOS) ​

本文档介绍 iOS 端接入穿山甲(CSJ)广告平台的对接事项:引入适配器、工程配置、平台参数与注意事项。

概述 ​

项目说明
适配器UjuCsjAdapter ~> 1.0.0（platformId=1）
穿山甲 SDKAds-CN-Beta 7.8.x（subspec: CSJMediation），由 UjuCsjAdapter podspec 自动依赖引入
依赖UjuAdCore ~> 3.4.3（3.4.3 起部署目标统一 iOS 15.0）
支持广告类型开屏、激励视频、插屏、横幅、原生(模板渲染)

适配器遵循穿山甲官方接入规范对接,展示、点击等监测数据由穿山甲 SDK 自动上报,无需开发者额外处理。

一、前置条件 ​

  1. 已按 iOS 初始化文档 完成优聚智汇 SDK 初始化。
  2. 在穿山甲平台注册并创建媒体与应用,获取穿山甲 App ID 与代码位 ID。
  3. 在优聚智汇开发者平台「广告平台配置」中开通穿山甲,填写穿山甲 App ID;在广告位瀑布流中配置穿山甲广告源(代码位 ID)。

二、引入适配器 ​

1. Podfile ​

ruby
source 'https://gitee.com/ujuad/iossdk.git'
source 'https://cdn.cocoapods.org/'

platform :ios, '15.0'

target 'YourApp' do
  pod 'UjuAdCore', '~> 3.4.8'
  # 穿山甲融合 SDK(Ads-CN-Beta 7.8.x)由 UjuCsjAdapter podspec 自动依赖引入,无需手动声明
  pod 'UjuCsjAdapter', '~> 1.0.0'
end

# Xcode 27+ 需要(穿山甲 pod 自带部署目标声明为 11.0,需统一抬到 15.0)
post_install do |installer|
  installer.pods_project.targets.each do |t|
    t.build_configurations.each do |c|
      c.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '15.0'
    end
  end
end

适配器以 Ads-CN-Beta 7.8.0.0 编译,~> 7.8.0 约束下 pod install 会解析到 7.8.x 最新补丁版。CSJAdSDK.bundle 等资源由该 pod 自动携带,-force_load / SWIFT_INCLUDE_PATHS 由 UjuCsjAdapter podspec 自动注入,无需手动配置。

2. Info.plist 适配器注册 ​

xml
<key>uju_adapter_csj</key>
<string>UjuCsjAdapter.CsjAdapterFactory</string>

SDK 初始化时自动扫描 uju_adapter_* 前缀 key 并反射注册适配器,无需调用任何额外代码。穿山甲 SDK 的初始化也由优聚智汇 SDK 在策略下发后自动完成(使用后台配置的穿山甲 App ID)。

三、工程配置(穿山甲 SDK 要求) ​

1. ATS 例外 ​

部分广告素材为 HTTP,需允许任意加载:

xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
</dict>

2. ATT 授权(iOS 14.5+) ​

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

建议在初始化前调用 ATTrackingManager.requestTrackingAuthorization 请求授权;用户拒绝授权时 IDFA 清零,可能降低广告收益。

3. SKAdNetwork ​

在 Info.plist 的 SKAdNetworkItems 中添加穿山甲 SKAdNetwork ID:

xml
<key>SKAdNetworkItems</key>
<array>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>238da6jt44.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>x2jnk7ly8j.skadnetwork</string>
    </dict>
    <dict>
        <key>SKAdNetworkIdentifier</key>
        <string>22mmun2rn5.skadnetwork</string>
    </dict>
</array>

4. Other Linker Flags ​

Build Settings → Other Linker Flags 添加 -ObjC。pod 'UjuCsjAdapter' 的 user_target_xcconfig 已自动配置 -force_load / SWIFT_INCLUDE_PATHS 等必要参数,无需手动处理。

四、验证 ​

真机运行后,在控制台过滤以下日志确认链路:

环节日志关键字
适配器注册反射注册 UjuCsjAdapter.CsjAdapterFactory 成功(platformId=1)
穿山甲初始化穿山甲 SDK 初始化成功
广告加载CsjSplash onLoadAd / splashAdLoadSuccess
竞价胜出竞价胜出(ADN): platformId=1
展示splashAdDidShow 等展示回调

穿山甲平台的展示、点击报表一般在广告实际展示后几分钟内可见(偶有小时级延迟)。请注意:仅完成"加载"未调用展示的请求,平台不计展示量。

五、注意事项(对接穿山甲官方文档要点) ​

  1. rootViewController 必须有效:穿山甲所有跳转均采用 present 方式,展示广告时优聚智汇 SDK 会传入当前页面控制器,请确保从可见的 UIViewController 发起 show,且该控制器未 present 其他控制器,否则会出现 presentedViewController already exists 导致跳转失败。
  2. 广告代理不可中途更改:穿山甲开屏文档明确"不支持中途更改代理,中途更改代理会导致接收不到广告相关回调"。适配器内部在加载阶段完成 delegate 绑定,业务方无需也不应持有并修改穿山甲广告对象的代理。
  3. 信息流必须设置 rootViewController:模板信息流广告视图必须关联有效控制器,否则点击跳转失败、dislike 回调不进(适配器内部已处理)。
  4. 同一广告对象只计一次有效展示:重复展示会被穿山甲系统过滤。请勿缓存已展示的 UjuAdObject 重复调用 show,需要再次展示时重新 load。
  5. 激励视频服务器回调:如需服务端奖励验证,请在穿山甲平台填写奖励回调 URL,并确认用户 ID(userId)为非空字符串。
  6. 横幅展示需要容器:横幅广告渲染到 show(_:container:) 传入的容器视图,请确保容器已布局(非零尺寸)后再展示。

六、常见问题 ​

Q1:初始化报错 Invalid SDK Framework(错误码 98765),提示替换 CSJAdSDK.bundle? ​

宿主 App 内的 CSJAdSDK.bundle 与 BUAdSDK 版本不一致或 bundle 缺失。手动集成时请确认 CSJAdSDK.bundle 已加入 Copy Bundle Resources,且与引入的 Ads-CN-Beta 版本一致;使用 CocoaPods 引入 Ads-CN-Beta 则自动匹配。

Q2:穿山甲平台没有展示、点击数据? ​

  1. 确认已完整执行 加载 → 展示 流程(仅加载不计展示);
  2. 确认展示回调已触发(见「四、验证」日志);
  3. 检查 rootViewController 是否有效(点击跳转失败会导致点击数据缺失);
  4. 平台报表存在延迟,可在几分钟至一小时后复查。

Q3:加载返回 noFill / 无填充? ​

穿山甲测试代码位有 QPS 与频控限制;请确认代码位状态开启、包名与穿山甲平台配置一致,并参考穿山甲错误码文档排查。