更新记录

1.1.0（2026-06-18）

c初始版本

平台兼容性

uni-app(4.66)

uni-app x(4.66)

wen-firebase-analytics

Firebase Analytics 插件，为 uni-app / uni-app x 提供原生 Google Analytics 集成。支持安卓和IOS，支持事件上报、电子商务衡量、屏幕跟踪、用户属性 / 用户 ID、Consent 模式等。

平台兼容性

uni-app (4.66)

uni-app x (4.66)

导入 uni_modules 规范插件需使用 HBuilderX 4.66+，须使用自定义基座或云打包。

关于插件

Firebase Analytics 是一种免费的应用衡量方案，可提供有关应用使用情况和用户参与度的洞察。

• 记录自定义事件与标准事件（login、search、share 等）
• 衡量电子商务（purchase、add_to_cart、view_item 等）
• 跟踪屏幕浏览（screen_view）
• 设置用户 ID、用户属性
• 设置默认事件参数
• 禁用 / 开启 Analytics 数据采集
• GDPR Consent 模式、获取 App Instance ID

SDK 版本信息

重要提示

• 必须使用自定义基座或云打包，标准基座不包含原生插件
• 须在 Firebase Console 创建项目并开启 Google Analytics
• Android 除 google-services.json 外，还须配置 nativeResources/android/res/values/config.xml（见集成步骤）
• google-services.json / GoogleService-Info.plist 中的包名 / Bundle ID 须与 manifest 一致
• 事件参数须用 createAnalyticsParams() 创建，勿直接写对象字面量
• *iOS 带回调的 API 请使用 `Options系列**（如logEventOptions`），避免重载编译问题
• Analytics 数据发送至 Google Firebase，请在隐私政策中告知用户

集成步骤

1. 创建 Firebase 项目

1. 打开 Firebase Console 创建项目
2. 创建时开启 「为此项目启用 Google Analytics」（或在「项目设置 → 集成」中启用）
3. 分别添加 Android、iOS 应用：
   • Android：填写包名 + SHA-1（可选但推荐）
   • iOS：填写 Bundle ID
4. 下载配置文件：
   • Android → google-services.json
   • iOS → GoogleService-Info.plist

2. 安装插件

1. 将 uni_modules/wen-firebase-analytics 复制到目标项目

3. 放置 Firebase 配置文件

在项目根目录 nativeResources/ 下放置（云打包 / 本地打包会自动合并）：

nativeResources/
├── android/
│   ├── google-services.json                      # Firebase 官方配置文件（建议保留）
│   └── res/
│       └── values/
│           └── config.xml                        # Firebase Android 字符串资源（必填）
└── ios/
    └── Resources/
        └── GoogleService-Info.plist

注意：

• 配置文件中的 package_name / BUNDLE_ID 必须与 manifest 一致
• IS_ANALYTICS_ENABLED 建议为 true
• 更换 Firebase 项目或包名时，须同时更新 google-services.json 与 config.xml
• Android 插件内部调用 FirebaseApp.initializeApp(context)，依赖 APK 中合并的 Android 字符串资源（即 config.xml），不会自行解析 google-services.json

Android：google-services.json 与 config.xml

参考 DCloud 插件市场 Firebase 集成说明，Android 端需将 Firebase 配置写入 nativeResources/android/res/values/config.xml，有两种处理方式：

方式一：联系作者转换

联系插件作者，将 google-services.json 转换为 config.xml，然后替换 nativeResources/android/res/values/config.xml。

方式二：手动对照替换（推荐）

1. 从 Firebase Console 下载 google-services.json，放到 nativeResources/android/google-services.json
2. 按下方对照表，将其中的值填入 nativeResources/android/res/values/config.xml

config.xml 模板示例：

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <!-- 若 json 中存在 client_type 为 3 的 oauth_client 则填写，纯 Analytics 可省略 -->
    <string name="default_web_client_id" translatable="false">YOUR_WEB_CLIENT_ID.apps.googleusercontent.com</string>
    <string name="gcm_defaultSenderId" translatable="false">322960669703</string>
    <string name="google_api_key" translatable="false">AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXX</string>
    <string name="google_app_id" translatable="false">1:322960669703:android:xxxxxxxxxxxxxxxx</string>
    <string name="google_crash_reporting_api_key" translatable="false">AIzaSyXXXXXXXXXXXXXXXXXXXXXXXXXXXX</string>
    <string name="google_storage_bucket" translatable="false">your-project.firebasestorage.app</string>
    <string name="project_id" translatable="false">your-project-id</string>
</resources>

google_api_key 与 google_crash_reporting_api_key 通常取同一个 current_key。若 google-services.json 的 oauth_client 为空数组，可省略 default_web_client_id 节点。

目录关系说明：

两者内容须保持一致；仅放 google-services.json 而不配置 config.xml，可能导致初始化失败（9020004）。

4. iOS 额外说明

• 首次云打包需能访问 CocoaPods 源（拉取 Firebase/Analytics）
• 插件 Info.plist 已设置 FirebaseAutomaticScreenReportingEnabled = false，避免与手动 screen_view 重复上报
• 模拟器与真机均支持

5. Android 权限

插件已在 AndroidManifest.xml 中声明，一般无需手动添加：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

如何使用

引入

import {
  configure,
  createAnalyticsParams,
  logEvent,
  logEventOptions,
  logLogin,
  logScreenViewOptions,
  trackPageScreen,
  setUserId,
  setUserProperty,
  logPurchase,
  EVENT_LOGIN,
  EVENT_PURCHASE
} from '@/uni_modules/wen-firebase-analytics'

初始化

在 App.uvue 的 onLaunch 中调用 configure：

// #ifdef APP-ANDROID || APP-IOS
import { configure } from '@/uni_modules/wen-firebase-analytics'
// #endif

onLaunch(() => {
  // #ifdef APP-ANDROID || APP-IOS
  configure({
    enabled: true,
    sessionTimeoutMillis: 1800000   // 30 分钟，可选
  })
  // #endif
})

configure 参数

记录事件

事件业务说明参考 Firebase 官方文档

自定义事件

// 方式一：简写（无回调）
const params = createAnalyticsParams()
params['button_name'] = 'start'
params['count'] = 1
params['enabled'] = true
logEvent('button_click', params)

// 方式二：带回调（iOS 推荐）
logEventOptions({
  name: 'button_click',
  params: createAnalyticsParams().apply(function () {
    this['source'] = 'home'
  }),
  success: () => { console.log('上报成功') },
  fail: (err) => { console.log(`[${err.errCode}] ${err.errMsg}`) }
})

标准事件

插件提供预置常量，不要硬编码字符串：

import {
  EVENT_LOGIN,
  EVENT_SIGN_UP,
  EVENT_SEARCH,
  EVENT_SHARE,
  EVENT_PURCHASE,
  EVENT_ADD_TO_CART,
  EVENT_VIEW_ITEM,
  EVENT_BEGIN_CHECKOUT,
  EVENT_ADD_PAYMENT_INFO,
  EVENT_VIEW_CART,
  EVENT_REMOVE_FROM_CART,
  EVENT_SCREEN_VIEW,
  EVENT_SELECT_CONTENT,
  EVENT_APP_OPEN,
  PARAM_ITEM_ID,
  PARAM_CURRENCY,
  PARAM_VALUE
} from '@/uni_modules/wen-firebase-analytics'

// 登录
logLogin({
  method: 'email',
  success: () => {}
})

// 搜索
logSearch({ searchTerm: 'art kit', success: () => {} })

// 分享
logShare({ contentType: 'product', itemId: 'SKU_001', method: 'wechat' })

// 注册
logSignUp({ method: 'google' })

参数校验规则

跟踪屏幕

页面自动上报（推荐）

在页面 onPageShow 中调用 trackPageScreen：

import { isInitialized, createAnalyticsParams, trackPageScreen } from '@/uni_modules/wen-firebase-analytics'

(() => {
  if (!isInitialized()) return
  trackPageScreen({
    params: createAnalyticsParams().apply(function () {
      this['source'] = 'auto'
    })
  })
})()

trackPageScreen 会从 getCurrentPages() 读取当前页面路径，作为 screen_name / screen_class 上报 screen_view。

手动指定屏幕信息

const params = createAnalyticsParams()
params['engagement_time_msec'] = 3200
params['previous_screen'] = 'AppLaunch'

logScreenViewOptions({
  screenName: 'ProductDetail',
  screenClass: 'pages/product/detail',
  params: params,
  success: () => {}
})

设置用户 ID

// 简写
setUserId('user_001')

// 带回调（iOS 推荐）
setUserIdOptions({
  userId: 'user_001',
  success: () => {}
})

// 清除用户 ID
setUserId(null)

设置用户属性

// 单个属性
setUserProperty('member_level', 'vip')

setUserPropertyOptions({
  name: 'member_level',
  value: 'vip',
  success: () => {}
})

// 批量设置
setUserProperties({
  properties: createAnalyticsParams().apply(function () {
    this['member_level'] = 'vip'
    this['region'] = 'CN'
  }),
  success: () => {}
})

// 清除属性：value 传 null
setUserProperty('member_level', null)

衡量电子商务

const item = {
  itemId: 'SKU_001',
  itemName: 'Art Kit',
  itemCategory: 'art_supplies',
  itemBrand: 'Caydo',
  price: 29.99,
  quantity: 1
}

// 浏览商品
logViewItem({
  value: 29.99,
  currency: 'USD',
  items: [item],
  success: () => {}
})

// 加购
logAddToCart({ value: 29.99, currency: 'USD', items: [item] })

// 开始结账
logBeginCheckout({ value: 59.98, currency: 'USD', items: [item] })

// 添加支付信息
logAddPaymentInfo({ value: 59.98, currency: 'USD', paymentType: 'credit_card', items: [item] })

// 查看购物车
logViewCart({ value: 59.98, currency: 'USD', items: [item] })

// 移除购物车
logRemoveFromCart({ value: 29.99, currency: 'USD', items: [item] })

// 购买
logPurchase({
  value: 59.98,
  currency: 'USD',
  transactionId: 'T12345',
  tax: 5.0,
  shipping: 3.0,
  coupon: 'SAVE10',
  items: [item],
  success: () => {}
})

设置默认事件参数

后续所有事件会自动附带默认参数：

const defaultParams = createAnalyticsParams()
defaultParams['app_version'] = '2.0.0'
defaultParams['platform'] = 'android'

setDefaultEventParameters(defaultParams)

禁用 / 开启数据采集

// 关闭采集
setAnalyticsCollectionEnabled(false)

// 重新开启
setAnalyticsCollectionEnabled(true)

// 设置会话超时
setSessionTimeoutDuration(30 * 60 * 1000)

Consent 模式（GDPR）

欧盟等地区请配合 Consent 使用：

setConsent({
  analyticsStorage: 'granted',   // 或 'denied'
  adStorage: 'denied',
  adUserData: 'denied',
  adPersonalization: 'denied',
  success: () => {}
})

工具 API

// 获取 App Instance ID
getAppInstanceId({
  success: (res) => {
    console.log('appInstanceId:', res.appInstanceId)
  }
})

// 重置 Analytics 数据（调试用）
resetAnalyticsData()

// 查询状态
if (isInitialized()) {
  const state = getState()
  console.log(state.initialized, state.collectionEnabled)
}

const info = getPluginInfo()
console.log(info.pluginVersion, info.projectId, info.packageName)

UTS 使用说明

事件参数必须用 createAnalyticsParams()

UTS 不支持随意写对象字面量作为事件参数：

const params = createAnalyticsParams()
params['key'] = 'value'       // string
params['count'] = 1           // number
params['enabled'] = true      // boolean

API 两种写法对照

Android 端简写 API 可用；iOS 端带回调请优先使用 *Options。

回调约定

多数 options 支持：

{
  success: (res) => {},    // res 为 { ok: true }
  fail: (err) => {},       // err: { errCode, errMsg, errType? }
  complete: (res) => {}
}

错误处理

logEventOptions({
  name: 'button_click',
  fail: (err) => {
    switch (err.errCode) {
      case 9020001:
        console.error('请先 configure')
        break
      case 9020002:
        console.error('事件名无效')
        break
      default:
        console.error(err.errMsg)
    }
  }
})

DebugView 调试

官方文档：Firebase DebugView

调试前请确认：

• nativeResources 中 Firebase 配置文件已放置且包名 / Bundle ID 匹配
• App.uvue 中已调用 configure({ enabled: true })
• Firebase Console 中选对了对应项目

Android DebugView

准备

1. 手机开启 USB 调试，adb devices 显示 device
2. 安装 debug 包（自定义基座或本地打包），例如：

cd scripts/android-pack
.\build-local-android.ps1
# 只安装不启动：
.\build-local-android.ps1 -NoLaunch

开启调试（关键）

adb shell setprop debug.firebase.analytics.app YOUR_PACKAGE_NAME
adb shell getprop debug.firebase.analytics.app
# 应输出 YOUR_PACKAGE_NAME

手机重启后 setprop 会丢失，需重新执行。

冷启动 App

adb shell am force-stop YOUR_PACKAGE_NAME
adb shell am start -n YOUR_PACKAGE_NAME/.MainActivity

控制台查看

Firebase Console → 你的 Firebase 项目 → Analytics → DebugView

等待 5～30 秒出现设备，在 Demo 页触发事件即可看到实时上报。

Demo 页可测项

插件日志

adb logcat -s wen-firebase-analytics:D FA:I FA-SVC:I

验证调试模式已开启

冷启动瞬间执行：

adb logcat -d -s FA:I | findstr "Faster debug"

必须看到：Faster debug mode event logging enabled

自动抓 logcat（本地打包脚本）

.\build-local-android.ps1 -Logcat -LogcatSeconds 60

关闭调试

adb shell setprop debug.firebase.analytics.app .none.

iOS DebugView（Mac）

通用配置

• nativeResources/ios/Resources/GoogleService-Info.plist 已放置
• Bundle ID 与 manifest、Firebase Console 一致
• App.uvue 在 APP-IOS 条件下已 configure({ enabled: true })

Mac 打包 / 运行（二选一）

A. HBuilderX（Mac）→ 运行 → 运行到手机或模拟器 → iOS 模拟器 / iOS 真机

B. HBuilderX 发行 → 云打包或自定义调试基座 → 用 Xcode 打开生成的 iOS 工程

含 wen-firebase-analytics 时，首次需拉取 CocoaPods（Firebase/Analytics），请用 .xcworkspace 打开（不要用 .xcodeproj）。

开启 DebugView（模拟器 / 真机通用，关键）

1. Xcode → Product → Scheme → Edit Scheme…（或 ⌘<）
2. 左侧选 Run → Arguments 标签
3. Arguments Passed On Launch 点 + 添加：-FIRDebugEnabled
4. 完全杀掉 App（从多任务划掉，不要只回桌面）
5. Xcode 重新 Run（⌘R）冷启动
6. 浏览器打开 Firebase Console → Analytics → DebugView
7. 等 5～30 秒出现设备，触发 configure、logEvent 等

-FIRDebugEnabled 对模拟器和真机同样生效，须写入 Scheme 后冷启动。

Mac + iOS 模拟器

环境： Mac + Xcode（含 iOS Simulator）+ HBuilderX 4.66+

推荐流程：

1. HBuilderX 运行到 iOS 模拟器，等待首次编译完成
2. 在 Finder 打开生成的 iOS 原生工程目录，例如 unpackage/dist/build/app-ios/（以 HBuilderX 实际导出路径为准）
3. 终端进入工程目录，首次安装 Pod：

cd <工程目录>
pod install

4. 双击打开 *.xcworkspace
5. 顶部设备选 iOS Simulator（如 iPhone 16）
6. 按上文添加 -FIRDebugEnabled → ⌘R 冷启动
7. Firebase DebugView 查看实时事件

模拟器日志（终端）：

xcrun simctl spawn booted log stream --level debug \
  --predicate 'eventMessage CONTAINS "Firebase" OR eventMessage CONTAINS "Analytics"'

或打开 macOS Console.app → 左侧选模拟器设备 → 搜索 Firebase。

模拟器注意：

• 模拟器须能访问 Google（公司网络 / 代理可能拦截）
• 插件仅 arm64，Apple Silicon Mac 模拟器可直接用；Intel Mac 旧模拟器可能不兼容
• 每次改 -FIRDebugEnabled 后都要 force quit App 再 Run

Mac + iOS 真机

环境： iPhone（iOS 13+）+ USB 数据线 + Apple 开发者账号（免费或付费均可调试）

推荐流程：

1. iPhone 开启 设置 → 隐私与安全性 → 开发者模式（iOS 16+）
2. HBuilderX 配置 iOS 打包证书 / 描述文件（manifest → iOS 打包配置）
3. HBuilderX 运行到 iOS 真机，或 Xcode 打开 .xcworkspace 后顶部选你的 iPhone
4. 首次安装：iPhone 设置 → 通用 → VPN与设备管理 → 信任开发者证书
5. Xcode Scheme 添加 -FIRDebugEnabled（同模拟器）
6. Xcode 选真机目标 → ⌘R 安装并冷启动
7. Firebase DebugView 中应出现真机设备（名称通常含 iPhone 型号）

真机日志：

• 方式一： Xcode 底部 Debug area（⌘⇧Y）
• 方式二： macOS Console.app → 左侧选已连接 iPhone → 搜索 Firebase / wen-firebase
• 方式三（可选，需 brew install libimobiledevice）：

idevicesyslog | grep -i firebase

真机注意：

• 真机须联网（Wi-Fi 或蜂窝），且能访问 Google / Firebase
• USB 断开不影响已安装 App，但 DebugView 仍须 -FIRDebugEnabled + 冷启动
• 若 HBuilderX 直跑真机无法加启动参数，请改用 Xcode 打开同一工程运行
• 云打包的 Release 包默认不带 -FIRDebugEnabled，DebugView 请用 Xcode 调试运行

关闭 iOS 调试模式

Scheme → Arguments Passed On Launch 删除 -FIRDebugEnabled，或改为添加 -FIRDebugDisabled 后冷启动。

DebugView 无数据排查

• [ ] 未 setprop（Android）或未加 -FIRDebugEnabled（iOS）
• [ ] iOS 用 HBuilderX 直跑但未在 Xcode Scheme 加 -FIRDebugEnabled
• [ ] iOS 真机未信任开发者证书，或开发者模式未开启（iOS 16+）
• [ ] Mac / 模拟器 / 真机网络无法访问 Google（代理、防火墙）
• [ ] 手机重启后 Android setprop 丢失，需重新执行
• [ ] App 未冷启动（仅切后台不够）
• [ ] 未先 configure()
• [ ] setAnalyticsCollectionEnabled(false) 关闭了采集
• [ ] Firebase 项目选错
• [ ] 网络无法访问 Google / Firebase

最短流程

常见问题

Q: 找不到插件方法？
A: 须使用自定义基座或云打包。

Q: iOS 编译报 logEvent 重载相关错误？
A: 带 success / fail 回调时请改用 logEventOptions、logScreenViewOptions 等 *Options API。

Q: Android DebugView 能看到设备但无事件？
A: 确认已 configure、采集开关开启，并触发 logEvent；查看 adb logcat -s wen-firebase-analytics:D。

Q: 修改了插件代码但打包仍用旧代码？
A: 在 HBuilderX 重新导出 app-android / app-ios 资源后再打包。

Q: 需要 FCM 推送？
A: 本插件仅含 Analytics，不含 Firebase Cloud Messaging。

附：API 速查

初始化与状态

事件与屏幕

用户标识

电子商务

logPurchase / logAddToCart / logViewItem / logBeginCheckout / logAddPaymentInfo / logViewCart / logRemoveFromCart

工具

更新记录

• 2.0.0 — Android + iOS 双端、电商事件、屏幕跟踪、Consent、*Options API
• 1.0.0 — 初始版本

完整可运行示例见项目 pages/index/index.uvue。

隐私、权限声明

1. 本插件需要申请的系统权限列表：

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明：

插件集成 Firebase Analytics SDK，数据由 Google Firebase 处理。详情参考 Firebase 隐私说明。请在应用隐私政策中告知用户。

3. 本插件是否包含广告：

无。