ga4-events

Name: ga4-events
Author: cognyai

github.com/cognyai营销与增长11158 次安装2 周前更新

代码仓库

关于 ga4-events

面向 GA4 实施人员的事件参考技能，帮助实现、审查和验证 Google Analytics 4 事件。内容涵盖事件参数、代码示例及验证方法。

主要功能

01自动收集与增强型事件
02推荐事件参数
03电商事件示例
04自定义事件命名规则
05事件验证方法
06GTM 与 Measurement Protocol 模式

适用场景

01实现 purchase 事件
02构建电商事件漏斗
03检查事件名称和参数
04在 DebugView 或 BigQuery 中验证数据

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/cognyai/claude-code-marketing-skills --skill ga4-events

安装后在 Claude Code 中输入/ga4-events确认已加载。

详细介绍

GA4 事件实施参考

用于实施 Google Analytics 4 事件的完整参考：自动收集的事件、增强型衡量、推荐事件和自定义事件，包含准确的参数列表、代码示例和验证方法。

完整文档：https://cogny.com/docs/ga4-event-implementation

用法

/ga4-events                          # Show event model overview
/ga4-events purchase                 # Show purchase event parameters and code
/ga4-events ecommerce                # Full e-commerce event funnel reference
/ga4-events enhanced measurement     # Enhanced measurement events list
/ga4-events custom events            # Custom event naming rules and limits
/ga4-events validation               # DebugView, Realtime, and BigQuery checks
/ga4-events gtm                      # GTM dataLayer implementation patterns
/ga4-events measurement protocol     # Server-side Measurement Protocol examples

说明

你是 GA4 事件实施专家。使用此参考帮助用户正确实施、审计和验证 GA4 事件。提供准确、可直接复制粘贴的代码示例。

用户提问时，找到下方相关章节，并提供可执行的答案和可直接使用的代码。如果有可用的 GA4 MCP 工具，请使用它们检查用户实际的媒体资源配置（自定义维度、数据流、转化事件），以提供符合具体情况的建议。

如果用户将特定事件名称或主题作为参数提供，请聚焦于该领域。否则，请概述事件模型。

事件模型概述

GA4 使用基于事件的数据模型，其中一切皆为事件。与 Universal Analytics 的命中类型（网页浏览、事件、交易）不同，GA4 只有一个概念：带参数的事件。

概念	Universal Analytics	GA4
数据模型	基于命中（网页浏览、事件、交易）	基于事件（一切皆为事件）
事件结构	类别 / 操作 / 标签 / 值	事件名称 + 参数（键值对）
会话	由服务器定义，超时为 30 分钟	根据 `session_start` 事件推导
网页浏览	专用命中类型	带有 `page_location` 参数的 `page_view` 事件
电子商务	增强型电子商务插件	内置推荐事件，包含 items 数组
自定义数据	自定义维度/指标（基于索引）	事件参数 + 自定义维度/指标（基于名称）

每个 GA4 事件都有：

事件名称：字符串标识符（例如，page_view、purchase）
事件参数：键值对（例如，page_location、transaction_id）
用户属性：持久的用户属性（例如，membership_tier）

自动收集的事件

无需配置即可自动收集。无法停用。

Web

事件	触发条件	关键参数
`first_visit`	用户首次访问（新 Cookie）	无
`session_start`	新会话开始（超时为 30 分钟）	`ga_session_id`、`ga_session_number`
`page_view`	每次页面加载（或 SPA 中的 `history.pushState`）	`page_location`、`page_title`、`page_referrer`
`user_engagement`	页面处于焦点状态且有互动，持续 1 秒或更长时间	`engagement_time_msec`

移动端（Firebase SDK）

事件	触发条件	关键参数
`first_open`	安装后首次打开应用	`previous_gmp_app_id`、`updated_with_analytics`
`session_start`	新会话开始	`ga_session_id`、`ga_session_number`
`screen_view`	屏幕切换	`firebase_screen`、`firebase_screen_class`、`firebase_screen_id`
`user_engagement`	应用在前台运行 1 秒或更长时间	`engagement_time_msec`
`app_update`	应用更新并启动	`previous_app_version`
`app_remove`	应用被移除（仅限 Android）	无
`os_update`	操作系统更新	`previous_os_version`

自动附加的参数（每个事件）

language、page_location、page_referrer、page_title、screen_resolution、ga_session_id、ga_session_number、engagement_time_msec

增强型衡量事件

在 Admin > Data Streams > Enhanced Measurement 中启用后自动收集。每项都可以单独切换。

事件	触发条件	关键参数
`scroll`	用户滚动超过页面的 90%	`percent_scrolled`（始终为 90）
`click`	点击出站链接	`link_url`、`link_domain`、`link_classes`、`link_id`、`outbound`
`view_search_results`	URL 包含搜索查询参数	`search_term`
`video_start`	YouTube 嵌入视频开始播放	`video_url`、`video_title`、`video_provider`、`video_current_time`、`visible`
`video_progress`	YouTube 视频播放到 10/25/50/75%	同 `video_start`，另加 `video_percent`
`video_complete`	YouTube 视频播放结束	同 `video_start`
`file_download`	点击文件链接（pdf、xls、doc、zip 等）	`file_name`、`file_extension`、`link_url`、`link_text`、`link_domain`
`form_start`	首次与表单交互	`form_id`、`form_name`、`form_destination`
`form_submit`	提交表单	`form_id`、`form_name`、`form_destination`、`form_submit_text`

注意： 视频跟踪仅适用于使用 enablejsapi=1 的 YouTube 嵌入视频。

商品参数参考

items 数组支持每件商品使用以下参数：

参数	类型	描述
`item_id`	STRING	SKU/ID（推荐）
`item_name`	STRING	显示名称（推荐）
`affiliation`	STRING	商店或关联方
`coupon`	STRING	商品级优惠券
`discount`	NUMBER	折扣金额
`index`	NUMBER	列表中的位置
`item_brand`	STRING	品牌名称
`item_category`	STRING	主要类别
`item_category2`-`5`	STRING	类别层级 2-5
`item_list_id`	STRING	列表 ID
`item_list_name`	STRING	列表名称
`item_variant`	STRING	变体（颜色、尺寸）
`location_id`	STRING	实体位置
`price`	NUMBER	商品价格
`currency`	STRING	ISO 4217 代码
`quantity`	NUMBER	数量
`promotion_id`	STRING	促销 ID
`promotion_name`	STRING	促销名称
`creative_name`	STRING	促销创意素材
`creative_slot`	STRING	创意素材版位

item_id 和 item_name 至少需要提供一个。每个事件最多包含 200 件商品。

自定义事件

当自动收集事件、增强型衡量事件或推荐事件都不适用时使用。

命名规则

最多 40 个字符
必须以字母开头
仅允许使用 [a-zA-Z][a-zA-Z0-9_]*
区分大小写 — Add_To_Cart 和 add_to_cart 是不同的事件
不能使用保留前缀：firebase_、google_、ga_
不能使用保留事件名称（例如：first_visit、session_start、app_install、in_app_purchase 等）

限制

限制	数值
每个媒体资源的唯一事件名称数	500
每个事件的参数数	25
参数名称长度	40 个字符
参数值（字符串）	100 个字符
用户属性名称长度	24 个字符
用户属性值（字符串）	36 个字符
每个项目的用户属性数	25

示例

gtag('event', 'newsletter_signup', {
  newsletter_type: 'weekly_digest', signup_location: 'footer'
});

gtag('event', 'feature_used', {
  feature_name: 'export_csv', feature_category: 'data_tools', plan_tier: 'pro'
});

gtag('event', 'article_read', {
  article_id: 'post_12345', article_category: 'technology', read_time_seconds: 245
});

自定义维度和指标

在 Admin > Custom definitions 中注册事件参数或用户属性，以用于报告。

范围

范围	来源	用例
事件级维度	事件参数	页面／操作属性
用户级维度	用户属性	持久用户属性
自定义指标	事件参数（数值）	数值汇总

配额

资源	标准版	Analytics 360
事件级自定义维度	50	125
用户级自定义维度	25	100
自定义指标	50	125

处理时间：标准报告需 24-48 小时（Realtime／DebugView 中会立即显示）。

// Set user properties
gtag('set', 'user_properties', {
  membership_tier: 'gold', signup_date: '2025-01-15'
});

GTM dataLayer 实现

// Custom event
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
  event: 'newsletter_signup',
  newsletter_type: 'weekly_digest',
  signup_location: 'footer'
});

// E-commerce — ALWAYS clear ecommerce first
window.dataLayer.push({ ecommerce: null });
window.dataLayer.push({
  event: 'purchase',
  ecommerce: {
    transaction_id: 'T12345', value: 259.98, currency: 'USD',
    tax: 20.80, shipping: 9.99, coupon: 'SUMMER20',
    items: [{ item_id: 'SKU_123', item_name: 'Trail Runner Pro',
      item_brand: 'RunCo', item_category: 'Shoes', price: 129.99, quantity: 1 }]
  }
});

Measurement Protocol（服务器端）

POST https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET

{
  "client_id": "abc123.def456",
  "events": [{
    "name": "offline_purchase",
    "params": {
      "transaction_id": "OFFLINE_T789",
      "value": 250.00,
      "currency": "USD"
    }
  }]
}

import requests, json

url = 'https://www.google-analytics.com/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET'
payload = {
    'client_id': 'abc123.def456',
    'events': [{'name': 'offline_purchase', 'params': {
        'transaction_id': 'OFFLINE_T789', 'value': 250.00, 'currency': 'USD'
    }}]
}
response = requests.post(url, data=json.dumps(payload))

限制： 不会验证响应（请使用调试端点），client_id 必须与现有 GA4 Cookie 匹配，事件不会显示在 Realtime 中（延迟 30 分钟），无法触发 first_visit／session_start。

验证服务器

POST https://www.google-analytics.com/debug/mp/collect?measurement_id=G-XXXXXXXXXX&api_secret=YOUR_API_SECRET
# Returns validation errors instead of silently accepting

验证和调试

DebugView

启用调试模式，即可在 Admin > DebugView 中近乎实时地查看事件：

gtag('config', 'G-XXXXXXXXXX', { debug_mode: true });
// Or per-event:
gtag('event', 'purchase', { debug_mode: true, transaction_id: 'T12345', value: 99.99, currency: 'USD' });

BigQuery 验证查询

事件量审计：

SELECT event_name, COUNT(*) as event_count, COUNT(DISTINCT user_pseudo_id) as unique_users
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
GROUP BY event_name ORDER BY event_count DESC

缺失购买参数：

SELECT 'missing_transaction_id' as issue, COUNT(*) as count
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND event_name = 'purchase'
  AND (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'transaction_id') IS NULL
UNION ALL
SELECT 'missing_currency', COUNT(*)
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND event_name = 'purchase'
  AND (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'currency') IS NULL

重复交易：

SELECT transaction_id, COUNT(*) as dupes
FROM (
  SELECT (SELECT value.string_value FROM UNNEST(event_params) WHERE key = 'transaction_id') as transaction_id
  FROM `project.analytics_123456789.events_*`
  WHERE _TABLE_SUFFIX BETWEEN FORMAT_DATE('%Y%m%d', DATE_SUB(CURRENT_DATE(), INTERVAL 7 DAY))
                          AND FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
    AND event_name = 'purchase'
)
WHERE transaction_id IS NOT NULL
GROUP BY transaction_id HAVING COUNT(*) > 1
ORDER BY dupes DESC

命名规范审计：

SELECT event_name, COUNT(*) as event_count,
  CASE
    WHEN LENGTH(event_name) > 40 THEN 'exceeds_40_chars'
    WHEN REGEXP_CONTAINS(event_name, r'^(firebase_|google_|ga_)') THEN 'reserved_prefix'
    WHEN NOT REGEXP_CONTAINS(event_name, r'^[a-zA-Z][a-zA-Z0-9_]*$') THEN 'invalid_characters'
    WHEN event_name != LOWER(event_name) THEN 'mixed_case_warning'
    ELSE 'valid'
  END as naming_issue
FROM `project.analytics_123456789.events_*`
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
GROUP BY event_name HAVING naming_issue != 'valid'

参数截断检查：

SELECT event_name, ep.key, MAX(LENGTH(ep.value.string_value)) as max_len,
  COUNTIF(LENGTH(ep.value.string_value) >= 100) as at_limit
FROM `project.analytics_123456789.events_*`, UNNEST(event_params) as ep
WHERE _TABLE_SUFFIX = FORMAT_DATE('%Y%m%d', CURRENT_DATE() - 1)
  AND ep.value.string_value IS NOT NULL
GROUP BY 1, 2 HAVING max_len >= 100

常见问题

区分大小写 — Purchase != purchase。始终使用 snake_case。
字符串会在 100 个字符处截断 — URL 和较长的值会被悄然截断。
自定义维度配额 — 事件级 50 个，用户级 25 个（标准版）。请仔细规划。
重复购买 — 始终包含 transaction_id 以进行去重（72 小时窗口）。
缺少货币 — 如果 value 没有对应的 currency，则会在营收报告中被忽略。
过期的 dataLayer — 在 GTM 中发送电商事件前，始终先推送 { ecommerce: null }。
参数中包含 PII — 不得包含电子邮件地址、电话号码或姓名，否则违反 GA4 服务条款。
动态事件名称 — 会迅速耗尽 500 个名称的限额。请改用参数。

资源

GA4 事件参考： https://developers.google.com/analytics/devguides/collection/ga4/reference/events
推荐事件： https://support.google.com/analytics/answer/9267735
Measurement Protocol： https://developers.google.com/analytics/devguides/collection/protocol/ga4
增强型衡量： https://support.google.com/analytics/answer/9216061
事件限制和配额： https://support.google.com/analytics/answer/9267744
Cogny 完整文档： https://cogny.com/docs/ga4-event-implementation

支持 Markdown

登录后评论

基本信息

作者: cognyai
仓库: cognyai/claude-code-marketing-skills
分类: 营销与增长
安装次数: 58
GitHub Stars: 111

报告问题

事件	参数
`login`	`method`（STRING）
`sign_up`	`method`（STRING）
`share`	`method`（STRING）、`content_type`（STRING）、`item_id`（STRING）
`search`	`search_term`（STRING）
`select_content`	`content_type`（STRING）、`content_id`（STRING）

事件	参数
`earn_virtual_currency`	`virtual_currency_name`（STRING）、`value`（NUMBER）
`spend_virtual_currency`	`virtual_currency_name`（STRING）、`value`（NUMBER）、`item_name`（STRING）
`level_up`	`level`（NUMBER）、`character`（STRING）
`post_score`	`score`（NUMBER，必填）、`level`（NUMBER）、`character`（STRING）
`tutorial_begin`	无
`tutorial_complete`	无
`unlock_achievement`	`achievement_id`（STRING，必填）

ga4-events

关于 ga4-events

主要功能

适用场景

安装

详细介绍

GA4 事件实施参考

用法

说明

事件模型概述

自动收集的事件

Web

移动端（Firebase SDK）

自动附加的参数（每个事件）

增强型衡量事件

推荐事件 — 所有资源

推荐事件 — 电商

view_item_list

select_item

view_item

add_to_cart

remove_from_cart

view_cart

begin_checkout

add_shipping_info

add_payment_info

purchase

refund

推荐事件 — 潜在客户开发

generate_lead

推荐事件 — 游戏