@tofrankie/miniprogram-ga4

v0.0.6

Published

2 months ago

适用于小程序的 Google Analytics 4

0High
0Medium
0Low

frankie_li

google analytics google analytics 4 ga4 ga miniprogram wechat miniprogram 微信小程序支付宝小程序抖音小程序

@tofrankie/miniprogram-ga4

适用于小程序的 Google Analytics 4。

目前已支持：

微信小程序
uni-app 微信小程序

[!NOTE] 理论上支持各小程序平台，其他平台未经验证，欢迎反馈！

快速开始

导入

npm 构建：

$ pnpm add @tofrankie/miniprogram-ga4

文件版：

克隆仓库：git clone https://github.com/tofrankie/miniprogram-ga4.git
安装依赖：pnpm install
构建产物：pnpm build
从 dist 目录获取对应产物文件
将产物文件拷贝至项目

初始化

前往 Google Analytics 后台创建媒体资源，拿到 Measurement ID 和 Sceret。

// app.js

const ga = require('@tofrankie/miniprogram-ga4')
// const ga = require('path/to/your-ga-sdk.js') // 文件版

App({
  onLaunch() {
    ga.config('your_measurement_id', 'your_api_sceret', {
      // 用于数据转发，详见下方 config() 参数说明
      // 数据转发服务器配置参考：https://github.com/rchunping/wxapp-google-analytics/issues/4
      transportUrl: 'https://analytics.example.com',

      // 开启调试日志，建议仅开发模式下开启
      debug: true,

      // 默认为微信小程序，通过此选项可指定其他小程序平台（其他平台未经测试）
      // api: my, // tt, uni, Taro, ...
    })
  },
})

事件上报

const ga = require('@tofrankie/miniprogram-ga4')

// 1️⃣ 上报页面浏览事件（体现在 GA 后台的网页和屏幕）
ga.pageView('首页', 'pages/index/index')

// 2️⃣ 上报通用的 event 事件
ga.event('your_category', 'your_action', 'your_label', 'your_value')

// 3️⃣ 上报任意事件
ga.event('your_event_name', {
  your_event_param1: 'xxx',
  your_event_param2: 'xxx',
  // ...
})

准备工作

在生成新事件或重命名现有事件之前：

确保新名称不是预留名称
与你的团队共同检查所做更改，以免出现事件名称重复的问题
查看事件收集限制

关于事件

简介

用户与网站产生的每一个交互，都可以成为事件，它由事件名称、事件参数组成。在 GA4 中事件类型有：自动收集的事件、增强型衡量事件、推荐事件、自定义事件，其中前两者接入 gtag.js 后自动收集，后两者需要手动上报。

鉴于小程序的特殊形态，它无法使用 gtag.js，需要基于 Measurement Protocol 借助网络请求进行数据上报。

[!IMPORTANT] 本 SDK 仅实现了 gtag.js 完整能力的部分。

固执己见的通用事件

[!NOTE] 基于实际考虑，事件埋点通常会随着业务迭代而变化，很容易产生“过时/废弃”的事件，加之为事件命名本身是一件令人头疼的事情，因此本 SDK 主张将绝大部分事件归入名为 event 的通用事件，如点击页面跳转、点击登录、点击视频播放、支付结果等。如果这个设计不满足你的业务需求，仍然可以通过不同参数形式上报任意事件名称的事件，还可以基于它做一个简单的二次封装。

// 通用事件上报（事件名称为 `event`）
ga.event('category', 'action', 'label', 'value')

// 示例
ga.event('首页', '点击-个人中心')
ga.event('设置页', '点击-切换开关', '开/关')
ga.event('设备列表页', '点击-设备详情', '设备名称')

category: 事件的类型，常以页面为单位
action: 事件的操作，常以事件目标+操作组成
label: 事件的标签，通常是事件目标更具体的描述
value: 事件的值，不作限制，可以是时间、数量等

你仍然可以通过 ga.event() 上报任意事件名称的事件。

ga.event('any_event_name', {
  event_param_1: 'param_value_1',
  event_param_2: 'param_value_2',
  event_param_3: 'param_value_3',
  // ...
})

// 上述通用的 event 事件相当于：
// ga.event('event', { category, action, label, value })

[!IMPORTANT] 若你使用通用事件的设计，应尽早参考下文「自定义事件筛选」章节将 category、action、label、value 设为自定义维度，避免上报的数据无法体现在 GA 报表中。注意，自定义维度和指标是有配额限制的（了解更多），这也是设计通用事件 event 的原因之一。

页面浏览事件 page_view

page_view 事件体现在 GA 后台的网页和屏幕。

由于小程序路径不同于标准的 Web 页面 URL，为了让 GA 后台报表可以正确识别小程序路径，SDK 内部在数据上报时会将小程序路径 pages/index/index 转换为：https://miniprogram.com/pages/index/index 形式。其中 https://miniprogram.com/ 只是 SDK 内部固定前缀，理论上任意域名均可。在后台报表中基于「网页路径和屏幕类」纬度筛选，即可看到小程序路径的统计数据。

// 形式
ga.pageView('页面标题', '页面路径', '来源页面路径')

// 示例（在 Page onLoad 中上报）
ga.pageView('首页') // 自动获取当前路径
ga.pageView('首页', 'pages/index/index') // 指定路径
ga.pageView('设置页', 'pages/setting/setting', 'pages/mine/mine') // 指定当前路径以及来源路径

[!NOTE] 对于页面浏览事件，我们可以通过一些 Hack 方式自动上报。比如，原生微信小程序可以考虑使用文档中未提及但实际可用的 wx.onAppRoute 事件，它可以捕获到 Navigation API 或手势操作等引起的路由变化。由于 wx.onAppRoute 是非公开 API，不排除后续小程序官方会将其移除，请谨慎使用！此处仅提供一种思路，自行承担后果！

示例：

// app.js
import ga from '@tofrankie/miniprogram-ga4'

App({
  onLaunch() {
    ga.config('xxx', 'xxx')

    wx.onAppRoute(res => {
      const pagePath = res.path
      const pageTitle = res.page.window?.navigationBarTitleText ?? pagePath
      ga.pageView(pageTitle, pagePath)
    })
  },
})

异常事件

异常在软件工程领域是很常见的，本 SDK 将其抽象为 exception 事件。

// 形式
ga.exception('描述', 'true/false')

// 示例
ga.exception('这是一个普通错误')
ga.exception('这是一个严重错误', true)

其他事件

基于 GA 推荐事件的电子商务类事件进行梳理，具体看下文 APIs。

常见问题

自定义事件筛选

在事件报告中使用「自定义参数」作为维度进行筛选。你必须先在 GA 后注册自定义参数为「自定义维度」或「自定义指标」，否则无法在报告中使用。注意，自定义维度只会有设定完成当天之后的值，可能要等待数小时后才会有数据，在设定之前的数据可能会显示为 not set。（参考）

GA 预留的自定义参数（用户属性名称）在创建自定义维度时不能使用，比如 cid、uid、user_id 等。因此应该避免使用预留的自定义参数名称，以免后续无法将其设为自定义维度，重构字段则会丢失此前的数据。

APIs

目前 SDK 提供了以下方法，可覆盖常用场景，并提供良好的代码提示以方便使用。

初始化：

ga.config()

常规事件：

ga.event()
ga.pageView()
ga.exception()

电子商务事件：

ga.search()
ga.viewItemList()
ga.viewCart()
ga.viewPromotion()
ga.selectPromotion()
ga.selectItem()
ga.viewItem()
ga.share()
ga.addToWishlist()
ga.addToCart()
ga.removeFromCart()
ga.beginCheckout()
ga.addPaymentInfo()
ga.addShippingInfo()
ga.purchase()
ga.refund()

ga.config()

初始化配置。通常在小程序入口进行配置。

ga.config(measurementId, apiSecret, options)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :------------------- | :------ | :--- | :------ | :------------------------------------------------------------------------------------------- | | measurementId | string | 是 | 无 | Measurement ID（更多） | | apiSecret | string | 是 | 无 | Measurement Protocol API 密钥（更多） | | options.transportUrl | string | 否 | 见说明 | 数据转发服务器 URL，默认使用 https://www.google-analytics.com | | options.eu | boolean | 否 | false | 在欧盟境内收集数据时设为 true，默认使用 https://region1.google-analytics.com | | options.debug | boolean | 否 | false | 开启调试日志 | | options.api | object | 否 | wx | 小程序 API 命名空间对象；理论上支持 my（支付宝小程序）、tt（抖音小程序）等 |

说明：

GA4 默认数据上报域名为 https://www.google-analytics.com。若在欧盟境内收集数据，应设置 options.eu: true，上报到 https://region1.google-analytics.com。
由于上述 GA 域名在国内均未完成备案，因此无法添加到小程序的 request 合法域名中，因此需要你准备一个已备案的域名做数据转发，并配置 options.transportUrl 覆盖默认域名。参考 rchunping/wxapp-google-analytics#4
理论上本 SDK 支持各平台小程序（内部使用到的 API 是各小程序平台通用的），可以在 options.api 传入如 my（支付宝小程序）、tt（抖音小程序）等，但未经测试验证。

ga.pageView()

发送 page_view 事件。

ga.pageView(pageTitle, pageLocation, pageReferrer)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :----------- | :----- | :--- | :----- | :-------------------------- | | pageTitle | string | 是 | 无 | 网页标题，不超过 100 个字符 | | pageLocation | string | 否 | 无 | 网页网址，不超过 420 个字符 | | pageReferrer | string | 否 | 无 | 网页来源，不超过 420 个字符 |

说明：

当 pageLocation 不传参时，将通过 getCurrentPages() 获取当前页面路径进行填充。
为了使得网页位置、网页路径维度自动填充，本 SDK 在上报该事件之前，会将 pageLocation、pageReferrer 的小程序路径前添加上 https://miniprogram.com/（取包名组合而来，不存在的域名），使其成为一个格式正确的网站 URL，让系统自动划分并填充网页位置、网页路径。即 pages/index/index → https://miniprogram.com/pages/index/index

ga.event()

该方法有两种用法：一是发送 event 事件；二是发送任意事件。

ga.event(categoryOrEventName, actionOrEventParams, label, value)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :------------------ | :------------ | :--- | :----- | :---------------------------------------------------- | | categoryOrEventName | string | 是 | 无 | event 事件的类型，常以页面为单位（或事件名称） | | actionOrEventParams | string/object | 是 | 无 | event 事件的操作，常以事件目标+操作组成（或事件参数） | | label | string | 否 | 无 | event 事件的标签，通常是事件目标更具体的描述 | | value | number | 否 | 无 | event 事件的值，不作限制，可以是时间、数量等 |

简单示例：

// 1️⃣ 发送 event 事件
event('category', 'action', 'label', 'value')

// 2️⃣ 发送任意事件
event('any_event_name', {
  event_param_1: 'param_value_1',
  event_param_2: 'param_value_2',
  event_param_3: 'param_value_3',
})

两者传参类型稍有不同，你可以认为 1️⃣ 就是 2️⃣ 的简单封装而已，可兼容原有 UA 的写法。

其中 event 事件参数如下：

| 事件参数名称 | 类型 | 必填 | 默认值 | 描述 | 示例 | | :----------- | :----- | :--- | :----- | :------------------------------- | :--------------- | | category | string | 是 | 无 | 类型，常以页面为单位 | 首页、个人中心页 | | action | string | 是 | 无 | 操作，常以事件目标+操作组成 | 参与活动-点击 | | label | string | 否 | 无 | 标签，事件目标更具体的描述 | 按钮文案等 | | value | number | 否 | 无 | 值，不作限制，可以是时长、数量等 | 1 |

ga.exception()

发送 exception 事件。当网页发生了崩溃、错误等，我们就可以上报此事件。

ga.exception(description, fatal)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :---------- | :------ | :--- | :------ | :------------------------------ | | description | string | 是 | 无 | 异常描述 | | fatal | boolean | 否 | false | 如果异常很严重，则设为 true。 |

ga.search()

发送 search 事件。

ga.search(eventParams)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :---------------------- | :----- | :--- | :----- | :--------- | | eventParams.search_term | string | 是 | 无 | 搜索的字词 |

ga.viewItemList()

发送 view_item_list 事件。当用户查看了商品列表，可上报此事件。

ga.viewItemList(eventParams)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :------------------------- | :----- | :--- | :----- | :--------------- | | eventParams.items | Item[] | 是 | 无 | 与事件相关的商品 | | eventParams.item_list_id | string | 否 | 无 | 所在商品列表 ID | | eventParams.item_list_name | string | 否 | 无 | 所在商品列表名称 |

Item 参数（商品属性，下同）：

| 参数 | 类型 | :------------------ | :----- | :--- | Item.item_id | string | 是 | 无 | Item.item_name | string | 是 | 无 | Item.affiliation | string | 否 | 无 | Item.coupon | string | 否 | 无 | Item.creative_name | string | 否 | 无 | Item.creative_slot | string | 否 | 无 | Item.discount | number | 否 | 无 | Item.index | number | 否 | 无 | Item.item_brand | string | 否 | 无 | Item.item_category | string | 否 | 无 | Item.item_category2 | string | 否 | 无 | Item.item_category3 | string | 否 | 无 | Item.item_category4 | string | 否 | 无 | Item.item_category5 | string | 否 | 无 | Item.item_list_id | string | 否 | 无 | Item.item_list_name | string | 否 | 无 | Item.item_variant | string | 否 | 无 | Item.location_id | string | 否 | 无 | Item.price | number | 否 | 无 | Item.promotion_id | string | 否 | 无 | Item.promotion_name | string | 否 | 无 | Item.quantity | number | 否 | 无 | 必填 | 默认值 | 描述 | | :----- | :--------------------------------------------------------------- | | 商品 ID | | 商品名称 | | 用于指定供应公司或实体店面的商品关联商户 | | 与商品相关的优惠券名称/代码 | | 促销广告素材的名称 | | 与商品相关的促销广告素材投放到的广告位的名称 | | 与商品相关的折扣货币价值 | | 列表中商品的索引/商品在列表中的位置 | | 商品所属品牌 | | 商品所属类别。如果将其用作类别层级或类目的一部分，则为第一个类别 | | 商品的第二个类别层级或其他类目 | | 商品的第三个类别层级或其他类目 | | 商品的第四个类别层级或其他类目 | | 商品的第五个类别层级或其他类目 | | 商品向用户展示时所在列表的 ID | | 商品向用户展示时所在列表的名称 | | 用于提供其他商品详情/选项的商品款式/规格、唯一代码或说明 | | 与商品关联的实际位置（例如实体店） | | 商品的货币价格（以指定的 currency 参数为单位） | | 与商品相关的促销活动的 ID | | 与商品相关的促销活动的名称 | | 商品数量 |

ga.viewCart()

发送 view_cart 事件。当用户查看了购物车，可上报此事件。

ga.viewCart(eventParams)

ga.viewPromotion()

发送 view_promotion 事件。当用户查看了推广活动，可上报此事件。

ga.viewPromotion(eventParams)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :------------------------- | :----- | :--- | :----- | :------------------------------------------- | | eventParams.items | Item[] | 是 | 无 | 与事件相关的商品 | | eventParams.creative_name | string | 否 | 无 | 促销广告素材的名称 | | eventParams.creative_slot | string | 否 | 无 | 与事件相关的促销广告素材投放到的广告位的名称 | | eventParams.promotion_id | string | 否 | 无 | 与事件相关的促销活动的 ID | | eventParams.promotion_name | string | 否 | 无 | 与事件相关的促销活动的名称 |

ga.selectPromotion()

发送 select_promotion 事件。当用户从列表中选择了推广活动，可上报此事件。

ga.selectPromotion(eventParams)

ga.selectItem()

发送 select_item 事件。当用户从列表中选择了商品，可上报此事件。

ga.selectItem(eventParams)

ga.viewItem()

发送 view_item 事件。当用户查看了某些商品，可上报此事件。

ga.viewItem(eventParams)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :------------------- | :----- | :---- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | eventParams.items | Item[] | 是 | 无 | 与事件相关的商品 | | eventParams.currency | string | 否 * | 无 | 与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 CNY）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。 | | eventParams.value | number | 否 * | 无 | 与事件相关的货币价值。如果设置 value，则必须提供 currency。如果设置 value，则必须提供 currency。 |

ga.share()

发送 share 事件。当用户分享了商品，可上报此事件。

ga.share(eventParams)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :----------------------- | :----- | :--- | :----- | :--------------------------- | | eventParams.method | string | 是 | 无 | 共享内容的方法，比如 Twitter | | eventParams.content_type | string | 否 | 无 | 共享内容的类型 | | eventParams.item_id | string | 否 | 无 | 共享内容的 ID |

ga.addToWishlist()

发送 add_to_wishlist 事件。当用户查看了某些商品，可上报此事件。

ga.addToWishlist(eventParams)

ga.addToCart()

发送 add_to_cart 事件。当用户将商品添加到购物车，可上报此事件。

ga.addToCart(eventParams)

ga.removeFromCart()

发送 remove_from_cart 事件。当用户将商品从购物车中移除，可上报此事件。

ga.removeFromCart(eventParams)

ga.beginCheckout()

发送 begin_checkout 事件。当用户已开始结账流程，可上报此事件。

ga.beginCheckout(eventParams)

ga.addPaymentInfo()

发送 add_payment_info 事件。当用户已提交其付款信息，可上报此事件。

ga.addPaymentInfo(eventParams)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :----------------------- | :----- | :---- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | eventParams.items | Item[] | 是 | 无 | 与事件相关的商品 | | eventParams.currency | string | 否 * | 无 | 与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 CNY）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。 | | eventParams.value | number | 否 * | 无 | 与事件相关的货币价值。如果设置 value，则必须提供 currency。如果设置 value，则必须提供 currency。 | | eventParams.coupon | string | 否 | 无 | 与事件相关的优惠券名称/代码 | | eventParams.payment_type | string | 否 | 无 | 选定的付款方式 |

ga.addShipping()

发送 add_shipping_info 事件。当用户已提交其配送信息，可上报此事件。

ga.addShipping(eventParams)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :------------------------ | :----- | :---- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | eventParams.items | Item[] | 是 | 无 | 与事件相关的商品 | | eventParams.currency | string | 否 * | 无 | 与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 CNY）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。 | | eventParams.value | number | 否 * | 无 | 与事件相关的货币价值。如果设置 value，则必须提供 currency。如果设置 value，则必须提供 currency。 | | eventParams.coupon | string | 否 | 无 | 与事件相关的优惠券名称/代码 | | eventParams.shipping_tier | string | 否 | 无 | 用户为所购商品选择的配送级别（例如 Ground、Air 和 Next-day） | | eventParams.payment_type | string | 否 | 无 | 选定的付款方式 |

ga.purchase()

发送 purchase 事件。当用户已购买一件或多件商品，可上报此事件。

ga.purchase(eventParams)

| 参数 | 类型 | 必填 | 默认值 | 描述 | | :------------------------- | :----- | :---- | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | eventParams.items | Item[] | 是 | 无 | 与事件相关的商品 | | eventParams.transaction_id | string | 是 | 无 | 交易的唯一标识符 | | eventParams.currency | string | 否 * | 无 | 与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 CNY）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。 | | eventParams.value | number | 否 * | 无 | 与事件相关的货币价值。如果设置 value，则必须提供 currency。如果设置 value，则必须提供 currency。 | | eventParams.coupon | string | 否 | 无 | 与事件相关的优惠券名称/代码 | | eventParams.shipping | number | 否 | 无 | 与交易相关的运费 | | eventParams.tax | number | 否 | 无 | 与交易相关的税费 |

ga.refund()

发送 refund 事件。当用户退回一件或多件商品，可上报此事件。

ga.refund(eventParams)

已知问题

众所周知，微信小程序对 npm 包支持不友好。在构建 npm 时，它无法识别 dist/index.cjs 文件，会自动追加 .js 变成 dist/index.cjs.js 文件，自然是找不到，因此会抛出错误。

/path/to/your-miniprogram-project/node_modules/@tofrankie/miniprogram-ga4/dist/index.cjs.js: Npm package entry file not found

针对该问题，本包在构建时，会自动将 dist/index.cjs 文件复制为 dist/index.js 文件，main 字段指向 dist/index.js 文件以解决微信开发工具构建 npm 报错问题。

通常情况下，开发体验是没有问题的，因为大多数项目所使用的 Node.js 版本已支持 exports 条件导入字段。在编辑器也能获得完整的类型提示，使用 uni-app 等框架开发接入也是没有问题的。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@tofrankie/miniprogram-ga4

快速开始

导入

初始化

事件上报

准备工作

关于事件

简介

固执己见的通用事件

页面浏览事件 page_view

异常事件

其他事件

常见问题

自定义事件筛选

相关链接

APIs

ga.config()

ga.pageView()

ga.event()

ga.exception()

ga.search()

ga.viewItemList()

ga.viewCart()

ga.viewPromotion()

ga.selectPromotion()

ga.selectItem()

ga.viewItem()

ga.share()

ga.addToWishlist()

ga.addToCart()

ga.removeFromCart()

ga.beginCheckout()

ga.addPaymentInfo()

ga.addShipping()

ga.purchase()

ga.refund()

已知问题