analytics-insights

Analytics Insights

面向 Google 衡量体系的运营技能——涵盖 GA4、GTM、Search Console 和 BigQuery，可直接通过聊天使用。构建跟踪计划、运行报告、标记转化、审计现有设置，以及查询数据仓库，全程无需离开对话。

不在范围内 — 转交给其他技能

请求	转交给
关键词研究、AI 搜索可见度、完整的 SEO 审计	seo-research（HyperSEO 工具包——在关键词研究方面比 GSC 覆盖更广、功能更丰富）
Google Ads 广告系列表现	google-ads（广告系列级别）——但 GA4 侧的转化归因由此技能负责
Meta / Facebook 广告指标	meta-ads
电子邮件营销计划指标	email-lifecycle（服务提供商侧）

GSC 和 HyperSEO 的搜索表现数据有所重叠。经验法则：在此处使用 GSC 获取用户自己网站的展示次数 / 点击次数 / 排名数据。使用 HyperSEO（位于 seo-research 中）进行关键词研究、竞争对手数据分析和 AI 搜索可见度分析。

要求

• 已安装并连接 Hyper MCP。 https://app.hyperfx.ai/mcp
• 在 https://app.hyperfx.ai/apps 至少连接以下其中一项：
  • Google Analytics — GA4 报告、自定义指标 / 维度、关键事件（转化）管理。
  • Google Tag Manager — 标签 / 触发器 / 变量 / 工作区 / 版本管理。
  • Google Search Console — 搜索表现数据、站点地图、URL 检查。
  • BigQuery — 针对 GA4 导出数据（或任何其他数据集）执行 SQL 查询。

如果 Agent 的工具列表中缺少 google_analytics_ga4_reports_run、google_tag_manager_tags_manage、google_search_console_performance_get 和 bigquery_execute_query，请停止操作，并告知用户启用 Hyper MCP，且至少连接上述一项集成。

如何运行此技能中的工具

此技能中的每个工具都以其规范工具名称命名。使用当前界面提供的调用方式运行：

界面	查找工具	运行工具
MCP 客户端（Claude、Cursor、Codex、ChatGPT）	search("<what you want to do>")，然后运行 describe("<name>")	call("<name>", {...})
Hyper CLI	hyperai search "<what you want to do>"，然后运行 hyperai describe <name>	hyperai call <name> --json '{...}'

如果找不到某个工具，说明其集成尚未连接，或未在工作区中启用：请停止操作，并告知用户需要连接哪个集成。

工具概览

分组	工具
GA4 — 报告	google_analytics_ga4_reports_run, google_analytics_accounts_list, google_analytics_properties_list, google_analytics_properties_get
GA4 — 媒体资源和数据流	google_analytics_ga4_properties_create, google_analytics_properties_update, google_analytics_properties_delete, google_analytics_data_streams_create, google_analytics_data_streams_list, google_analytics_data_streams_get, google_analytics_data_streams_update, google_analytics_data_streams_delete, google_analytics_data_retention_get (只读 — MCP 中没有更新变体), google_analytics_data_collection_acknowledge
GA4 — 关键事件（转化）	google_analytics_key_events_create, google_analytics_key_events_list, google_analytics_key_events_get, google_analytics_key_events_update, google_analytics_key_events_delete
GA4 — 自定义指标 / 维度	google_analytics_custom_metrics_create, google_analytics_custom_metrics_list, google_analytics_custom_metrics_get, google_analytics_custom_metrics_update, google_analytics_custom_metrics_archive, google_analytics_custom_dimensions_create, google_analytics_custom_dimensions_list, google_analytics_custom_dimensions_get, google_analytics_custom_dimensions_update, google_analytics_custom_dimensions_archive
GTM	google_tag_manager_accounts_manage, google_tag_manager_containers_manage, google_tag_manager_workspaces_manage, google_tag_manager_tags_manage, google_tag_manager_triggers_manage, google_tag_manager_variables_manage, google_tag_manager_built_in_variables_manage, google_tag_manager_folders_manage, google_tag_manager_environments_manage, google_tag_manager_versions_manage, google_tag_manager_version_headers_manage, google_tag_manager_user_permissions_manage, google_tag_manager_clients_manage, google_tag_manager_templates_manage, google_tag_manager_transformations_manage, google_tag_manager_zones_manage, google_tag_manager_destinations_manage
Google Search Console	google_search_console_performance_get, google_search_console_sites_list, google_search_console_sitemaps_list, google_search_console_sitemaps_get, google_search_console_sitemaps_submit, google_search_console_sitemaps_delete, google_search_console_urls_submit
BigQuery	bigquery_execute_query, bigquery_insert_rows

关键规则

1. **GA4 媒体资源 ID——参数名因工具而异。**共有三种模式：(a) 报告工具（run_ga4_report、get_property）使用 property_id="properties/123456789"。(b) 创建和列出工具（create_key_event、list_key_events、create_custom_dimension、list_custom_dimensions 等）使用 parent="properties/123456789"。(c) 获取／更新／删除工具针对特定资源操作，使用带完整资源路径的 name=（例如 "properties/123456789/keyEvents/12345"）。这三种模式都需要以某种形式包含 properties/ 前缀——仅传入数字 ID 会静默失败。如有疑问，请查看工具的架构，确认哪个参数标记为 required。
2. 日期范围的起止日期均包含在内。start_date="2026-04-01" 和 end_date="2026-04-30" 会返回 30 天的数据，而不是 29 天。相对日期也是如此：7daysAgo 到 today 是 8 天，而不是 7 天。
3. **GA4 在事件数超过约 1,000 万时会开始抽样。**对于高流量媒体资源，GA4 API 会静默地对结果进行抽样。如果精度至关重要（董事会报告、财务归因），请改用 BigQuery GA4 导出——参见 references/bigquery-ga4-export.md。
4. **GA4 中的转化称为“关键事件”。**GA4 在 2024 年将“转化”更名为“关键事件”。工具也采用了这一名称——使用 google_analytics_key_events_create 将事件标记为转化。不要被旧版文档混淆。
5. **GTM 变更需要工作区、版本和发布。**在工作区中创建的标记／触发器／变量，只有在工作区提交为新版本并发布该版本后才会生效。使用 google_tag_manager_workspaces_manage → 修改 → google_tag_manager_versions_manage（创建）→ 发布。
6. **GSC 数据会延迟 2–3 天。**不要在 GSC 中查询“昨天”的数据并期待有结果——请查询 3 天或更早的数据，以获得稳定的数字。部分指标的 GA4 数据会延迟 24–48 小时。
7. **Apple Mail 隐私保护会抬高 GA4 中来自电子邮件的“互动”会话数。**不要仅凭 GA4 中的数据判断电子邮件带来的互动情况——请与电子邮件服务商自己的点击数据交叉核对。

工作流——选择合适的路径

此技能涵盖四种不同的任务。请先选择任务；不同任务的工作流也不同。

用户想要……	路径	参考资料
一份报告（“我们上个月的表现如何？”）	阶段 R	—
设置跟踪（“我们需要衡量 X”）	阶段 T	references/ga4-tracking-plan.md
审核现有的 GTM／GA4（“为什么转化数据不对劲？”）	阶段 A	references/gtm-audit.md
精确／未抽样／跨数据源分析	阶段 B	references/bigquery-ga4-export.md

Phase R — 运行报告（最常见的路径）

数据仓库选项： 如果工作区已连接分析数据仓库，请发现其中的表和架构，并通过 database_query 查询。读取所选连接的 Warehouse Data Status，并报告其最近一次成功刷新的时间；不要假设缓存每小时更新，也不要假设数据未经抽样。否则，GA4 使用 google_analytics_ga4_reports_run，GSC 使用 google_search_console_performance_get。明确列出账号 ID、日期和指标定义。

1. 确认媒体资源。 google_analytics_accounts_list() → google_analytics_properties_list(filter="parent:accounts/<account_id>")。如果有多个，请让用户选择。在后续对话中保留 properties/<id>。
2. 选择日期范围。 务必确认。“过去 30 天”对应 start_date="30daysAgo"、end_date="yesterday"（避免使用 today——当天数据不完整且不稳定）。
3. 选择指标和维度。 不要在一份报告中塞入 12 个指标 × 6 个维度——结果会难以阅读。选择 2–3 个能回答用户问题的指标，以及 1–2 个有意义的细分维度。
4. 运行报告。

google_analytics_ga4_reports_run(
  property_id="properties/123456789",
  start_date="30daysAgo",
  end_date="yesterday",
  metrics=["activeUsers", "sessions", "conversions", "totalRevenue"],
  dimensions=["sessionDefaultChannelGroup", "deviceCategory"],
)

5. 以表格形式展示结果。 始终将原始数字与解读一并展示。“自然搜索带来了 12,400 次会话（环比增长 18%）”比“自然流量有所增长”更好。
6. 数据指出问题时进行一次后续分析。 如果某项指标表现突出（例如，移动设备上的转化率下降了 40%），运行一份有针对性的后续报告——不要臆测。

常见 GA4 指标和维度

GA4 API 使用驼峰命名。最常用的有：

指标： activeUsers、sessions、screenPageViews、bounceRate、engagementRate、averageSessionDuration、conversions、eventCount、totalRevenue、transactions、purchaseRevenue、userEngagementDuration。

维度： country、city、deviceCategory、operatingSystem、browser、sessionDefaultChannelGroup、sessionSource、sessionMedium、sessionCampaignName、pagePath、eventName、date、hour、landingPage。

如需完整列表，用户可以查阅 GA4 Data API 参考文档。

Phase T — 设置跟踪

GA4 API 可以创建媒体资源、数据流、关键事件、自定义指标和自定义维度——但它无法将 GTM 代码部署到网页中。这一步需要在 GTM 中完成（或在网站中硬编码）。此技能的工作流：

1. 先制定跟踪计划。 定义需要触发哪些事件、在哪里触发，以及哪些事件属于转化（关键事件）。完整模板见 references/ga4-tracking-plan.md。
2. GA4 端设置——创建自定义维度／指标，并标记关键事件：

google_analytics_custom_dimensions_create(
  parent="properties/123456789",
  parameter_name="plan_tier",
  display_name="Plan Tier",
  scope="EVENT",
)

google_analytics_key_events_create(
  parent="properties/123456789",
  event_name="purchase",
  counting_method="ONCE_PER_EVENT",
)

3. GTM 端设置——在工作区中创建／更新代码、触发器和变量，然后创建版本并发布：

google_tag_manager_workspaces_manage(operation="create", account_id="...", container_id="...", name="purchase-tracking-v3")

google_tag_manager_tags_manage(operation="create", workspace_path="...", tag_definition={...})
google_tag_manager_triggers_manage(operation="create", workspace_path="...", trigger_definition={...})
google_tag_manager_variables_manage(operation="create", workspace_path="...", variable_definition={...})

google_tag_manager_versions_manage(operation="create", workspace_path="...", version_name="purchase-tracking-v3")
# then publish via the GTM UI or version operation

4. 验证——参见 Phase A。

阶段 A — 审计（现有设置已损坏或存在疑点）

大多数“我们的分析数据不对”的反馈都属于以下情况之一：

症状	可能原因	如何确认
转化事件未出现在 GA4 中	事件在 GTM 中触发，但未到达 GA4（测量 ID 错误、被同意门控拦截、广告拦截器）	使用 google_analytics_ga4_reports_run 查询过去 7d 的 eventName=purchase → 如果为 0，则检查 GTM
转化次数与实际相差悬殊	事件在每个页面上都触发（而不只是确认页面），或存在重复标签	使用 google_tag_manager_tags_manage(operation="list") 审计 GTM 标签，检查是否有多个标签在同一触发器上触发
GA4 报告的收入与权威数据平台不同	货币不一致、退款处理方式、归因窗口	并排提取两边的数据，查找退款 / 货币相关行
移动流量突然降至约 0	标签只在桌面触发器上触发，或近期 GTM 发布导致移动容器出错	使用 google_tag_manager_versions_manage(operation="list") 查找近期发布，并与之前的版本进行差异比较
GSC 点击数 ≠ GA4 自然搜索会话数	两者本来就不同——定义不同。不要试图精确对账。	这是预期情况；记录下来并继续

详细的审计指南见 references/gtm-audit.md。

阶段 B — BigQuery GA4 导出（精准分析 / 跨来源分析）

适用于未采样数据、自定义归因、将 GA4 与订单数据库 / CRM 数据联接，或进行队列分析的场景。需要在 GA4 管理后台启用 GA4 → BigQuery 导出（自 2023 年起，标准属性可免费使用）。

bigquery_execute_query(
  query="""
    SELECT
      event_date,
      COUNT(DISTINCT user_pseudo_id) AS users,
      COUNTIF(event_name = 'purchase') AS purchases,
      SUM(IF(event_name = 'purchase', ecommerce.purchase_revenue, 0)) AS revenue
    FROM `your-project.analytics_123456789.events_*`
    WHERE _TABLE_SUFFIX BETWEEN '20260401' AND '20260430'
    GROUP BY event_date
    ORDER BY event_date
  """
)

架构、常用查询和完整的归因建模工作流见 references/bigquery-ga4-export.md。

输出标准

• 始终以表格呈现数字，不要写成叙述文字。“12,400 次会话，8.2% 跳出率，1.4% 转化率” → Markdown 表格。
• 始终在报告标题中注明日期范围。“2026 年 4 月 1 日—30 日”——没有日期的数字毫无用处。
• 始终注明报告所对应的属性 / 网站。多属性组织经常因此出问题。
• 注明采样情况。 如果 GA4 返回的 samplesReadCount < samplingSpaceSize，请明确说明。用户需要知道这个数字是否适合用于财务 / 董事会报告。
• 区分“比率指标”和“可求和指标”。 跳出率、互动率、转化率是比率，不能求和——应将其作为单个数字呈现，而不是列总计。

参考工作流

参考资料	阅读时机
references/ga4-tracking-plan.md	设计跟踪方案时——推荐的事件架构、自定义维度 / 指标、关键事件映射、命名约定
references/gtm-audit.md	审计现有 GTM 容器时——查找重复标签、损坏的触发器、未使用的变量、缺失的同意门控
references/bigquery-ga4-export.md	查询 GA4 BigQuery 导出数据时——架构、常用查询（DAU、漏斗、归因、队列、留存）、联接模式