介绍
# GA4 Analytics Toolkit
## 设置
安装依赖项：
```bash 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 的服务账号。
## 快速开始
| 用户说 | 要调用的函数 | |-----------|-----------------| | "Show me site traffic for the last 30 days" | `siteOverview("30d")` | | "What are my top search queries?" | `searchConsoleOverview("30d")` | | "Who's on the site right now?" | `liveSnapshot()` | | "Reindex these URLs" | `reindexUrls(["https://example.com/page1", ...])` | | "Compare this month vs last month" | `compareDateRanges({startDate: "30daysAgo", endDate: "today"}, {startDate: "60daysAgo", endDate: "31daysAgo"})` | | "What pages get the most traffic?" | `contentPerformance("30d")` |
通过从 `scripts/src/index.ts` 导入来执行函数：
```typescript import { siteOverview, searchConsoleOverview } from './scripts/src/index.js';
const overview = await siteOverview('30d'); ```
或直接使用 tsx 运行：
```bash 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 Analytics
| 函数 | 目的 | 收集内容 | |----------|---------|----------------| | `siteOverview(dateRange?)` | 综合站点快照 | 页面浏览量、流量来源、用户群体、事件 | | `trafficAnalysis(dateRange?)` | 流量深度分析 | 来源、按来源/媒介划分的会话、新用户与回访用户 | | `contentPerformance(dateRange?)` | 热门页面分析 | 页面浏览量、落地页、退出页 | | `userBehavior(dateRange?)` | 参与模式 | 用户群体、事件、每日参与指标 | | `compareDateRanges(range1, range2)` | 时间段对比 | 两个日期范围的并排指标 | | `liveSnapshot()` | 实时数据 | 活跃用户、当前页面、当前事件 |
### Search Console
| 函数 | 目的 | 收集内容 | |----------|---------|----------------| | `searchConsoleOverview(dateRange?)` | SEO 快照 | 热门查询、页面、设备、国家/地区细分 | | `keywordAnalysis(dateRange?)` | 关键词深度分析 | 带设备细分的查询 | | `seoPagePerformance(dateRange?)` | 页面 SEO 指标 | 按点击数排序的热门页面、国家/地区细分 |
### Indexing（索引）
| 函数 | 目的 | |----------|---------| | `reindexUrls(urls)` | 请求对多个 URL 重新建立索引 | | `checkIndexStatus(urls)` | 检查 URL 是否已被索引 |
### Utility（实用工具）
| 函数 | 目的 | |----------|---------| | `getAvailableFields()` | 列出所有可用的 GA4 维度和指标 |
### Individual API Functions（单个 API 函数）
如需精细控制，请从 API 模块导入特定函数。有关包含参数、类型和示例的 30 多个 API 函数的完整列表，请参阅 [references/api-reference.md](references/api-reference.md)。
## Date Ranges（日期范围）
所有函数均接受灵活的日期范围格式：
| 格式 | 示例 | 描述 | |--------|---------|-------------| | 简写 | `"7d"`, `"30d"`, `"90d"` | 从 X 天前到今天 | | 显式 | `{startDate: "2024-01-01", endDate: "2024-01-31"}` | 具体日期 | | GA4 相对 | `{startDate: "30daysAgo", endDate: "today"}` | GA4 相对格式 |
默认值为 `"30d"`（可通过 `.env` 中的 `GA4_DEFAULT_DATE_RANGE` 配置）。
## Results Storage（结果存储）
结果自动保存到 `results/`，结构如下：
``` results/ ├── reports/ # GA4 standard reports ├── realtime/ # Real-time snapshots ├── searchconsole/ # Search Console data ├── indexing/ # Indexing API results └── summaries/ # Human-readable markdown summaries ```
### Managing Results（管理结果）
```typescript 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'); ```
## Common Dimensions and Metrics（常用维度和指标）
### Dimensions（维度） `pagePath`, `pageTitle`, `sessionSource`, `sessionMedium`, `country`, `deviceCategory`, `browser`, `date`, `eventName`, `landingPage`, `newVsReturning`
### Metrics（指标） `screenPageViews`, `activeUsers`, `sessions`, `newUsers`, `bounceRate`, `averageSessionDuration`, `engagementRate`, `conversions`, `totalRevenue`, `eventCount`
## Tips（提示）
1. **指定日期范围** — “过去 7 天”或“过去 90 天”提供的洞察与默认的 30 天不同 2. **请求汇总** — 拉取数据后，请求一个包含表格和洞察的 markdown 摘要 3. **对比时间段** — 使用 `compareDateRanges()` 发现趋势（本月与上月对比） 4. **查看实时数据** — `liveSnapshot()` 显示当前谁在网站上 5. **结合 GA4 + Search Console** — 流量数据加上搜索查询数据能呈现全貌