更新记录

2.0.0（2026-06-04）

• 新增 UTS API 插件版本，插件 ID 为 JQ-RangersAppLog-UTS。
• iOS 接入 BDASignalSDK 2.0.0，支持初始化、IDFA 开关、DeepLink clickid、关键事件、延迟上报、IAP 监听。
• Android 接入 AppConvert 2.0.4，支持初始化、注册事件、付费事件和自定义事件上报。
• 提供老版 JQ-RangersAppLog 常用接口兼容层，并补充 Android/iOS 示例工程和隐私说明。

平台兼容性

uni-app(5.07)

uni-app x(5.07)

巨量融合归因SDK UTS版

JQ-RangersAppLog-UTS 是全新的 uni_modules / UTS API 插件，用于接入巨量营销融合归因优化方案（非游）V2.0。

本插件已按《巨量营销融合归因优化方案接入手册（非游）V2.0》完成 Android / iOS 双端 UTS 对接，并已完成云打包、iOS 真机、Android 真机流程验证；初始化、DeepLink / clickid、注册事件、付费事件、关键事件、老接口兼容调用均已在示例工程中提供。

担心无法使用的同学请先试用，确认自定义基座 / 云打包 / 真机功能正常后再购买。巨量引擎转化 SDK 版本可能随官方文档随时更新，购买和上线前请以本插件当前版本、试用结果、巨量官方文档和巨量后台检测结果为准。

插件介绍

1. 本插件封装巨量引擎转化融合归因 Android / iOS SDK，适合 uni-app / uni-app x 项目通过 UTS 接入巨量广告归因、转化上报、注册上报、付费上报、关键事件上报。
2. iOS 基于 BDASignalSDK 2.0.0，最低 iOS 15.0，支持隐私同意后初始化、IDFA 开关、DeepLink clickid 解析、启动参数缓存、关键事件上报。
3. Android 基于 com.bytedance.ads:AppConvert:2.0.4，最低 Android API 21，支持 BDConvert 初始化、注册事件、付费事件、自定义事件上报和 BDBridgeActivity 归因跳转配置。
4. 老版原生插件用户可以继续使用 configAppUid、configApp、setupAppLog、registerEvent、purchaseEvent 常用接口；新项目建议直接使用 initBDASDK、trackRegister、trackPurchase、trackEssentialEvent 等 UTS API。
5. 普通授权价格 198.00 元，不开放源码授权。

巨量官方文档地址：

• 巨量营销融合归因优化方案接入手册（非游）V2.0：https://bytedance.larkoffice.com/docx/CgYBdVzoBogND2xv7PhcSfFNnyc
• 巨量广告移动应用 SDK 文档：https://open.oceanengine.com/labels/7/docs/1696710651039744

已验证

• iOS：HBuilderX 5.07 云打包后，iPhone 真机验证初始化、原生状态、DeepLink clickid、注册事件、付费事件、老接口兼容调用均可正常执行。
• Android：HBuilderX 5.07 云打包 APK 后，Android 真机验证初始化、注册事件、付费事件、老接口兼容调用均可正常执行。
• Android 已按 AppConvert 2.0.4 AAR 公开 API 对接 BDConvert 初始化、ConvertReportHelper 注册/付费/自定义事件。
• iOS 已将 SDK 调用切到主线程，避免 BDASignalSDK 内部初始化 WKWebView 时因后台线程触发闪退。
• Android AppConvert 2.0.4 未公开 optionalData/user_unique_id 注入和 clickid getter 等等价接口，插件会返回 warning 提醒；这不影响初始化和注册/付费/自定义事件上报，最终转化归因仍需按巨量融合归因方案完成服务端 API 回传并以巨量后台检测为准。

安装

1. 将插件导入到项目的 uni_modules/JQ-RangersAppLog-UTS。
2. App 端需要重新生成自定义基座或云打包，不能只使用 HBuilderX 默认标准基座。
3. 请在用户同意隐私政策后再调用 initBDASDK。

iOS 原生配置：

{
  "deploymentTarget": "15.0",
  "validArchitectures": ["arm64"],
  "dependencies-pods": [
    {
      "name": "BDASignalSDK",
      "version": "2.0.0"
    }
  ]
}

Android 原生配置：

{
  "minSdkVersion": 21,
  "dependencies": ["com.bytedance.ads:AppConvert:2.0.4"],
  "project": {
    "repositories": [
      "maven { url 'https://artifact.bytedance.com/repository/Volcengine/' }"
    ]
  }
}

快速开始

import {
  initBDASDK,
  getDebugStatus,
  getClickId,
  handleOpenURL,
  trackRegister,
  trackPurchase,
  trackEssentialEvent
} from '@/uni_modules/JQ-RangersAppLog-UTS'

// 用户同意隐私政策后调用
const initResult = initBDASDK({
  enableIdfa: false, // 仅 iOS 生效
  enableLog: true,   // Android AppConvert 调试日志
  optionalData: {
    user_unique_id: 'user_10001' // iOS 生效；Android AppConvert 未公开该注入接口
  },
  enableIPFetch: true
})

console.log(initResult)
console.log(getDebugStatus())

// iOS 支持解析并读取 clickid
handleOpenURL('yourapp://open?clickid=xxx')
console.log('clickid', getClickId())

trackRegister({
  registerType: 'mobile',
  success: true
})

trackPurchase({
  goodsType: 'digital',
  goodsName: 'vip',
  goodsId: 'A1001',
  goodsNum: 1,
  payChannel: '***',
  currency: 'CNY',
  success: true,
  amount: 68
})

trackEssentialEvent('add_to_cart', {
  source: 'demo'
})

隐私与合规

• 插件不展示广告，也不会主动弹出权限申请。
• iOS BDASignalSDK 可能采集 IDFV、设备信息、系统信息、网络信息、应用信息、DeepLink clickid、调用方传入的 user_unique_id / extra 参数。
• Android AppConvert 可能采集 Android ID、OAID、设备信息、系统信息、网络信息、应用信息、广告点击/转化归因信息、调用方主动传入的事件参数。
• Android SDK 自带 INTERNET、ACCESS_NETWORK_STATE、CHANGE_NETWORK_STATE 等网络相关声明，并包含用于归因跳转的 BDBridgeActivity。
• iOS IDFA 默认不采集。若业务需要 IDFA，请先在应用中配置 NSUserTrackingUsageDescription，完成 ATT 合规授权后再调用 enableIdfa(true) 或 initBDASDK({ enableIdfa: true })。
• 建议在用户同意隐私政策后再调用 initBDASDK。
• 融合归因方案中的注册、付费等转化效果通常还需要按巨量引擎后台要求完成服务端 API 回传，最终归因结果以巨量引擎后台和官方文档为准。

API

initBDASDK(options?)

初始化 SDK。建议在隐私同意后调用。

initBDASDK({
  enableIdfa: false,
  optionalData: {
    user_unique_id: 'user_10001'
  },
  enableLog: true,
  enableOAID: true,
  autoSendLaunchEvent: true,
  playSessionEnable: true
})

options 字段：

enableIdfa(enable)

iOS 设置 SDK 是否允许采集 IDFA。Android 调用会返回 warning，不会做实际操作。

registerOptionalData(data)

iOS 向 BDASignalSDK 注入可选参数。Android AppConvert 未公开等价接口，调用会返回 warning。

getClickId()

iOS 获取 SDK 缓存的 clickid。Android AppConvert 2.0.4 未公开 clickid getter，返回空字符串。

handleOpenURL(url)

iOS 解析 URL Scheme 或 Universal Link 中的 clickid。Android 归因点击由 AppConvert 内部和 BDBridgeActivity 处理，未公开手动解析接口。

trackRegister(params?)

注册事件。

Android 会映射到：

ConvertReportHelper.onEventRegister(registerType, success)

插件实际调用 AppConvert 2.0.4 的 extra 参数重载，会把传入的 params 同时作为 JSONObject 透传给 SDK。

常用参数：

trackPurchase(params?)

付费事件。

Android 会映射到：

ConvertReportHelper.onEventPurchase(goodsType, goodsName, goodsId, goodsNum, payChannel, currency, success, amount, ttOpenId, extra)

插件会把传入的 params 同时作为 JSONObject 透传给 SDK。

常用参数：

trackEssentialEvent(eventName, params?)

iOS 调用 BDASignalSDK 关键事件接口；Android 调用 ConvertReportHelper.onEventV3(eventName, JSONObject)。

常用快捷方法：

trackRegister({ registerType: 'mobile', success: true })
trackPurchase({ goodsName: 'vip', amount: 68 })
trackStayTime({ seconds: 30 })
trackGameAddiction({ value: 1 })

常用事件名：

enableDelayUpload() / startSendingEvents()

iOS 生效。Android AppConvert 未公开延迟上报接口，调用会返回 warning。

enablePurchaseEvent()

iOS IAP 监听生效。Android 请在业务付费成功后主动调用 trackPurchase。

老接口兼容

import {
  configAppUid,
  configApp,
  setupAppLog,
  registerEvent,
  purchaseEvent
} from '@/uni_modules/JQ-RangersAppLog-UTS'

configAppUid('user_10001')
configApp({ uid: 'user_10001', showDebugLog: true })

setupAppLog({
  uid: 'user_10001',
  showDebugLog: true
}, (res) => {
  console.log(res)
})

registerEvent({ registerType: 'mobile', success: true })
purchaseEvent({ goodsName: 'vip', amount: 68 })

注意：setupAppLog 中老 RangersAppLog 独有配置项会被忽略，并返回 warning。融合归因接入以各平台 SDK 公开能力为准。

对接核对

常见问题

为什么真机运行提示插件不存在或 undefined class？

UTS 原生插件必须重新打自定义基座或云打包。HBuilderX 默认标准基座不包含你的 UTS 原生模块。

Android 为什么读取不到 clickid？

AppConvert 2.0.4 AAR 的公开 API 没有 getClickId 或 handleOpenURL 方法。Android 点击归因由 SDK 内部和 BDBridgeActivity 处理，客户端无需也不能通过公开 API 读取 clickid；注册、付费等转化仍建议按巨量后台要求做服务端 API 回传。

初始化返回 nativeOk: true 是否代表 SDK 已接入？

代表 UTS 已经调用到对应平台原生 SDK。最终数据是否在巨量后台展示，还取决于网络、广告计划、转化配置、服务端回传和巨量后台处理。

发布信息

• 插件 ID：JQ-RangersAppLog-UTS
• 插件名称：巨量融合归因SDK UTS版
• 版本：2.0.0
• 分类：UTS插件 / API插件
• 价格：普通授权 198.00 元，不开放源码授权
• 关键词：巨量、融合归因、BDASignalSDK、AppConvert、Android、iOS、UTS