更新记录

1.0.0（2026-07-31） 下载此版本

初始版本

平台兼容性

uni-app(4.31)

uni-app x(4.61)

其他

xyz-umeng-analytics

友盟移动统计 UTS 插件，支持 Android、iOS、HarmonyOS 三端。

SDK 版本

接入步骤

1. 友盟后台配置

在 友盟官网 分别创建 Android、iOS、Harmony 应用，获取各端独立的 AppKey。

2. 初始化（隐私合规）

本插件支持两种初始化方式：

方式一：自动初始化 + 手动完成首次初始化（推荐）

插件已在各端的应用生命周期回调中实现了初始化逻辑：

• Android：在 UTSAndroidHookProxy.onCreate 中读取 AndroidManifest.xml 的 UMENG_APPKEY / UMENG_CHANNEL 完成 preInit，若已同意隐私协议则自动 init
• iOS：在 UTSiOSHookProxy.applicationDidFinishLaunchingWithOptions 中读取 info.plist 的 umconfig.appKey / umconfig.channel，若已同意隐私协议则自动初始化
• Harmony：在 UTSHarmony.onAppAbilityCreate 中读取 AppScope/resources/rawfile/umconfig.json 完成 preInit，若已同意隐私协议则自动 init

此时开发者只需处理首次启动时的隐私弹窗，在用户同意后调用一次 initSDK 即可。

参考 uni-app x 隐私合规文档，在 App.uvue 中：

<script setup lang="uts">
import * as Umeng from "@/uni_modules/xyz-umeng-analytics"

onLaunch((res: OnLaunchOptions) => {
  // 调试时开启日志，发布时删除或注释掉此行
  Umeng.setLogEnabled(true)

  // #ifdef APP
  uni.getPrivacySetting({
    success(res) {
      if (res.needAuthorization) {
        // 用户未同意隐私政策，弹出隐私弹窗页面
        uni.openDialogPage({
          url: '/pages/privacy'
        })
        // 在隐私页面中用户点击同意后调用 Umeng.initSDK(appKey, channel)
        // 非首次启动且已同意隐私协议时，插件会自动读取配置文件中的 appKey 和 channel 并完成初始化
      }
    }
  })
  // #endif
})
</script>

隐私弹窗页面中，同意按钮需使用 button 组件并设置 open-type="agreePrivacyAuthorization"：

<template>
  <view class="privacy-dialog">
    <text>请阅读并同意《隐私政策》</text>
    <button class="button" type="primary" open-type="agreePrivacyAuthorization" @click="agree">同意</button>
    <button class="button" @click="reject">不同意</button>
  </view>
</template>

<script setup lang="uts">
import * as Umeng from "@/uni_modules/xyz-umeng-analytics"

function onAgree() {
  // 用户点击同意后初始化友盟
  Umeng.initSDK(appKey, channel)
  // 关闭弹窗
  uni.closeDialogPage({})
}

function onReject() {
  // 不同意则关闭弹窗，不初始化
  uni.closeDialogPage({})
}
</script>

方式二：完全手动初始化

如果不依赖插件的自动初始化（例如需要自定义初始化时机），可手动调用全部流程：

<script setup lang="uts">
import * as Umeng from "@/uni_modules/xyz-umeng-analytics"

onLaunch((res: OnLaunchOptions) => {
  // 1. 手动预初始化（iOS 端为空操作）
  Umeng.preInit(appKey, channel)

  // 2. 调试时开启日志，发布时删除或注释掉此行
  Umeng.setLogEnabled(true)

  // 3. 判断隐私协议并初始化
  // #ifdef APP
  uni.getPrivacySetting({
    success(res) {
      if (res.needAuthorization) {
        uni.openDialogPage({ url: '/pages/privacy' })
      } else {
        Umeng.preInit(appKey, channel)
        Umeng.initSDK(appKey, channel)
      }
    }
  })
  // #endif
})
</script>

注意：三端必须使用各自独立的 AppKey，不要混用。配置文件中已设置好各端 AppKey 后，代码中调用 initSDK 时也需传入对应的 AppKey：

// #ifdef APP-ANDROID
const appKey = "your_android_appkey"
// #endif
// #ifdef APP-IOS
const appKey = "your_ios_appkey"
// #endif
// #ifdef APP-HARMONY
const appKey = "your_harmony_appkey"
// #endif
const channel = "your_channel"

3. 自定义基座

本插件包含三方原生 SDK 依赖和权限配置等资源变更，必须打自定义基座后才能正常运行。标准基座无法验证。

公共 API（三端统一）

以下 API 三端统一，通过 import * as Umeng from "@/uni_modules/xyz-umeng-analytics" 引入后调用。

初始化

自定义事件

账号统计

iOS/Android 共有 API

以下 API 在 iOS 和 Android 端可用，Harmony 端不支持，需通过条件编译使用：

// #ifdef APP-ANDROID || APP-IOS
Umeng.onEventWithLabel("purchase", "vip")
Umeng.onPageStart("home")
// ... 页面展示中 ...
Umeng.onPageEnd("home")
// #endif

自定义事件

页面统计

用户属性

Android 专属 API

以下 API 仅在 Android 端可用：

// #ifdef APP-ANDROID
Umeng.getOaid((oaid: string) => { console.log(oaid) })
Umeng.getUMIDString()
// #endif

iOS 专属 API

以下 API 仅在 iOS 端可用：

// #ifdef APP-IOS
Umeng.beginEvent("video_play")
// ... 用户看完视频 ...
Umeng.endEvent("video_play")
// #endif

时长事件

页面统计

其他

Harmony 端说明

Harmony 端基于友盟官方 Harmony SDK，支持的功能较 Android/iOS 少：

• 支持：preInit、initSDK、setLogEnabled、onEvent、onEventObject、onProfileSignIn、onProfileSignInWithProvider、onProfileSignOff
• 不支持：页面统计、时长事件、用户属性、onEventWithLabel、onEventValue 等

Harmony 端的 onEvent 内部通过 onEventObject 实现。事件可在 initSDK 前调用，SDK 最多缓存 1000 条事件。

各端 AppKey 和 Channel 配置（可选）

如果使用方式一（自动初始化），需要在各端配置文件中设置 AppKey 和 Channel。这些文件默认不存在，需手动创建。

Android

手动创建项目根目录下的 AndroidManifest.xml，在 <application> 节点内添加：

<meta-data android:name="UMENG_APPKEY" android:value="your_android_appkey" />
<meta-data android:name="UMENG_CHANNEL" android:value="your_channel" />

uni-app x 项目中 AndroidManifest.xml 的配置方式请参考 官方文档

iOS

手动创建项目根目录下的 info.plist，在 <dict> 节点内添加：

<key>umconfig</key>
<dict>
    <key>appKey</key>
    <string>your_ios_appkey</string>
    <key>channel</key>
    <string>your_channel</string>
</dict>

uni-app x 项目中 info.plist 的配置方式请参考 官方文档

HarmonyOS

手动创建 harmony-configs 目录下的 AppScope/resources/rawfile/umconfig.json 文件，内容如下：

{
  "appKey": "your_harmony_appkey",
  "channel": "your_channel"
}

如果不配置这些文件，插件不会自动初始化，需使用方式二手动调用 preInit 和 initSDK。

注意事项

1. 三端必须使用各自独立的 AppKey
2. 必须使用自定义基座验证
3. 调用各端专有 API 时必须使用 #ifdef 条件编译包裹，否则其他平台编译会报错
4. 更多使用细节请参考友盟官方文档：
   • Android SDK 集成文档
   • iOS SDK 集成文档
   • HarmonyOS SDK 集成文档