更新记录

2.3.1（2026-06-02） 下载此版本

提交

平台兼容性

uni-app x(5.06)

ad-ibx-sdk

爱变现 Android SDK 的 uni-app x UTS 封装模块。

当前版本基于 ibx_sdk_release_v2.3.1.aar 与 ibx_device_release_v2.3.1.aar 进行封装，提供一个统一的 start(options) 启动入口，用于从 uni-app x 页面内拉起爱变现业务。

适用范围

• uni-app x
• Android
• 需要自定义基座或自定义打包环境

目录说明

• utssdk/interface.uts：模块对外暴露的类型定义
• utssdk/app-android/index.uts：Android 平台启动实现
• utssdk/app-android/config.json：原生依赖与 Maven 仓库配置
• utssdk/app-android/libs/：本地 AAR 文件

对外接口

模块对外暴露一个 start(options) 方法。

IBXStartOptions

type IBXStartOptions = {
  appKey : string
  secret : string
  targetId : string
  deviceId : string
  oaidCertName : string
  oaidLibName : string
  oaidHelperVersion : number
  debug : boolean
}

start(options)

• 入参：IBXStartOptions
• 返回值：boolean
• 返回 true：已完成反射调用并发起 SDK 启动
• 返回 false：启动失败，通常是上下文缺失、AAR 未生效或自定义基座未包含原生依赖

实现说明

当前封装采用反射方式调用 com.aiyingli.ibxmodule.IBXSdk，内部流程如下：

1. 获取当前 Activity
2. 获取 IBXSdk 单例
3. 设置 debug / 日志开关
4. 调用 initApplication
5. 调用 setHighCostState(false)
6. 优先使用外部传入的 deviceId
7. 仅调用 5 参数 init(application, appKey, targetId, deviceId, secret)
8. 调用 start(activity) 拉起爱变现页面

之所以只保留 5 参数 init，是为了优先使用业务侧已经拿到的设备标识，避免再次触发 SDK 内部 OAID 依赖链，减少 OAIDHelper、证书文件或厂商实现差异带来的启动失败问题。

依赖说明

utssdk/app-android/config.json 中已声明以下依赖：

• com.arialyy.aria:core:3.8.10
• com.arialyy.aria:compiler:3.8.10
• com.github.donkingliang:imageselector:2.2.1
• com.github.bumptech.glide:glide:4.9.0

同时配置了以下仓库：

• mavenCentral()
• maven { url 'https://jitpack.io' }

使用前准备

1. 使用自定义基座

本模块包含本地 AAR 和三方 Maven 依赖，标准基座下不能保证原生能力正常生效。

如果运行日志里看到以下提示，属于正常现象：

uni_module [ad-ibx-sdk] (Android) 存在三方依赖或资源引用

这时需要：

• 在 HBuilderX 里配置自定义基座运行环境
• 或提交云端打自定义基座 / 自定义包

2. 提前获取设备标识

建议在业务侧先获取可用设备标识，再传给 start(options)。

推荐优先级：

1. OAID
2. Android ID
3. 业务本地设备 ID

3. 准备爱变现后台参数

你需要从爱变现平台获取：

• appKey
• secret
• targetId

其中：

• targetId 一般建议传业务用户 ID
• 如果当前用户未登录，也可以按业务规则传设备维度标识

基本用法

直接调用模块

// #ifdef APP-ANDROID
import { start } from '@/uni_modules/ad-ibx-sdk'
import type { IBXStartOptions } from '@/uni_modules/ad-ibx-sdk/utssdk/interface.uts'
// #endif

function openIbx() : boolean {
  // #ifdef APP-ANDROID
  const options : IBXStartOptions = {
    appKey: '你的appKey',
    secret: '你的secret',
    targetId: '你的用户ID',
    deviceId: '优先传oaid，没有则传androidId',
    oaidCertName: '',
    oaidLibName: '',
    oaidHelperVersion: 0,
    debug: true
  }
  return start(options)
  // #endif

  return false
}

推荐封装一层业务启动器

建议在 common 目录单独封装一个启动器，把平台参数、设备标识与异常处理放在一处管理。

示例：

// #ifdef APP-ANDROID
import { start as startIBXSdk } from '@/uni_modules/ad-ibx-sdk'
import type { IBXStartOptions } from '@/uni_modules/ad-ibx-sdk/utssdk/interface.uts'
// #endif

export function openIBXSdk(targetId : string, deviceId : string, debug : boolean) : boolean {
  // #ifdef APP-ANDROID
  const options : IBXStartOptions = {
    appKey: '你的appKey',
    secret: '你的secret',
    targetId: targetId,
    deviceId: deviceId,
    oaidCertName: '',
    oaidLibName: '',
    oaidHelperVersion: 0,
    debug: debug
  }
  return startIBXSdk(options)
  // #endif

  return false
}

页面调用示例

function openIbxSdk() : void {
  const targetId = getUid()
  const deviceId = getDeviceId()
  const opened = openIBXSdk(targetId, deviceId, true)
  if (!opened) {
    uni.showToast({ title: '请重新安装最新自定义基座', icon: 'none' })
  }
}

常见问题

1. 启动时报找不到类

例如：

NoClassDefFoundError: com.donkingliang.imageselector.utils.ImageSelector

通常表示自定义基座没有正确集成 Maven 依赖，或者运行环境还在使用旧基座。请确认：

• 已使用自定义基座运行
• 自定义基座已重新构建
• config.json 中依赖与仓库配置已经生效

2. 启动时报 AAR 未生效

例如日志中出现：

[ibx] 启动失败，请确认自定义基座已包含 AAR

请检查：

• utssdk/app-android/libs/ 下 AAR 是否存在
• 当前运行的是否是最新自定义基座
• 运行配置是否指向了正确项目

3. 没有 OAID 是否可以启动

可以。

当前实现优先使用外部传入的 deviceId，如果业务侧没有 OAID，可以降级传 Android ID 或你自己的设备标识。

4. 为什么 oaidCertName、oaidLibName、oaidHelperVersion 目前没有实际参与启动

当前版本为了避免内部 OAID 初始化链路导致额外崩溃，已经固定走外部设备标识模式。保留这些字段主要是为了兼容爱变现原始参数结构，方便后续扩展。

调试建议

• 启动前打印 targetId、deviceId
• 优先确认设备标识不是空字符串
• 每次修改 config.json 或 AAR 后，重新制作并安装自定义基座
• 若运行失败，优先查看 Android 控制台里的 Java 异常堆栈

更新记录

1.0.1

• 补充模块接入说明
• 补充 Android 依赖与运行环境说明

1.0.0

• 初始版本