更新记录

1.0.10（2026-07-05）

优化 Android ios 鸿蒙上报问题 测试后安卓 ios 鸿蒙都能上报

1.0.9（2026-06-25）

修改ios uniapp 打包报错

1.0.8（2026-06-18）

修复ios 打包错误

平台兼容性

uni-app(4.0)

uni-app x(4.01)

xtf-umeng

xtf-umeng 是一个面向 uni-app / uni-app x 的友盟统计 UTS 插件，当前聚焦三类能力：

• 三端统一统计主干：初始化、登录/登出、事件上报、多参数事件
• APM 调试能力：页面统计、自定义日志、自定义信息、崩溃/卡顿测试
• Android 扩展能力：OAID / UMID、采集开关、页面模式、进程退出埋点等

如果你的业务需要同时支持 Android、iOS、鸿蒙，建议优先只围绕统一主干能力接入；Android 专属扩展建议只在 Android 页面或条件编译分支内使用。

当前状态

• Android：统计、APM、页面统计、OAID / UMID、真实闪退 / 真实 ANR 测试能力最完整
• iOS：统计与 APM 接口已接通，必须使用自定义基座验证；若原生 SDK / framework 未生效，接口会输出 unsupported 警告
• 鸿蒙：已接入真实 @umeng/analytics 和 @umeng/apm，但 Android 特有的细粒度 APM 开关并不一一映射
• 多端 AppKey：Android、iOS、鸿蒙必须分别使用各自的 AppKey 与 channel，不要混用
• 隐私合规：推荐在用户同意隐私协议后调用 UMsubmitPolicyGrantResult(true)，再执行 initUM(...) 或 initUMAPM(...)

平台能力矩阵

接入前提

1. 准备三端独立友盟配置

• Android、iOS、鸿蒙分别申请独立 AppKey
• 建议三个平台分别使用独立 channel
• iOS 如涉及 url scheme，按友盟要求配置为 um.${appKey}

下面这段配置结构在 uni-app 与 uni-app x 中写法相同，可以直接通用：

type UMAPMConfig = {
  debug: boolean
  enableANR: boolean
  enableNativeCrash: boolean
  enableMemory: boolean
  enableLaunch: boolean
  enablePagePerf: boolean
  paTimeoutMillis: number
}

type UMPlatformConfig = {
  appKey: string
  channel: string
  useAPMInit: boolean
  apm: UMAPMConfig
}

const DEFAULT_APM_CONFIG: UMAPMConfig = {
  debug: true,
  enableANR: true,
  enableNativeCrash: true,
  enableMemory: true,
  enableLaunch: true,
  enablePagePerf: true,
  paTimeoutMillis: 2000,
}

const ANDROID_UMENG_CONFIG: UMPlatformConfig = {
  appKey: "YOUR_ANDROID_APP_KEY",
  channel: "android",
  useAPMInit: true,
  apm: DEFAULT_APM_CONFIG,
}

const IOS_UMENG_CONFIG: UMPlatformConfig = {
  appKey: "YOUR_IOS_APP_KEY",
  channel: "ios",
  useAPMInit: true,
  apm: DEFAULT_APM_CONFIG,
}

const HARMONY_UMENG_CONFIG: UMPlatformConfig = {
  appKey: "YOUR_HARMONY_APP_KEY",
  channel: "harmony",
  useAPMInit: true,
  apm: DEFAULT_APM_CONFIG,
}

2. 使用自定义基座

这个插件包含原生三方依赖与原生混编代码，标准基座不能完整验证：

• Android：Maven / AAR 依赖、Kotlin 原生代码
• iOS：CocoaPods / Swift framework
• 鸿蒙：ohpm / har / ets 原生桥接

因此以下场景都必须重新打自定义基座：

• 修改 Android / iOS / 鸿蒙 SDK 版本
• 修改 Kotlin / Swift / ets 原生代码
• 修改原生依赖配置
• 修改会影响原生构建的 manifest.json / 宿主配置

常规流程：

1. 打开项目并配置 manifest.json
2. 在 HBuilderX 中执行云端打包
3. 勾选“自定义调试基座”
4. 安装新的自定义基座到真机
5. 再运行当前项目

特别注意：

• Android 当前“真实闪退”原生实现已经从 RuntimeException 测试切到更接近真实原生崩溃的 signal crash 测试；如果设备上仍然看到旧的 xtf-umeng native test crash Java 栈，说明你跑的还是旧自定义基座
• 原生代码变更无法依赖普通热更新立即生效

3. 隐私协议先于初始化

推荐顺序：

1. 监听用户隐私同意状态
2. 调用 UMsubmitPolicyGrantResult(true)
3. 调用 initUM(...) 或 initUMAPM(...)

下面这段隐私同意后再初始化的调用方式，在 uni-app 与 uni-app x 中可以通用：

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

export default {
  methods: {
    onPrivacyAgreed() {
      UMsubmitPolicyGrantResult(true)
      initUMAPM("YOUR_ANDROID_APP_KEY", "android", true, true, true, true, true, true, 2000)
    }
  }
}

4. 鸿蒙宿主配置说明

鸿蒙如果走资源文件方式，宿主工程可维护：

• AppScope/resources/rawfile/umconfig.json
• harmony-configs/entry/src/main/module.json5
• harmony-configs/AppScope/resources/base/element/string.json

当前示例工程优先推荐直接用代码传 appKey / channel，资源文件方式主要作为宿主兼容补充。

导入方式

下面这组导入在 uni-app 与 uni-app x 中写法相同：

import {
  initUM,
  initUMAPM,
  UMsubmitPolicyGrantResult,
  UMonProfileSignIn,
  UMonProfileSignOff,
  UMonEvent,
  UMonEventObject,
  UMonPageStart,
  UMonPageEnd,
  UMAPMAddCustomInfo,
  UMAPMGenerateCustomLog,
  UMAPMTriggerNativeCrashWithDelay,
  UMAPMTriggerANRWithBlockMillis,
} from "@/uni_modules/xtf-umeng"

如果你只做 Android，还可以继续使用 Android 扩展能力。

推荐初始化方式

只接统计

下面这段初始化写法在 uni-app 与 uni-app x 中相同：

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

export default {
  onLaunch() {
    UMsubmitPolicyGrantResult(true)
    initUM("YOUR_ANDROID_APP_KEY", "android")
  }
}

可直接放在 App.vue 或 App.uvue 中。

同时接统计和 APM

下面这段初始化写法在 uni-app 与 uni-app x 中相同：

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

export default {
  onLaunch() {
    UMsubmitPolicyGrantResult(true)
    initUMAPM("YOUR_ANDROID_APP_KEY", "android", true, true, true, true, true, true, 2000)
  }
}

可直接放在 App.vue 或 App.uvue 中。

说明：

• Android：initUMAPM(...) 当前会同时完成 UMConfigure.init(...) 与 UMCrash.init(...)，普通统计事件与 APM 初始化走同一入口
• iOS：必须使用最新自定义基座验证
• 鸿蒙：会走真实 @umeng/analytics / @umeng/apm，Android 专属 APM 开关不会逐个映射

API 总览

一、三端统一主干 API

下面这些方法的导入写法在 uni-app 与 uni-app x 中相同：

import {
  initUM,
  initUMAPM,
  UMsubmitPolicyGrantResult,
  UMonProfileSignIn,
  UMonProfileSignIns,
  UMonProfileSignInWithProvider,
  UMonProfileSignOff,
  UMonEvent,
  UMonEventObject,
  UMonPageStart,
  UMonPageEnd,
  UMAPMAddCustomInfo,
  UMAPMGenerateCustomLog,
  UMAPMTriggerNativeCrashWithDelay,
  UMAPMTriggerANRWithBlockMillis,
} from "@/uni_modules/xtf-umeng"

initUM(key, channel)

• 作用：初始化统计 SDK
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

UMsubmitPolicyGrantResult(true)
initUM("YOUR_ANDROID_APP_KEY", "android")

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

• 作用：初始化统计 + APM
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

UMsubmitPolicyGrantResult(true)
initUMAPM("YOUR_ANDROID_APP_KEY", "android", true, true, true, true, true, true, 2000)

UMsubmitPolicyGrantResult(flag)

• 作用：提交隐私同意结果
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

UMsubmitPolicyGrantResult(true)

UMonProfileSignIn(id)

• 作用：上报登录用户 ID，不带 provider
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

UMonProfileSignIn("user-001")

UMonProfileSignIns(provider, id)

• 作用：兼容旧命名的带来源登录上报
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

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

UMonProfileSignInWithProvider(id, provider)

• 作用：带 provider 的登录上报
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

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

UMonProfileSignOff()

• 作用：登出上报
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

UMonProfileSignOff()

UMonEvent(eventID)

• 作用：上报单事件
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

UMonEvent("demo_event")

UMonEventObject(eventID, key, value)

• 作用：上报多参数事件
• 平台：Android / iOS / 鸿蒙
• 注意：key.length 与 value.length 必须一致
• 调用例子（uni-app / uni-app x 通用）：

UMonEventObject("purchase_click", ["sku_id", "source"], ["sku-001", "banner"])

UMonPageStart(viewName)

• 作用：页面开始埋点

• 平台：Android / iOS / 鸿蒙

• 调用例子（uni-app / uni-app x 通用）：

export default {
  onShow() {
    UMonPageStart("statistics-demo")
  }
}

可直接放在页面的 onShow() 中。

UMonPageEnd(viewName)

• 作用：页面结束埋点

• 平台：Android / iOS / 鸿蒙

• 调用例子（uni-app / uni-app x 通用）：

export default {
  onHide() {
    UMonPageEnd("statistics-demo")
  }
}

可直接放在页面的 onHide() 中。

UMAPMAddCustomInfo(key, value)

• 作用：写入 APM 自定义信息
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

UMAPMAddCustomInfo("current_page", "apm-demo")
UMAPMAddCustomInfo("demo_scene", "apm_verify")

UMAPMGenerateCustomLog(message, logType)

• 作用：写入 APM 自定义日志
• 平台：Android / iOS / 鸿蒙
• 调用例子（uni-app / uni-app x 通用）：

UMAPMGenerateCustomLog("uni-app x apm custom log", "demo_apm_log")

UMAPMTriggerNativeCrashWithDelay(delayMillis)

• 作用：延迟触发崩溃测试
• 平台差异：Android 为真实原生崩溃测试；iOS 需自定义基座验证；鸿蒙当前映射为 JS 异常测试
• 调用例子（uni-app / uni-app x 通用）：

UMAPMTriggerNativeCrashWithDelay(2000)

UMAPMTriggerANRWithBlockMillis(blockMillis)

• 作用：按毫秒阻塞主线程，测试 ANR / 卡顿
• 平台差异：Android 为真实 ANR；鸿蒙当前映射为主线程阻塞测试
• 调用例子（uni-app / uni-app x 通用）：

UMAPMTriggerANRWithBlockMillis(20000)

二、Android 扩展 API

下面这些方法主要面向 Android 页面或 Android 调试页。方法调用本身在 uni-app 与 uni-app x 中写法相同：

import {
  UMpreInit,
  UMsetDebugLogEnabled,
  UMsetProcessEvent,
  UMsetPageCollectionModeAuto,
  UMsetPageCollectionModeManual,
  UMuserProfileMobile,
  UMuserProfileEMail,
  UMuserProfile,
  UMonKillProcess,
  UMenableImsiCollection,
  UMenableIccidCollection,
  UMenableImeiCollection,
  UMenableWiFiMacCollection,
  onUMgetOaid,
  getUMIDString,
  UMAPMSetDebug,
  UMAPMEnableANRLog,
  UMAPMEnableNativeLog,
  UMAPMEnableMemoryMonitor,
  UMAPMEnableKillProcessAfterCrash,
  UMAPMSetPaTimeoutTime,
  UMAPMTriggerNativeCrash,
  UMAPMTriggerANR,
} from "@/uni_modules/xtf-umeng"

UMpreInit(key, channel)

• 作用：仅预初始化，不做完整统计启动
• 调用例子（uni-app / uni-app x 通用）：

UMpreInit("YOUR_ANDROID_APP_KEY", "android")

UMsetDebugLogEnabled(flag)

• 作用：打开 / 关闭友盟调试日志
• 调用例子（uni-app / uni-app x 通用）：

UMsetDebugLogEnabled(true)

UMsetProcessEvent(flag)

• 作用：多进程事件开关
• 调用例子（uni-app / uni-app x 通用）：

UMsetProcessEvent(true)

UMsetPageCollectionModeAuto()

• 作用：切到自动页面采集
• 调用例子（uni-app / uni-app x 通用）：

UMsetPageCollectionModeAuto()

UMsetPageCollectionModeManual()

• 作用：切到手动页面采集
• 调用例子（uni-app / uni-app x 通用）：

UMsetPageCollectionModeManual()

UMuserProfileMobile(mobile)

• 作用：写入手机号属性
• 调用例子（uni-app / uni-app x 通用）：

UMuserProfileMobile("***")

UMuserProfileEMail(email)

• 作用：写入邮箱属性
• 调用例子（uni-app / uni-app x 通用）：

UMuserProfileEMail("demo@example.com")

UMuserProfile(key, value)

• 作用：写入自定义用户属性
• 调用例子（uni-app / uni-app x 通用）：

UMuserProfile("member_level", "vip")

UMonKillProcess()

• 作用：在进程退出前尝试保存统计状态
• 调用例子（uni-app / uni-app x 通用）：

UMonKillProcess()

UMenableImsiCollection(flag)

• 作用：IMSI 采集开关
• 调用例子（uni-app / uni-app x 通用）：

UMenableImsiCollection(false)

UMenableIccidCollection(flag)

• 作用：ICCID 采集开关
• 调用例子（uni-app / uni-app x 通用）：

UMenableIccidCollection(false)

UMenableImeiCollection(flag)

• 作用：IMEI 采集开关
• 调用例子（uni-app / uni-app x 通用）：

UMenableImeiCollection(false)

UMenableWiFiMacCollection(flag)

• 作用：WiFi Mac 采集开关
• 调用例子（uni-app / uni-app x 通用）：

UMenableWiFiMacCollection(false)

onUMgetOaid(callback)

• 作用：获取 OAID
• 调用例子（uni-app / uni-app x 通用）：

onUMgetOaid((oaid) => {
  console.log("current oaid", oaid)
})

getUMIDString()

• 作用：获取 UMID
• 调用例子（uni-app / uni-app x 通用）：

const umid = getUMIDString()
console.log("current umid", umid)

UMAPMSetDebug(flag)

• 作用：APM 调试日志开关
• 调用例子（uni-app / uni-app x 通用）：

UMAPMSetDebug(true)

UMAPMEnableANRLog(flag)

• 作用：APM ANR 开关
• 调用例子（uni-app / uni-app x 通用）：

UMAPMEnableANRLog(true)

UMAPMEnableNativeLog(flag)

• 作用：APM native crash 开关
• 调用例子（uni-app / uni-app x 通用）：

UMAPMEnableNativeLog(true)

UMAPMEnableMemoryMonitor(flag)

• 作用：APM 内存监控开关
• 调用例子（uni-app / uni-app x 通用）：

UMAPMEnableMemoryMonitor(true)

UMAPMEnableKillProcessAfterCrash(flag)

• 作用：崩溃后是否主动杀进程
• 调用例子（uni-app / uni-app x 通用）：

UMAPMEnableKillProcessAfterCrash(true)

UMAPMSetPaTimeoutTime(timeoutMillis)

• 作用：页面卡顿阈值
• 调用例子（uni-app / uni-app x 通用）：

UMAPMSetPaTimeoutTime(2000)

UMAPMTriggerNativeCrash()

• 作用：立即触发崩溃测试
• 调用例子（uni-app / uni-app x 通用）：

UMAPMTriggerNativeCrash()

UMAPMTriggerANR()

• 作用：立即触发 ANR 测试
• 调用例子（uni-app / uni-app x 通用）：

UMAPMTriggerANR()

三、iOS / 鸿蒙差异说明

iOS

• 当前接口以真实原生桥接为主，但必须使用自定义基座验证
• 如果你看到 xtf-umeng iOS: xxx is not available until the analytics pod is verified，通常说明原生 pod / framework 没有真正装进当前基座

鸿蒙

• initUMAPM(...) 当前通过官方 ApmPlugin 接入
• UMAPMSetDebug、UMAPMEnableANRLog、UMAPMEnableNativeLog、UMAPMEnableMemoryMonitor、UMAPMEnableKillProcessAfterCrash、UMAPMSetPaTimeoutTime 这些 Android 专属细粒度能力在鸿蒙端只保留兼容导出，不会等价实现
• UMAPMTriggerNativeCrashWithDelay(...) 在鸿蒙端当前映射为 JS 异常测试
• UMAPMTriggerANRWithBlockMillis(...) 在鸿蒙端当前映射为主线程阻塞测试

调试建议

Android 统计 / APM 联调

• 点“测试真实闪退”后，应用应该真实退出；若控制台仍然只出现 RuntimeException 栈而应用不退出，优先怀疑设备仍在运行旧自定义基座
• 点“测试真实 ANR”后，主线程会阻塞约 20 秒，属于预期行为
• 崩溃 / ANR 数据通常不是瞬时进入后台，建议崩溃后重新打开应用，再等待后台补传

iOS 联调

• 必须使用最新自定义基座
• 如果接口无效但不崩溃，优先看原生日志或 unsupported 警告

鸿蒙联调

• 建议先确认宿主权限与 UMsubmitPolicyGrantResult(true) 是否已执行
• 如果接口无效，优先看宿主 module.json5、rawfile/umconfig.json 和运行日志

常见问题

1. Android 有日志但没有真实闪退

最常见原因是：

• 你仍在运行旧自定义基座
• 设备上还没有安装包含最新 Kotlin 原生代码的基座

当前插件的新实现已经改成 signal crash 测试；如果仍然看到旧的 xtf-umeng native test crash Java 栈，说明原生改动没有真正进设备。

2. Android 统计事件不上报

优先确认：

• 是否先调用了 UMsubmitPolicyGrantResult(true)
• 是否走了 initUM(...) 或 initUMAPM(...)
• 是否使用了当前平台自己的 AppKey / channel
• 是否是旧自定义基座

3. iOS / 鸿蒙接口存在但效果不一致

这是当前三端 SDK 能力差异导致的正常现象。建议把“统一主干能力”和“平台扩展能力”分开看：

• 统一主干：初始化、登录、登出、事件、多参数事件、页面统计、APM 自定义日志/信息
• 平台扩展：Android 的 OAID / UMID / 采集开关 / 真闪退 / 真 ANR 等

版本与验证建议

• 修改原生代码后先重新打自定义基座，再开始联调
• Android 优先验证：initUMAPM(...)、UMonEvent(...)、UMonPageStart/End(...)、UMAPMGenerateCustomLog(...)
• iOS 优先验证：初始化、自定义事件、APM 自定义日志、页面统计
• 鸿蒙优先验证：初始化、自定义事件、ApmPlugin、权限与宿主配置

如果你要继续扩展插件，建议优先保持三端统一主干行为一致，再逐步补平台专属调试接口。