更新记录

1.0.9（2026-06-25）

修改ios uniapp 打包报错

1.0.8（2026-06-18）

修复ios 打包错误

1.0.7（2026-06-15）

• 升级为 Android、iOS、鸿蒙三端统一统计主干，统一支持初始化、登录登出、自定义事件和多参数事件。
• 保留 Android 扩展能力，补充页面采集、OAID、UMID、APM、自定义日志、真实闪退与真实 ANR 测试接口。
• 重构 demo 结构，调整为首页 + 统计 Demo 的更清晰入口形式。
• 完善插件文档，新增方法说明、uni-app / uni-app x 示例、友盟 Key 申请说明、自定义基座流程与注意事项。

平台兼容性

uni-app(4.0)

uni-app x(4.01)

xtf-umeng

xtf-umeng 是一个面向 uni-app / uni-app x 的友盟统计 UTS 插件。

当前文档按两层能力来说明：

• 三端统一主干能力：初始化、登录、登出、自定义事件、多参数事件
• Android 扩展能力：页面采集、设备标识、APM、真实闪退、真实 ANR 等

如果你要做跨端业务，建议优先使用三端统一主干能力；如果你只做 Android，可以继续使用 Android 扩展能力。

平台支持

友盟 Key 申请流程

1. 注册并登录友盟开发者平台

• 打开友盟开发者中心
• 使用企业或个人账号登录
• 进入“产品管理”或“应用管理”

2. 创建应用

• 选择“移动统计”产品
• 新建应用
• 分别填写 Android、iOS、鸿蒙对应的应用信息

3. 获取 AppKey

• 创建成功后，在应用详情页可以看到 AppKey
• Android、iOS、鸿蒙建议分别确认渠道值 channel
• iOS 如涉及 url scheme，按友盟要求配置为 um.${appkey}

4. 建议的配置方式

• App.uvue 中推荐通过 UMsubmitPolicyGrantResult(true) 和 initUM(appKey, channel) 配合初始化
• 鸿蒙端已接入真实 @umeng/analytics / @umeng/apm，插件内会兜底执行 preInit({ appKey, channel, context, plugins })
• 友盟官方仍推荐宿主工程在 AbilityStage.onCreate 中尽早 preInit
• 如果业务没有显式调用 UMsubmitPolicyGrantResult(...)，鸿蒙桥接层会按当前实现直接尝试初始化；但从合规和官方推荐角度，仍建议先提交隐私授权结果再初始化
• 如果你希望保留官方示例的资源文件方式，也可以同步维护 AppScope/resources/rawfile/umconfig.json，插件目录下保留的 uni_modules/xtf-umeng/utssdk/app-harmony/resources/rawfile/umconfig.json 主要用于示例占位

5. 平台配置示例

Android / iOS 友盟模块配置示例

如果你在 manifest.json 中配置友盟模块，可参考下面的字段组织方式：

{
  "app": {
    "distribute": {
      "android": {
        "urltypes": "um.xxxxxxxxxx"
      },
      "ios": {
        "urltypes": "um.xxxxxxxxxx"
      },
      "sdkConfigs": {
        "statics": {
          "umeng": {
            "appkey_ios": "xxxxxxxxxx",
            "channelid_ios": "appstore",
            "appkey_android": "xxxxxxxxxx",
            "channelid_android": "umeng"
          }
        }
      }
    }
  }
}

鸿蒙配置示例

鸿蒙端当前已接入真实 ohpm 依赖，并优先使用 UMsubmitPolicyGrantResult(true) 与 initUM(appKey, channel) 传入配置；如果你想保留官方示例的资源文件方式，也可以在宿主工程的 AppScope/resources/rawfile/umconfig.json 中配置：

{
  "appKey": "xxxxxxxxxx",
  "channel": "harmony"
}

自定义基座

为什么需要自定义基座

根据 uni-app x UTS 插件文档，Android 平台原生配置和三方 SDK 变更需要云端打包后才能生效；真机调试时应使用自定义基座。

这个插件涉及：

• Android Maven / AAR 三方依赖
• iOS CocoaPods 依赖
• 鸿蒙 ohpm / har 依赖

因此调试和验证时，不能只依赖标准基座。

如何打包自定义基座

常规流程如下：

1. 打开项目
2. 配好 manifest.json、插件依赖和友盟参数
3. 在 HBuilderX 中选择云端打包
4. 勾选“自定义调试基座”
5. 打包完成后，使用该自定义基座运行项目

自定义基座注意事项

• 修改插件原生依赖后，必须重新打自定义基座
• 修改 Android / iOS / 鸿蒙三方 SDK 版本后，必须重新打自定义基座
• 标准基座不带你的包名、签名和友盟配置，不能代替正式验证
• 若工程代码没有真实引用某些能力，对应模块可能被摇树裁剪；打包前建议至少有一处真实调用
• Android 远程 Maven 依赖本地编译时，HBuilderX 需要正确配置 JDK 路径
• iOS 在 Windows 环境下不能本地跑 CocoaPods，只能通过云端打包或在 macOS 环境验证
• 鸿蒙需保证本机 DevEco Studio / HBuilderX 对应环境满足版本要求

导入方式

如果只是使用三端统一主干能力，可以这样导入：

import {
  initUM,
  UMonProfileSignIn,
  UMonProfileSignIns,
  UMonProfileSignInWithProvider,
  UMonProfileSignOff,
  UMonEvent,
  UMonEventObject,
} from "@/uni_modules/xtf-umeng"

如果你只做 Android，也可以额外导入 Android 扩展能力。

推荐初始化方式

uni-app 与 uni-app x 通用写法

初始化写法相同，可以合并。

import { initUM } from "@/uni_modules/xtf-umeng"

export default {
  onLaunch() {
    initUM("你的AppKey", "你的渠道")
  }
}

结合隐私同意再初始化

建议在用户同意隐私协议后再初始化友盟，鸿蒙端尤其建议这样使用。

import { initUM, UMsubmitPolicyGrantResult } from "@/uni_modules/xtf-umeng"

export default {
  methods: {
    onPrivacyAgreed() {
      UMsubmitPolicyGrantResult(true)
      initUM("你的AppKey", "你的渠道")
    }
  }
}

三端统一主干方法

下面这些方法推荐作为跨端公共能力使用。

initUM(key, channel)

• 作用：初始化友盟统计 SDK
• 参数：
  • key：友盟 AppKey
  • channel：渠道名，如 android、ios、harmony、appstore
• 平台：Android / iOS / 鸿蒙
• 鸿蒙说明：插件会优先走真实 @umeng/analytics，内部兜底执行 preInit({ plugins: [new InternalPlugin()] })
• 鸿蒙建议：正式项目中仍建议宿主在 AbilityStage.onCreate 中按友盟官方文档尽早 preInit

示例：

initUM("你的AppKey", "android")

UMonProfileSignIn(id)

• 作用：上报登录用户 ID，不带来源
• 参数：
  • id：用户账号 ID
• 平台：Android / iOS / 鸿蒙

示例：

UMonProfileSignIn("user-001")

UMonProfileSignIns(provider, id)

• 作用：上报登录用户 ID，并带账号来源
• 参数：
  • provider：账号来源，如 WEIXIN、APPLE、CUSTOM
  • id：用户账号 ID
• 平台：Android / iOS / 鸿蒙
• 说明：这是兼容旧命名的方法

示例：

UMonProfileSignIns("CUSTOM", "user-001")

UMonProfileSignInWithProvider(id, provider)

• 作用：与 UMonProfileSignIns 类似，但参数顺序更直观
• 参数：
  • id：用户账号 ID
  • provider：账号来源
• 平台：Android / iOS / 鸿蒙
• 建议：新代码优先使用这个方法

示例：

UMonProfileSignInWithProvider("user-001", "CUSTOM")

UMonProfileSignOff()

• 作用：上报用户登出
• 平台：Android / iOS / 鸿蒙

示例：

UMonProfileSignOff()

UMonEvent(eventID)

• 作用：上报单事件埋点
• 参数：
  • eventID：事件 ID
• 平台：Android / iOS / 鸿蒙

示例：

UMonEvent("sample_visit")

UMonEventObject(eventID, key, value)

• 作用：上报带参数的事件埋点
• 参数：
  • eventID：事件 ID
  • key：参数名数组
  • value：参数值数组
• 平台：Android / iOS / 鸿蒙
• 注意：key.length 和 value.length 必须一致

uni-app 示例

UMonEventObject("sample_action", ["page", "result"], ["home", "success"])

uni-app x 示例

uni-app x 中若类型推断不稳定，建议显式标注数组类型：

UMonEventObject(
  "sample_action",
  ["page", "result"] as string[],
  ["home", "success"] as string[]
)

Android 扩展方法

下面这些方法是 Android 扩展能力，不建议作为三端统一接口主干使用。

初始化与调试

UMpreInit(key, channel)

• 作用：友盟预初始化
• 平台：Android

UMpreInit("你的AppKey", "android")

UMsetDebugLogEnabled(flag)

• 作用：打开或关闭友盟调试日志
• 平台：Android

UMsetDebugLogEnabled(true)

UMsetProcessEvent(flag)

• 作用：设置是否支持多进程事件上报
• 平台：Android

UMsetProcessEvent(true)

页面采集

UMsetPageCollectionModeAuto()

• 作用：切换为自动页面采集
• 平台：Android

UMsetPageCollectionModeAuto()

UMsetPageCollectionModeManual()

• 作用：切换为手动页面采集
• 平台：Android

UMsetPageCollectionModeManual()

UMonPageStart(viewName)

• 作用：页面进入打点
• 平台：Android

UMonPageStart("goods-detail")

UMonPageEnd(viewName)

• 作用：页面离开打点
• 平台：Android

UMonPageEnd("goods-detail")

用户属性

UMuserProfileMobile(mobile)

• 作用：设置手机号属性
• 平台：Android

UMuserProfileMobile("***")

UMuserProfileEMail(email)

• 作用：设置邮箱属性
• 平台：Android

UMuserProfileEMail("demo@test.com")

UMuserProfile(key, value)

• 作用：设置自定义用户属性
• 平台：Android

UMuserProfile("memberLevel", "vip")

退出保存

UMonKillProcess()

• 作用：在主动退出、杀进程前触发数据保存
• 平台：Android
• 建议：在 uni.exit() 前调用

UMonKillProcess()
uni.exit()

设备标识与采集开关

UMsubmitPolicyGrantResult(flag)

• 作用：提交隐私授权结果
• 平台：Android / 鸿蒙
• 鸿蒙说明：
  • 传 true 后，会消费待执行的鸿蒙统计 / APM 初始化
  • 传 false 后，不会执行正式 init()
  • 推荐与 initUM(...) 或 initUMAPM(...) 配合使用

UMsubmitPolicyGrantResult(true)

UMenableImsiCollection(flag)

• 作用：控制 IMSI 采集
• 平台：Android

UMenableImsiCollection(true)

UMenableIccidCollection(flag)

• 作用：控制 ICCID 采集
• 平台：Android

UMenableIccidCollection(true)

UMenableImeiCollection(flag)

• 作用：控制 IMEI 采集
• 平台：Android

UMenableImeiCollection(true)

UMenableWiFiMacCollection(flag)

• 作用：控制 WiFi MAC 采集
• 平台：Android

UMenableWiFiMacCollection(true)

onUMgetOaid(callback)

• 作用：获取 OAID
• 平台：Android

uni-app 示例

onUMgetOaid(function(id) {
  console.log(id)
})

uni-app x 示例

onUMgetOaid(function(id: string) {
  console.log(id)
})

getUMIDString()

• 作用：获取友盟 UMID
• 平台：Android

const umid = getUMIDString()
console.log(umid)

APM 方法

这些方法主要用于 Android 侧友盟性能监控；其中 initUMAPM 在鸿蒙端会真实接入 ApmPlugin，其余细粒度 APM 开关暂仍以 Android 为主。

initUMAPM(appKey, channel, debug, enableANR, enableNativeCrash, enableMemory, enableLaunch, enablePagePerf, paTimeoutMillis)

• 作用：初始化 APM
• 平台：Android / 鸿蒙

initUMAPM("你的AppKey", "android", true, true, true, true, true, true, 2000)

• 鸿蒙说明：会按友盟官方文档通过 preInit({ plugins: [new InternalPlugin(), new ApmPlugin()] }) 挂载 APM，并在隐私同意后调用 init()。
• 鸿蒙限制：enableANR、enableNativeCrash、enableMemory、enableLaunch、enablePagePerf、paTimeoutMillis 这些 Android 风格参数当前仅保留兼容签名，不逐项映射到鸿蒙 SDK。
• 鸿蒙注意：如果已经先调用 initUM(...) 完成了不带 ApmPlugin 的统计初始化，再调用 initUMAPM(...) 无法在当前会话中补挂 APM；需要一开始就走 initUMAPM(...)。

UMAPMSetDebug(flag)

• 作用：设置 APM 调试开关

UMAPMSetDebug(true)

UMAPMEnableANRLog(flag)

• 作用：开启或关闭 ANR 监控

UMAPMEnableANRLog(true)

UMAPMEnableNativeLog(flag)

• 作用：开启或关闭 Native Crash 监控

UMAPMEnableNativeLog(true)

UMAPMEnableMemoryMonitor(flag)

• 作用：开启或关闭内存监控

UMAPMEnableMemoryMonitor(true)

UMAPMEnableKillProcessAfterCrash(flag)

• 作用：设置崩溃后是否杀进程

UMAPMEnableKillProcessAfterCrash(true)

UMAPMSetPaTimeoutTime(timeoutMillis)

• 作用：设置页面性能统计超时时间

UMAPMSetPaTimeoutTime(2000)

UMAPMAddCustomInfo(key, value)

• 作用：写入 APM 自定义信息

UMAPMAddCustomInfo("scene", "payment")

UMAPMGenerateCustomLog(message, logType)

• 作用：写入 APM 自定义日志

UMAPMGenerateCustomLog("apm custom log", "demo_apm_log")

Android 真机测试方法

下面两个方法会让 App 真正异常，仅用于 Android 真机联调。

UMAPMTriggerNativeCrash()

• 作用：立即触发真实闪退
• 平台：Android
• 注意：是 App 真实崩溃，不是普通报错

UMAPMTriggerNativeCrash()

UMAPMTriggerNativeCrashWithDelay(delayMillis)

• 作用：延迟触发真实闪退
• 平台：Android

UMAPMTriggerNativeCrashWithDelay(2000)

UMAPMTriggerANR()

• 作用：触发真实 ANR
• 平台：Android

UMAPMTriggerANR()

UMAPMTriggerANRWithBlockMillis(blockMillis)

• 作用：按指定毫秒数阻塞主线程，触发真实 ANR
• 平台：Android
• 建议：传 15000 或 20000 以上

UMAPMTriggerANRWithBlockMillis(20000)

跨端使用建议

如果你要写三端公共业务代码，建议只使用下面这些方法：

• initUM
• UMonProfileSignIn
• UMonProfileSignIns
• UMonProfileSignInWithProvider
• UMonProfileSignOff
• UMonEvent
• UMonEventObject
• UMsubmitPolicyGrantResult

其余能力建议通过条件编译只在 Android 使用。若鸿蒙侧需要性能监控，则在鸿蒙分支单独调用 initUMAPM(...)。

条件编译示例

只在 Android 使用页面采集

// #ifdef APP-ANDROID
UMsetPageCollectionModeManual()
UMonPageStart("home")
// #endif

只在 Android 使用 APM

// #ifdef APP-ANDROID
initUMAPM("你的AppKey", "android", true, true, true, true, true, true, 2000)
// #endif

参考文档

• UTS 语法
• UTS 插件
• UTS iOS CocoaPods
• uni-app x 项目与基座说明