更新记录

1.0.1（2026-08-27） 下载此版本

首个版本。以 UTS 插件形态封装友盟+ 统计分析 UMCommon 原生 SDK，支持 uni-app 的 App-vue / App-nvue（iOS + Android）。

• 提供 25 个 API：预初始化 / 合规初始化、自定义事件、页面时长、账号统计、用户属性、预置属性等
• 初始化拆分为 preInitUM（不采集、不联网）与 initUM（正式采集），配合 submitPolicyGrantResult 满足隐私合规的两阶段要求
• Android 原生 SDK 走 Maven 在线依赖（common:9.9.8 + asms:1.8.3），iOS 内嵌 UMCommon.xcframework 7.6.6，两端均无需自行下载友盟 SDK
• 随插件提供苹果隐私清单 PrivacyInfo.xcprivacy

平台兼容性

uni-app(3.97)

友盟统计分析 UMCommon（UTS 插件）

基于友盟+ 统计分析原生 SDK 封装的 UTS 插件，为 uni-app 工程提供事件统计、页面时长、账号统计、用户属性、预置属性等能力。

Android 侧走 Maven 在线依赖，接入方可自主升级 SDK 版本、插件包内也不必内置二进制；iOS 侧内嵌 UMCommon.xcframework。两端都无需你自行下载友盟 SDK。

快速接入

第一步，在 HBuilderX 中从插件市场导入本插件，或把 uni_modules/umeng-common 整个目录拷贝到你的 uni-app 工程根目录下的 uni_modules/ 中。

第二步，在 App.vue 中做合规初始化：

import {
  preInitUM, initUM, submitPolicyGrantResult,
  setLogEnabled, setPageCollectionMode
} from '@/uni_modules/umeng-common'

export default {
  onLaunch() {
    // 1) 预初始化：必须在最早时机调用，此阶段不采集不上报
    preInitUM({ appKey: '你的AppKey', channel: 'App Store' })

    // 2) 只有用户已同意隐私政策，才真正初始化
    if (uni.getStorageSync('privacyAgreed') === true) {
      this.startUMCommon()
    }
  },
  methods: {
    // 用户在隐私弹窗点「同意」后调用此方法
    startUMCommon() {
      submitPolicyGrantResult(true)   // Android 生效，iOS 空实现
      setLogEnabled(false)            // 生产环境关闭日志
      initUM({ appKey: '你的AppKey', channel: 'App Store' })
      setPageCollectionMode('MANUAL') // init 之后设置页面采集模式
    }
  }
}

注意导出的方法名带 UM 后缀——是 preInitUM / initUM，而不是 preInit / init。

第三步，业务侧埋点：

import { onEventObject, onPageStart, onPageEnd } from '@/uni_modules/umeng-common'

onEventObject('checkout', { amount: 99.5, sku: 'A123', vip: true })
onPageStart('pages/order/detail')
onPageEnd('pages/order/detail')

第四步，制作自定义调试基座真机验证。插件依赖的原生 SDK（iOS 内嵌 xcframework、Android 走 Maven 在线依赖）在 HBuilderX 标准基座里都没有，直接用标准基座运行会报找不到方法，需在 HBuilderX 中「运行 → 制作自定义调试基座」后再真机运行。

合规要求（必读）

preInitUM 与 initUM 必须分离，这不是可选项。

preInitUM 在 App 启动最早时机调用，此阶段 SDK 不采集任何设备标识、不发起任何网络请求。initUM 必须等到用户明确同意隐私政策之后才调用。如果直接在启动时调 initUM，会在用户同意前采集设备标识，iOS 侧存在被苹果拒审的风险，Android 侧无法通过工信部合规扫描。

Android 侧额外需要在用户同意后调用一次 submitPolicyGrantResult(true)。iOS 侧该方法为空实现，合规控制完全依赖延迟调用 initUM。

Android 依赖说明

原生 SDK 由插件的 utssdk/app-android/config.json 声明 Maven 坐标，云打包时 gradle 自动从 Maven Central 拉取，你不需要手工下载 aar：

"dependencies": [
  "com.umeng.umsdk:common:9.9.8",
  "com.umeng.umsdk:asms:1.8.3"
]

asms 是友盟的基础组件，缺失时 initUM 会失败，两条坐标必须同时存在。

离线打包时需要你自己声明这两条依赖。 离线打包不经过 HBuilderX 云端 gradle，插件 config.json 的依赖不会被合并到你的原生工程，需要在 Android 工程的 app/build.gradle 里补上：

dependencies {
    implementation 'com.umeng.umsdk:common:9.9.8'
    implementation 'com.umeng.umsdk:asms:1.8.3'
}

并确认 repositories 中含 mavenCentral()。云打包用户无需任何额外操作。

API 列表

完整类型声明与注释见 utssdk/interface.uts，IDE 会自动提供补全。共 25 个方法：

初始化：preInitUM initUM submitPolicyGrantResult setLogEnabled setEncryptEnabled setDomain setPageCollectionMode setScenarioType setSessionContinueMillis getUmid getZid getSdkVersion

事件与页面：onEventObject onEvent onPageStart onPageEnd

账号与属性：profileSignIn profileSignOff userProfile userProfileMobile userProfileEMail

预置属性：registerPreProperties unregisterPreProperty clearPreProperties

其他：setLocation

平台能力差异

以下三个方法在两端行为不完全一致，已在 interface.uts 中逐条注明：

preInitUM 在 Android 侧对应原生 UMConfigure.preInit()，具备真实的合规预初始化语义；iOS 原生 SDK 没有该接口，插件内实现为缓存参数、不做采集，因此 iOS 的合规控制完全靠延迟 initUM。

submitPolicyGrantResult 仅 Android 原生提供，iOS 为空实现。

setSessionContinueMillis 仅 Android 原生提供，iOS 为空实现。

这些方法在不支持的平台上保留为空实现，你写跨端代码时无需再做平台判断。

目录结构

uni_modules/umeng-common/
├── package.json                     插件清单
├── readme.md                        本文件
├── changelog.md
└── utssdk/
    ├── interface.uts                对外 API 类型声明(单一事实来源)
    ├── app-android/
    │   ├── index.uts                Kotlin 侧桥接
    │   ├── config.json              maven 坐标 / minSdkVersion / abis
    │   └── AndroidManifest.xml      插件所需权限
    └── app-ios/
        ├── index.uts                Swift 侧桥接
        ├── UMBridge.swift           Swift 原生实现
        ├── config.json              系统库依赖 / deploymentTarget
        ├── info.plist               需合并到主工程的字段
        ├── PrivacyInfo.xcprivacy    苹果隐私清单
        └── Frameworks/
            ├── UMCommon.xcframework
            └── UMDevice.xcframework

UMDevice.xcframework 是 UMCommon 的运行时依赖，已随插件一并内嵌，无需单独引入。

常见问题

控制台报「找不到模块 @/uni_modules/umeng-common」

确认插件位于工程根目录下的 uni_modules/umeng-common（注意不是 uni_modules/uni_modules/...），然后重启 HBuilderX。

用标准基座运行时报错 / 方法调用没反应

插件依赖原生 SDK，标准基座里没有，必须制作自定义调试基座。

调用 initUM 报找不到方法

导出的方法名带 UM 后缀，是 preInitUM / initUM，不是 preInit / init。

后台看不到数据

按顺序检查：AppKey 是否填对（iOS 与 Android 在友盟后台是两个独立应用、两个不同 AppKey）；是否真的调用了 initUM()（只调 preInitUM 不会上报）；是否在真机而非模拟器；调用 setLogEnabled(true) 看日志里有没有上报成功记录；检查设备网络。

Android 报 ClassNotFoundException: com.umeng.commonsdk.UMConfigure

Maven 依赖没拉到。云打包请检查打包日志中 com.umeng.umsdk 的解析结果；离线打包则需按「Android 依赖说明」在 app/build.gradle 里手工补依赖。

页面时长数据都归到同一个页面

页面采集模式用了 AUTO，拿到的是原生容器页名。请在 initUM 之后调 setPageCollectionMode('MANUAL')，并在每个页面的 onShow / onHide 手动调 onPageStart / onPageEnd。

iOS 提审被拒，提示获取了 IDFA

友盟 SDK 默认采集 IDFA 但不主动弹权限申请。若你的 App 本身不含广告功能，在 App Store Connect 提交时按苹果要求勾选「此 App 使用广告标识符用于归因分析」即可。本插件未声明 NSUserTrackingUsageDescription，不会给宿主 App 带来额外弹窗。

iOS 提审报 ITMS-91053 隐私清单问题

本插件已内置 PrivacyInfo.xcprivacy。若仍报错，请检查工程中其他三方 SDK 是否缺少隐私清单。

支持

接入问题请联系友盟技术支持，或提供以下信息便于排查：HBuilderX 版本、getSdkVersion() 返回值、真机系统版本、SDK 日志（调用 setLogEnabled(true) 后的完整控制台输出）、以及是云打包还是离线打包。