GroMore iOS 接入指南

本文档指导开发者在 iOS 端将优聚智汇 SDK 以**自定义广告网络（自定义 ADN）**形式接入穿山甲 GroMore 聚合平台（穿山甲融合 SDK / Ads-CN-Beta CSJMediation），由 GroMore 调度优聚广告参与瀑布流 / Client Bidding。

阅读前置

请先阅读自定义广告平台概述，了解反向集成模式与核心概念。本文仅介绍 iOS 端的依赖引入、平台配置与注意事项。

GroMore 自定义 ADN 官方接入规范：https://www.csjplatform.com/supportcenter/28709

版本号说明

组件	当前版本	说明
UjuRevGromoreAdapter	`~> 3.4.5`	优聚 GroMore 反向聚合适配器，版本号与 UjuAdCore 对齐
UjuAdCore	`~> 3.4.5`	优聚核心 SDK，由 UjuRevGromoreAdapter 强依赖
UjuAdExt	`~> 3.5.5`	优聚智汇预算扩展包，可选（推荐，扩展广告填充来源）
Ads-CN-Beta（CSJMediation）	`7.8.x`	穿山甲融合 SDK（含 GroMore 聚合能力），由 UjuRevGromoreAdapter podspec 自动依赖引入

开发环境要求

项目	要求
iOS 部署目标	iOS 15.0 及以上（优聚智汇组件 3.4.3 起统一为 15.0）
Swift 版本	Swift 5.9 及以上
Xcode 版本	Xcode 15 及以上（推荐 Xcode 26+）
架构	arm64（真机）/ arm64 + x86_64（模拟器）
依赖工具	Xcode / CocoaPods

SDK 组件关系

┌──────────────────────────────────────────────┐
│            集成方 App                        │
├──────────────────────────────────────────────┤
│  穿山甲融合 SDK（Ads-CN-Beta，自动依赖引入） │
│  └── GroMore 聚合                            │
│       ↓ 运行时通过反射发现适配器             │
│  UjuRevGromoreAdapter（必选）                │
│  └── UjuGromore*Adapter（@objc 暴露）        │
│       ↓ 编译期依赖                           │
│  UjuAdCore（必选）                           │
│  ├── 优聚 Adx 竞价引擎 / 埋点上报            │
│  └── 广告加载 / 渲染 / 展示                  │
│  UjuAdExt（可选，推荐）                      │
│  └── 内部 DSP 适配器（Vendor 已打包）        │
└──────────────────────────────────────────────┘

支持广告类型：开屏 / 插屏 / 插全屏（全屏视频）/ 激励视频 / 信息流（模板渲染）；支持 Client Bidding（ECPM 单位分）。

集成方式

方式一：CocoaPods 集成（推荐）

步骤 1：添加私有 spec repo

bash

pod repo add UjuAdSpecs https://gitee.com/ujuad/iossdk.git

步骤 2：创建 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.5'
  pod 'UjuRevGromoreAdapter', '~> 3.4.5'

  # 可选：预算扩展包（扩展广告填充来源）
  # pod 'UjuAdExt', '~> 3.5.5'
end

# Xcode 27+ 需要（穿山甲 pod 自带部署目标声明为 11.0，需统一抬到 15.0；
# 引入 UjuAdExt 时还需排除模拟器 arm64 架构）
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'
      c.build_settings['EXCLUDED_ARCHS[sdk=iphonesimulator*]'] = 'arm64'
    end
  end
end

穿山甲 SDK 自动引入

穿山甲融合 SDK（Ads-CN-Beta 7.8.x + CSJMediation，含 GroMore 聚合能力）由 UjuRevGromoreAdapter podspec 自动依赖引入，无需（也不应）手动声明。适配器以 Ads-CN-Beta 7.8.0.0 编译，~> 7.8.0 约束下 pod install 会解析到 7.8.x 最新补丁版。

UjuRevGromoreAdapter.podspec 的 user_target_xcconfig 已自动注入 -force_load（本适配器 + UjuAdCore 的静态库）、SWIFT_INCLUDE_PATHS、SWIFT_ENABLE_EXPLICIT_MODULES=NO 等必要配置，无需手动设置。

步骤 3：安装依赖并验证

bash

pod install
open YourApp.xcworkspace

swift

import UjuAdCore

print("UjuAdCore 版本: \(UjuAdCore.shared.getVersion())")
// 输出: UjuAdCore 版本: 3.4.5

方式二：XCFramework 手动集成

下载产物：

包名	下载地址
`UjuAdCore-3.4.5.xcframework.zip`	Gitee Release UjuAdCore-3.4.5
`UjuRevGromoreAdapter-3.4.5.xcframework.zip`	Gitee Release UjuRevGromoreAdapter-3.4.5
Ads-CN-Beta 7.8.0.0	手动集成时需自行引入（`pod 'Ads-CN-Beta', '7.8.0.0', :subspecs => ['CSJMediation']` 或从穿山甲官方下载）

将 UjuAdCore.xcframework、UjuRevGromoreAdapter.xcframework、穿山甲融合 SDK 各 xcframework 拖入项目 Frameworks/ 目录，Embed 选项均为 Do Not Embed（静态库）
在 iOS 准备工作 UjuAdCore 配置的基础上，追加以下 Build Settings：

text

// SWIFT_INCLUDE_PATHS 追加 UjuRevGromoreAdapter 的 Headers 目录
SWIFT_INCLUDE_PATHS[sdk=iphoneos*] = $(inherited) \
  $(SRCROOT)/Frameworks/UjuAdCore.xcframework/ios-arm64/Headers \
  $(SRCROOT)/Frameworks/UjuRevGromoreAdapter.xcframework/ios-arm64/Headers
SWIFT_INCLUDE_PATHS[sdk=iphonesimulator*] = $(inherited) \
  $(SRCROOT)/Frameworks/UjuAdCore.xcframework/ios-arm64_x86_64-simulator/Headers \
  $(SRCROOT)/Frameworks/UjuRevGromoreAdapter.xcframework/ios-arm64_x86_64-simulator/Headers

// OTHER_LDFLAGS 追加 UjuRevGromoreAdapter 的 -force_load 与 -ObjC
OTHER_LDFLAGS[sdk=iphoneos*] = $(inherited) \
  -force_load $(SRCROOT)/Frameworks/UjuAdCore.xcframework/ios-arm64/libUjuAdCore-iphoneos.a \
  -force_load $(SRCROOT)/Frameworks/UjuRevGromoreAdapter.xcframework/ios-arm64/libUjuRevGromoreAdapter-iphoneos.a \
  -ObjC
OTHER_LDFLAGS[sdk=iphonesimulator*] = $(inherited) \
  -force_load $(SRCROOT)/Frameworks/UjuAdCore.xcframework/ios-arm64_x86_64-simulator/libUjuAdCore-simulator.a \
  -force_load $(SRCROOT)/Frameworks/UjuRevGromoreAdapter.xcframework/ios-arm64_x86_64-simulator/libUjuRevGromoreAdapter-simulator.a \
  -ObjC

为什么需要 -force_load 和 -ObjC？

GroMore 通过 NSClassFromString 反射实例化 UjuGromore*Adapter 类，默认链接模式下这些 OC 类符号会被 dead-strip，必须 -force_load 本静态库；穿山甲 SDK 与适配器均含 OC Category，需 -ObjC 正确加载。CocoaPods 集成时由 podspec 自动配置。

GroMore 平台配置

1. 新建自定义广告网络（穿山甲媒体平台 → GroMore → 广告网络 → + 自定义广告网络）

配置项	填写值
初始化 Adapter 类全路径	`UjuGromoreConfigAdapter`
开屏 Adapter 类全路径	`UjuGromoreSplashAdapter`
激励视频 Adapter 类全路径	`UjuGromoreRewardAdapter`
插屏 Adapter 类全路径	`UjuGromoreInterstitialAdapter`
全屏视频 Adapter 类全路径（插全屏）	`UjuGromoreFullscreenVideoAdapter`
信息流 Adapter 类全路径	`UjuGromoreNativeAdapter`

2. 应用管理 → 为应用添加自定义 ADN

字段	填写值
App ID	优聚智汇后台分配的 `appId`
App Key	优聚智汇后台分配的 `appKey`（RSA 公钥 Base64）

兼容写法：App ID 或 App Key 任一字段可直接填写 JSON {"appId":"...","appKey":"...","channel":"gromore"}（字段长度受限或需自定义渠道标识时使用）。

3. 瀑布流管理 → 为广告位添加自定义 ADN 代码位

字段	填写值
代码位 ID	优聚智汇后台分配的 `placementId`（直接映射）
竞价类型	普通 / Client Bidding 均支持（Client Bidding 时适配器回传 ECPM，单位分）
渲染类型（信息流）	模板渲染（优聚信息流由 SDK 内部模板渲染）
自定义 Adapter 扩展参数（可选，JSON）	`{"placementId":"覆盖值","bidFloor":1.5,"adSourceId":0}` — `bidFloor` 为底价（元，CPM）；`adSourceId` 指定参与的预算源（0 全部参与 / 100 仅优聚 Adx / 1 仅穿山甲 ADN）

SDK 初始化

无需在宿主代码中显式初始化优聚 SDK：GroMore 初始化时会实例化 UjuGromoreConfigAdapter，适配器内部自动完成 UjuAdCore 的 initialize + start 流程。若宿主已自行初始化成功，适配器会直接复用，不会重复 start。

可选的宿主侧开关（需在 GroMore 初始化前设置）：

swift

import UjuRevGromoreAdapter

UjuGromoreConfigAdapter.debugLoggingEnabled = false     // 默认 true，联调排查用
UjuGromoreConfigAdapter.crashReportingEnabled = false   // 宿主已有崩溃捕获时建议关闭
UjuGromoreConfigAdapter.channelOverride = "gromore_xx"  // 覆盖渠道标识，默认 "gromore"

隐私与个性化映射

GroMore 在初始化前回调隐私配置更新，适配器自动映射为优聚初始化配置：

GroMore 隐私 key	优聚配置
`ABUPrivacyLimitPersonalAds`	个性化推荐开关（取反）
`ABUPrivacyLimitProgrammaticAds`	程序化推荐开关（取反）
`ABUPrivacyForbiddenIDFA` / `bum_forbidden_idfv`	是否允许使用 IDFA / IDFV（取反）
`ABUPrivacyCanLocation`	是否允许使用位置信息；为 false 且携带经纬度时透传给优聚 SDK

插屏与插全屏说明

穿山甲融合 SDK 已将传统插屏与全屏视频（插全屏）分为两种代码位：传统插屏代码位对应 UjuGromoreInterstitialAdapter，插全屏代码位对应 UjuGromoreFullscreenVideoAdapter（融合 SDK 主流插屏类型），两者底层均为优聚插屏广告，请按平台创建的代码位类型选择填写对应类名。

常见问题

现象	排查
GroMore 日志提示自定义 ADN 类不存在	平台配置的类全路径是否为 `UjuGromore*Adapter`；集成方 target 是否 `-force_load` 本静态库（CocoaPods 自动注入）
加载失败提示 SDK 未初始化	平台未配置初始化 Adapter 类全路径，或 App ID / App Key 为空 / 配置错误；可开启 `debugLoggingEnabled` 查看初始化失败原因
Client Bidding 出价为 0	优聚广告 ecpm 为 0 时不回传 ECPM，检查广告位底价与竞价结果
信息流高度异常	平台代码位渲染类型需为模板渲染；请求高度为 0 时由模板内容自适应
部署目标报错（set to 11.0）	Podfile 需按本文 `post_install` 钩子统一抬升 Pods 部署目标到 15.0

广告类型

广告类型

第三方广告平台

GroMore iOS 接入指南

版本号说明

开发环境要求

SDK 组件关系

集成方式

方式一：CocoaPods 集成（推荐）

步骤 1：添加私有 spec repo

步骤 2：创建 Podfile

步骤 3：安装依赖并验证

方式二：XCFramework 手动集成

GroMore 平台配置

1. 新建自定义广告网络（穿山甲媒体平台 → GroMore → 广告网络 → + 自定义广告网络）

2. 应用管理 → 为应用添加自定义 ADN

3. 瀑布流管理 → 为广告位添加自定义 ADN 代码位

SDK 初始化

隐私与个性化映射

插屏与插全屏说明

常见问题

相关链接

GroMore iOS 接入指南 ​

版本号说明 ​

开发环境要求 ​

SDK 组件关系 ​

集成方式 ​

方式一：CocoaPods 集成（推荐） ​

步骤 1：添加私有 spec repo ​

步骤 2：创建 Podfile ​

步骤 3：安装依赖并验证 ​

方式二：XCFramework 手动集成 ​

GroMore 平台配置 ​

1. 新建自定义广告网络（穿山甲媒体平台 → GroMore → 广告网络 → + 自定义广告网络） ​

2. 应用管理 → 为应用添加自定义 ADN ​

3. 瀑布流管理 → 为广告位添加自定义 ADN 代码位 ​

SDK 初始化 ​

隐私与个性化映射 ​

插屏与插全屏说明 ​

常见问题 ​

相关链接 ​

GroMore iOS 接入指南

版本号说明

开发环境要求

SDK 组件关系

集成方式

方式一：CocoaPods 集成（推荐）

步骤 1：添加私有 spec repo

步骤 2：创建 Podfile

步骤 3：安装依赖并验证

方式二：XCFramework 手动集成

GroMore 平台配置

1. 新建自定义广告网络（穿山甲媒体平台 → GroMore → 广告网络 → + 自定义广告网络）

2. 应用管理 → 为应用添加自定义 ADN

3. 瀑布流管理 → 为广告位添加自定义 ADN 代码位

SDK 初始化

隐私与个性化映射

插屏与插全屏说明

常见问题

相关链接