更新记录

1.2.0（2026-09-01） 下载此版本

新增归因与 DeepLink 能力。

• 新增安装归因结果回调 setOnAttributionResultListener，双端统一返回 { attribution, errorCode }
• 新增 iOS 专属归因开关 setASAEnabled / setSKANEnabled（必须在 initUM 之前调用）
• 新增 Deferred DeepLink 安装参数获取 getInstallParams
• 新增 DeepLink 解析回调 setDeepLinkCallback 与链接处理函数 handleOpenURL / handleUniversalLink / handlePasteboardURL
• 新增归因预置事件常量 UMEventUserRegister / UMEventInAppConvert / UMEventOrderRefund / UMEventAdRevenueEvent 及 23 个参数 key
• DeepLink 不自动拦截原生生命周期，由业务侧在 App.uvue 的 onLaunch / onShow 中手动调用

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

新增 uni-app x 支持；iOS 侧内部重构，对外 API 无变化。

• 新增 uni-app x 支持（App-Android / App-iOS），与经典 uni-app 共用同一套函数式 API，已在两端真机打包验证
• iOS 移除内部 Swift 中转层，改为从 index.uts 直连原生 UMCommon
• 环境要求提升：需 HBuilderX 4.0+（uni-app 4.31+、uni-app-x 4.61+）；仍在 HBuilderX 3.9x 的经典工程请继续使用 1.0.1

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(4.31)

uni-app x(4.61)

其他

友盟统计分析 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。

⚠️ 授权弹窗不能在 App.uvue 的 onLaunch 里弹，这是 uni-app x 特有的坑。uni.showModal 底层由 dialogPage 实现，dialogPage 必须挂在 parentPage 上、不指定时默认取「当前页面」；而 onLaunch 阶段首页尚未创建，挂不上会导致首页渲染异常（页面内容全空）。正确做法是把弹窗放到首页的 onReady，或改用 uni.openDialogPage（只有它有「在 onLaunch 调用则绑定到首页」的特殊处理，也是官方合规指南推荐的方式）。preInitUM 仍应留在 onLaunch。

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 会自动提供补全。共 33 个导出函数（25 个原基础 API + 8 个新增归因/DeepLink API），另有 27 个预置事件常量：

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

归因：setOnAttributionResultListener setASAEnabled setSKANEnabled getInstallParams

DeepLink：setDeepLinkCallback handleOpenURL handleUniversalLink handlePasteboardURL

事件与页面：onEventObject onEvent onPageStart onPageEnd

账号与属性：profileSignIn profileSignOff userProfile userProfileMobile userProfileEMail

预置属性：registerPreProperties unregisterPreProperty clearPreProperties

其他：setLocation

预置归因事件常量：UMEventUserRegister UMEventInAppConvert UMEventOrderRefund UMEventAdRevenueEvent 及 23 个 UMEventParam* 参数 key。

常量不从插件入口导出，而是定义在 common/constants.uts，需单独引入：

import { UMEventUserRegister } from '@/uni_modules/umeng-common/common/constants.uts'

为何不放在插件里：UTS 插件内的 export const 在 Android 侧不会进入预编译产物（本地运行报“找不到名称”）， iOS 侧生成 JS 代理时会丢掉字符串引号（运行报 ReferenceError: Can't find variable）。

归因与 DeepLink 接入

1. 归因开关（仅 iOS）

setASAEnabled（Apple Search Ads 归因采集）和 setSKANEnabled（SKAdNetwork 注册）必须在 initUM 之前调用，且仅在 iOS 生效；Android 侧为空实现。

// #ifdef APP-IOS
setASAEnabled(true)
setSKANEnabled(true)
// #endif
preInitUM({ appKey: '你的AppKey', channel: 'official' })
initUM({ appKey: '你的AppKey', channel: 'official' })

2. 安装归因结果回调

import { setOnAttributionResultListener } from '@/uni_modules/umeng-common'

setOnAttributionResultListener((res) => {
  if (res.errorCode === 0) {
    console.log('归因成功', res.attribution)
  } else {
    console.log('归因失败', res.errorCode)
  }
})

3. Deferred DeepLink 安装参数

import { getInstallParams } from '@/uni_modules/umeng-common'

getInstallParams({
  success: (res) => console.log('安装参数', res.params),
  fail: (res) => console.log('无安装参数', res.error)
})

4. DeepLink 唤起处理

插件不自动拦截原生 AppDelegate / Activity 生命周期，需要业务侧在 App.uvue 的 onLaunch / onShow 中手动调用。

// App.uvue
import {
  setDeepLinkCallback,
  handleOpenURL,
  handleUniversalLink
} from '@/uni_modules/umeng-common'

export default {
  onLaunch(options: OnLaunchOptions) {
    // 1. 先注册 DeepLink 回调
    setDeepLinkCallback((params) => {
      console.log('DeepLink 参数', params)
      // 业务侧自行决定路由跳转
    })

    // 2. 再处理本次启动链接
    this.handleLaunchLink(options.appLink, options.appScheme)
  },
  onShow(options: OnShowOptions) {
    // 后台被唤起也要处理
    this.handleLaunchLink(options.appLink, options.appScheme)
  },
  methods: {
    // OnLaunchOptions / OnShowOptions 是两个独立类型，只取需要的字段传入，
    // 否则 uts 强类型下无法用一个方法兼容两种入参；
    // 也不能把入参写成 any 后取属性，那会报“找不到名称 appLink”
    handleLaunchLink(appLink: string | null, appScheme: string | null) {
      if (appLink != null && appLink!.length > 0) {
        handleUniversalLink(appLink!)
      } else if (appScheme != null && appScheme!.length > 0) {
        handleOpenURL(appScheme!)
      }
    }
  }
}

⚠️ 这三个链接处理方法会触发网络请求去解析参数，属于采集行为。如果接入了隐私授权弹窗，未授权前不要调用它们；应先把 appLink / appScheme 缓存在内存里，等用户同意、initUM 执行完之后再补交给 SDK。

5. 预置归因事件

import { onEventObject } from '@/uni_modules/umeng-common'
import {
  UMEventUserRegister,
  UMEventParamRegisterMethod,
  UMEventParamRegisterTime
} from '@/uni_modules/umeng-common/common/constants.uts'

onEventObject(UMEventUserRegister, {
  [UMEventParamRegisterMethod]: 'phone',
  [UMEventParamRegisterTime]: Date.now()
})

6. Manifest / Associated Domains 配置提示

• Android：在 manifest.json 的 app-plus.distribute.android 或插件 AndroidManifest.xml 中声明对应的 <intent-filter> 与 android:scheme。
• iOS：在 manifest.json 的 app-plus.distribute.ios 中配置 URL Types 与 Associated Domains（Universal Link），并确保友盟后台配置的 universal link 域名与之一致。

平台能力差异

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

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

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

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

setASAEnabled / setSKANEnabled 仅 iOS 原生提供，Android 为空实现；且必须在 initUM 之前调用。

handleUniversalLink 在 iOS 侧内部构造 NSUserActivity 后调用 handleUserActivity:；Android 侧复用 handleOpenURL 的 URL 处理通道。

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

目录结构

uni_modules/umeng-common/
├── package.json                     插件清单
├── readme.md                        本文件
├── changelog.md
└── utssdk/
    ├── interface.uts                对外 API 类型声明(单一事实来源)
    ├── app-android/
    │   ├── index.uts                Android 原生实现
    │   ├── config.json              maven 坐标 / minSdkVersion / abis
    │   └── AndroidManifest.xml      插件所需权限
    └── app-ios/
        ├── index.uts                iOS 原生实现(直连 UMCommon)
        ├── 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) 后的完整控制台输出）、以及是云打包还是离线打包。