ga4-analytics

GA4 Analytics Toolkit

设置

安装依赖：

cd scripts && npm install

在项目根目录中创建 .env 文件来配置凭据：

GA4_PROPERTY_ID=123456789
[email protected]
GA4_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
SEARCH_CONSOLE_SITE_URL=https://your-domain.com
GA4_DEFAULT_DATE_RANGE=30d

前置条件：启用了 Analytics Data API、Search Console API 和 Indexing API 的 Google Cloud 项目。一个有权访问你的 GA4 媒体资源和 Search Console 的服务账号。

快速开始

用户说	要调用的函数
“显示过去 30 天的网站流量”	siteOverview("30d")
“我的热门搜索查询有哪些？”	searchConsoleOverview("30d")
“当前有哪些用户正在访问网站？”	liveSnapshot()
“重新编入这些 URL 的索引”	reindexUrls(["https://example.com/page1", ...])
“比较本月和上月”	compareDateRanges({startDate: "30daysAgo", endDate: "today"}, {startDate: "60daysAgo", endDate: "31daysAgo"})
“哪些页面的流量最高？”	contentPerformance("30d")

通过从 scripts/src/index.ts 导入来执行函数：

import { siteOverview, searchConsoleOverview } from './scripts/src/index.js';

const overview = await siteOverview('30d');

或者直接使用 tsx 运行：

npx tsx scripts/src/index.ts

工作流模式

每次分析都分为三个阶段：

1. 分析

运行 API 函数。每次调用都会访问 Google API 并返回结构化数据。

2. 自动保存

所有结果都会自动保存为带时间戳的 JSON 文件，存放在 results/{category}/ 中。文件命名格式：YYYYMMDD_HHMMSS__operation__extra_info.json

3. 汇总

分析完成后，读取已保存的 JSON 文件，并在 results/summaries/ 中创建 Markdown 摘要，其中包含数据表格、趋势和建议。

高阶函数

GA4 分析

函数	用途	收集的数据
siteOverview(dateRange?)	全面的站点概览	浏览量、流量来源、人口统计信息、事件
trafficAnalysis(dateRange?)	深入分析流量	来源、按来源／媒介划分的会话数、新访客与回访访客
contentPerformance(dateRange?)	热门页面分析	浏览量、落地页、退出页面
userBehavior(dateRange?)	互动模式	人口统计信息、事件、每日互动指标
compareDateRanges(range1, range2)	时段比较	两个日期范围的并列指标
liveSnapshot()	实时数据	活跃用户、当前页面、当前事件

Search Console

函数	用途	收集的数据
searchConsoleOverview(dateRange?)	SEO 概览	热门查询、页面、设备、国家细分数据
keywordAnalysis(dateRange?)	深入分析关键词	按设备细分的查询
seoPagePerformance(dateRange?)	页面 SEO 指标	按点击次数排序的热门页面、国家细分数据

索引

函数	用途
reindexUrls(urls)	请求为多个 URL 重新编入索引
checkIndexStatus(urls)	检查 URL 是否已编入索引

实用工具

函数	用途
getAvailableFields()	列出所有可用的 GA4 维度和指标

单独的 API 函数

如需更精细的控制，可从 API 模块导入特定函数。完整的 30 多个 API 函数列表（含参数、类型和示例）请参阅 references/api-reference.md。

日期范围

所有函数都接受灵活的日期范围格式：

格式	示例	描述
简写	"7d"、"30d"、"90d"	从指定天数前到今天
明确指定	{startDate: "2024-01-01", endDate: "2024-01-31"}	指定日期
GA4 相对格式	{startDate: "30daysAgo", endDate: "today"}	GA4 相对格式

默认值为 "30d"（可通过 .env 中的 GA4_DEFAULT_DATE_RANGE 配置）。

结果存储

结果会自动保存到 results/，目录结构如下：

results/
├── reports/          # GA4 standard reports
├── realtime/         # Real-time snapshots
├── searchconsole/    # Search Console data
├── indexing/         # Indexing API results
└── summaries/        # Human-readable markdown summaries

管理结果

import { listResults, loadResult, getLatestResult } from './scripts/src/index.js';

// List recent results
const files = listResults('reports', 10);

// Load a specific result
const data = loadResult(files[0]);

// Get most recent result for an operation
const latest = getLatestResult('reports', 'site_overview');

常见维度和指标

维度

pagePath、pageTitle、sessionSource、sessionMedium、country、deviceCategory、browser、date、eventName、landingPage、newVsReturning

指标

screenPageViews、activeUsers、sessions、newUsers、bounceRate、averageSessionDuration、engagementRate、conversions、totalRevenue、eventCount

提示

1. 指定日期范围 — “过去 7 天”和“过去 90 天”与默认的 30 天范围相比，会带来不同的洞察
2. 请求摘要 — 提取数据后，请求生成包含表格和洞察的 Markdown 摘要
3. 比较不同时间段 — 使用 compareDateRanges() 发现趋势（本月与上月）
4. 查看实时数据 — liveSnapshot() 会显示当前正在访问网站的用户
5. 结合 GA4 和 Search Console — 流量数据加上搜索查询数据，才能全面了解情况