Google Analytics 4（GA4）

基础用法

在使用之前，请在 Google Analytics 后台创建媒体资源（详见），接着拿到衡量 ID（详见）和 Measurement Protocol API 密钥（详见）。

import ga from '@ifanrx/uni-stats/ga'

// 初始化，应放在 main.js 进行初始化
ga.config('your_measurement_id', 'your_api_sceret', {
  transportUrl: 'https://analytics.ifanrusercontent.com',
})

// 上报 page_view 事件
ga.pageView('your_page_name', 'your/page/path')

// 上报 event 事件
ga.event('your_category', 'your_action', 'your_label', 'your_value')

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

上报场景值

App.vue

onLaunch(options => {
  uni.ga.scene(options.scene, options.path)
})

上报页面展示

推荐配合路由守卫使用，避免在每个页面都重复编写上报代码

App.vue

import {useUserStore, router} from '@ifanrx/uni-mp'

const userStore = useUserStore()

router.afterEach((to, from) => {
  // 根据项目情况选择哪种上报方式
  uni.ga.event('page', {
    path: to,
    member_id: userStore.user?.memberId,
    trade_union_id: userStore.user?.tradeUnionId,
  })

  // 根据项目情况选择哪种上报方式
  uni.ga.pageView('页面标题', to, from)
})

APIs

addPaymentInfo

▸ addPaymentInfo(eventParams): void

用户已提交其付款信息（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.coupon`	`undefined` \| `string`	与事件相关的优惠券名称/代码
`eventParams.currency`	`undefined` \| `string`	与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 `CNY`）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.payment_type`	`undefined` \| `string`	选定的付款方式
`eventParams.value`	`undefined` \| `number`	与事件相关的货币价值。如果设置 value，则必须提供 currency。

返回值

void

addShippingInfo

▸ addShippingInfo(eventParams): void

用户已提交其配送信息（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.coupon`	`undefined` \| `string`	与事件相关的优惠券名称/代码
`eventParams.currency`	`undefined` \| `string`	与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 `CNY`）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.shipping_tier`	`undefined` \| `string`	用户为所购商品选择的配送级别（例如 Ground、Air 和 Next-day）
`eventParams.value`	`undefined` \| `number`	与事件相关的货币价值。如果设置 value，则必须提供 currency。

返回值

void

addToCart

▸ addToCart(eventParams): void

商品已添加到购物车（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.currency`	`undefined` \| `string`	与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 `CNY`）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.value`	`undefined` \| `number`	与事件相关的货币价值。如果设置 value，则必须提供 currency。

返回值

void

addToWishlist

▸ addToWishlist(eventParams): void

商品已添加到心愿单（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.currency`	`undefined` \| `string`	与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 `CNY`）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.value`	`undefined` \| `number`	与事件相关的货币价值。如果设置 value，则必须提供 currency。

返回值

void

beginCheckout

▸ beginCheckout(eventParams): void

用户已开始结账流程（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.coupon`	`undefined` \| `string`	与事件相关的优惠券名称/代码
`eventParams.currency`	`undefined` \| `string`	与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 `CNY`）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.value`	`undefined` \| `number`	与事件相关的货币价值。如果设置 value，则必须提供 currency。

返回值

void

config

▸ config(measurementId, apiSecret, options?): void

初始化配置

参数

Name	Type	Description
`measurementId`	`string`	衡量 ID（详见）
`apiSecret`	`string`	Measurement Protocol API 密钥（详见）
`options?`	`Object`	配置参数
`options.log`	`undefined` \| `boolean`	是否打印信息，默认为 `false`
`options.transportUrl`	`undefined` \| `string`	数据上报服务器 URL，默认为 `https://www.google-analytics.com`

返回值

void

event

▸ event(categoryOrEventName, actionOrEventParams, label?, value?): void

发送 event 事件（或发送任意事件）

参数

Name	Type	Description
`categoryOrEventName`	`string`	event 事件的类型，常以页面为单位（或事件名称）
`actionOrEventParams`	`string` \| `EventParams`	event 事件的操作，常以事件目标+操作组成（或事件参数）
`label?`	`string`	event 事件的标签，通常是事件目标更具体的描述
`value?`	`number`	event 事件的值，不作限制，可以是时间、数量等

返回值

void

示例

// 用法一：发送 event 事件
event('your_category', 'your_action', 'your_lable', 'your_value')

// 用法二：发送任意事件（用法一就是发送名为 `event` 事件的简单封装，以兼容以往 `ga.event()` 的写法）
event('your_event_name', {your_event_param: 'your_param_value'})

exception

▸ exception(description, fatal?): void

发送 exception 事件

参数

Name	Type	Default value	Description
`description`	`string`	`undefined`	异常描述（不超过 100 个字符）
`fatal?`	`boolean`	`false`	默认为 `false`，如果异常很严重，则设为 `true`。

返回值

void

pageView

▸ pageView(pageTitle, pageLocation?, pageReferrer?): void

发送 page_view 事件

参数

Name	Type	Default value	Description
`pageTitle`	`string`	`undefined`	页面标题（不超过 100 个字符）
`pageLocation?`	`string`	`''`	页面网址（不超过 420 个字符）
`pageReferrer?`	`string`	`''`	页面来源（不超过 420 个字符）

返回值

void

purchase

▸ purchase(eventParams): void

用户已购买一件或多件商品（更多）

参数

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

返回值

void

refund

▸ refund(eventParams): void

用户退回一件或多件商品（更多）

参数

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

返回值

void

removeFromCart

▸ removeFromCart(eventParams): void

商品已从购物车中移除（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.currency`	`undefined` \| `string`	与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 `CNY`）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.value`	`undefined` \| `number`	与事件相关的货币价值。如果设置 value，则必须提供 currency。

返回值

void

scene

▸ scene(scene, path, options?): void

上报场景值

参数

Name	Type	Description
`scene`	`number`	场景值
`path`	`string`	页面路径
`options?`	`Object`	选项
`options.allowScenes`	`undefined` \| `any`[]	需要上报的场景值，不在此列表则不上报，默认为：1007, 1008, 1014, 1035, 1037, 1038, 1047, 1048, 1049, 1053, 1058, 1065, 1107

返回值

void

search

▸ search(eventParams): void

搜索（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.search_term`	`string`	搜索的字词

返回值

void

selectItem

▸ selectItem(eventParams): void

从列表中选择了商品（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.item_list_id`	`undefined` \| `string`	所在商品列表 ID
`eventParams.item_list_name`	`undefined` \| `string`	所在商品列表名称
`eventParams.items`	`Item`[]	与事件相关的商品

返回值

void

selectPromotion

▸ selectPromotion(eventParams): void

从列表中选择了推广活动（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.creative_name`	`undefined` \| `string`	促销广告素材的名称
`eventParams.creative_slot`	`undefined` \| `string`	与事件相关的促销广告素材投放到的广告位的名称
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.promotion_id`	`undefined` \| `string`	与事件相关的促销活动的 ID
`eventParams.promotion_name`	`undefined` \| `string`	与事件相关的促销活动的名称

返回值

void

▸ share(eventParams): void

用户分享了商品（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.content_type`	`undefined` \| `string`	共享内容的类型
`eventParams.item_id`	`undefined` \| `string`	分享商品的 ID
`eventParams.method`	`undefined` \| `string`	共享内容的方法，比如 Twitter

返回值

void

viewCart

▸ viewCart(eventParams): void

查看购物车（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.item_list_id`	`undefined` \| `string`	所在商品列表 ID
`eventParams.item_list_name`	`undefined` \| `string`	所在商品列表名称
`eventParams.items`	`Item`[]	与事件相关的商品

返回值

void

viewItem

▸ viewItem(eventParams): void

用户查看了某些商品（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.currency`	`undefined` \| `string`	与事件相关的商品所用的币种（使用 ISO 4217 格式，比如人民币为 `CNY`）。如果设置 value，则必须提供 currency，这样才能准确计算收入指标。
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.value`	`undefined` \| `number`	与事件相关的货币价值。如果设置 value，则必须提供 currency。如果设置 value，则必须提供 currency。

返回值

void

viewItemList

▸ viewItemList(eventParams): void

查看商品列表（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.item_list_id`	`undefined` \| `string`	所在商品列表 ID
`eventParams.item_list_name`	`undefined` \| `string`	所在商品列表名称
`eventParams.items`	`Item`[]	与事件相关的商品

返回值

void

viewPromotion

▸ viewPromotion(eventParams): void

查看推广活动（更多）

参数

Name	Type	Description
`eventParams`	`Object`	事件参数
`eventParams.creative_name`	`undefined` \| `string`	促销广告素材的名称
`eventParams.creative_slot`	`undefined` \| `string`	与事件相关的促销广告素材投放到的广告位的名称
`eventParams.items`	`Item`[]	与事件相关的商品
`eventParams.promotion_id`	`undefined` \| `string`	与事件相关的促销活动的 ID
`eventParams.promotion_name`	`undefined` \| `string`	与事件相关的促销活动的名称

返回值

void

源码

ga/index.js

Google Analytics 4（GA4） ​

基础用法 ​

上报场景值 ​

上报页面展示 ​

APIs ​

addPaymentInfo ​

参数 ​

返回值 ​

addShippingInfo ​

参数 ​

返回值 ​

addToCart ​

参数 ​

返回值 ​

addToWishlist ​

参数 ​

返回值 ​

beginCheckout ​

参数 ​

返回值 ​

config ​

参数 ​

返回值 ​

event ​

参数 ​

返回值 ​

exception ​

参数 ​

返回值 ​

pageView ​

参数 ​

返回值 ​

purchase ​

参数 ​

返回值 ​

refund ​

参数 ​

返回值 ​

removeFromCart ​

参数 ​

返回值 ​

scene ​

参数 ​

返回值 ​

search ​

参数 ​

返回值 ​

selectItem ​

参数 ​

返回值 ​

selectPromotion ​

参数 ​

返回值 ​

share ​

参数 ​

返回值 ​

viewCart ​

参数 ​

返回值 ​

viewItem ​

参数 ​

返回值 ​

viewItemList ​

参数 ​

返回值 ​

viewPromotion ​

参数 ​

返回值 ​

源码 ​

Google Analytics 4（GA4）

基础用法

上报场景值

上报页面展示

APIs

addPaymentInfo

参数

返回值

addShippingInfo

参数

返回值

addToCart

参数

返回值

addToWishlist

参数

返回值

beginCheckout

参数

返回值

config

参数

返回值

event

参数

返回值

exception

参数

返回值

pageView

参数

返回值

purchase

参数

返回值

refund

参数

返回值

removeFromCart

参数

返回值

scene

参数

返回值

search

参数

返回值

selectItem

参数

返回值

selectPromotion

参数

返回值

share

参数

返回值

viewCart

参数

返回值

viewItem

参数

返回值

viewItemList

参数

返回值

viewPromotion

参数

返回值

源码