giip
SES 商机登记
7分钟阅读

GA 分析报告指南

查看贵组织的 GA4 + Search Console 综合 AI 分析报告(核心内容),以及所选媒体资源/站点的最新指标与历史(辅助信息)。

🔗 打开 GA 分析报告 →

📋 概述

本页面分为两层:

  • 综合报告(核心) — 结合 GA4 与 Search Console 数据的 AI 分析。在右侧历史列表中点击过去的日期,可查看当时的报告;对喜欢的建议点击**“将此建议登记为 Issue”即可直接登记为 giip issue。开启其下方的“生成报告时自动登记 issue”**开关后，此后每次生成新的综合报告都会自动将其建议登记为 giip issue（开启时，当前显示的最新报告若尚未登记，也会立即登记 1 条）。开关关闭时，仍可照旧使用手动登记按钮。
  • 单独的 GA4 / GSC 面板(辅助) — 综合报告下方分别显示各媒体资源的最新指标(KPI 卡片)、最近每日历史表,以及 GSC 热门搜索词。这些面板不再单独生成 AI 分析(上方的综合报告是唯一的最终分析),仅供直接查看原始数字时参考。

✅ 前提条件

  1. GA4 媒体资源与(可选)Search Console 站点需已在您的组织注册 — 见 GA 媒体资源管理、GSC 站点。若任一来源未注册,综合报告会为该项显示“需要设置”的链接。
  2. 采集正在运行,已有数据(见下方“设置采集”)。

🔎 查看报告

  1. 打开页面后综合报告会自动加载。点击右侧历史列表中的日期可切换到当天的报告,点击“返回最新”可回到最新报告。
  2. 若要查看单项指标,请在下方的 GA4/GSC 面板中从下拉框选择已注册的媒体资源/站点(或手动输入)。

📊 指标

指标含义
活跃用户去重活跃用户
会话会话数
页面浏览量屏幕/页面浏览量
跳出率单次交互会话占比(以 % 显示)
转化次数转化事件
平均会话(秒)平均会话时长(秒)
点击次数 / 展示次数 (GSC)Search Console 搜索结果的点击/展示次数
CTR / 平均排名 (GSC)点击率(%) / 平均搜索排名

🤖 AI 如何区分页面

综合报告背后的 AI 会读取每个 URL 路径,自动区分营销/公开页面(访客无需登录即可查看的落地页、博客等)与登录后的产品/管理界面(如仪表盘、仅管理员可见的页面)。后者会被自动排除在“转化入口”相关的批评之外。

如果自动分类与贵组织的实际情况不符(例如刻意将部分公开页面设为无需登录),或希望 AI 更好地体现贵公司自身的服务方向与目标客户,可在 管理员 > Gareport AI 自定义提示词 中输入仅适用于本组织(csn)的附加说明。该说明不会替代全局规则,而是附加在其后。

⚙️ 设置采集 (管理员)

指标由 GIIP 代理/服务器采集,并由 AI 定期综合分析。一次性设置:

  1. 注册 GA4 媒体资源(GA 媒体资源管理)与注册 GSC 站点(GSC 站点) — 两个数据源都需注册,综合报告才完整。
  2. 服务账号密钥 — 创建具有 GA4 读取权限的 Google 服务账号并将媒体资源共享给它。将密钥 JSON 放置于 giipdb mgmt/ga-collector.config.json.sample 中 serviceAccountKeyFile 字段指定的路径(实际路径: giipdb/.secrets/ga-service-account.json,gitignore)。giipfaw 的 ProcessGaCollect 读取此文件并直接调用 Google Data API。
  3. 采集作业 — giipfaw 的定时函数(ProcessGaCollect)通过读取 DB(tGaConfig) 中注册的活动媒体资源列表自动执行采集。无需单独的 PC/代理部署。CQE 指南 和 giipdb docs/30_Specs/CQE_SPECIFICATION.md 仅适用于旧版基于代理的采集方式。
  4. AI 分析(综合) — giipfaw 的 ProcessComboReport 会同时读取 GA4 与 GSC 数据并生成综合报告。若样本量过小(例如访客数不足),报告会一并注明该限制。

采集运行后本页会自动填充。

故障排除

现象原因解决
“暂无报告”综合报告批处理尚未运行确认采集/设置状态,并等待下次运行。
出现“需要设置”链接GA4 媒体资源或 GSC 站点其中之一未注册通过提示的链接(GA 媒体资源管理 / GSC 站点)完成注册。
媒体资源/站点下拉框为空该组织无已注册媒体资源/站点在对应管理页面中注册。
403 / 访问被拒无该媒体资源组织的权限使用您所属的组织。
AI 分析误解了我们的服务结构自动页面分类未覆盖本组织的特殊情况在 Gareport AI 自定义提示词页面中补充说明。

🔌 供 AI 使用的最新数据查询 API

这是一个只读 API,让外部 AI 无需解读界面或登录 Google 账号,仅凭组织标识值(csn)与该组织的密钥(SK),即可一次读取 GIIP 已采集的 GA4/GSC 最新快照与综合报告。它不包含任何重新采集、重新分析或修改设置的功能。

⚠️ 范围限制: 此 API 仅提供最新的一份快照,不包含界面上的历史列表(按日期查看的历史报告)或完整的每日历史表格 — 只能查询最近一次采集/生成的数据。

请求

项目值
方法GET
URLhttps://giipfaw.azurewebsites.net/api/giipGareportSnapshot?csn={CSN}
头部x-api-key: {SK}
参数仅一个正整数 csn

成功响应 (HTTP 200)

{
  "csn": 47,
  "retrievedAt": "2026-09-01T00:00:00Z",
  "sources": {
    "gsc": { "status": "READY", "siteCount": 1 },
    "ga4": { "status": "READY", "propertyCount": 1 },
    "combinedReport": { "status": "READY" }
  },
  "gscSites": [ { "siteUrl": "...", "label": "...", "collectedAt": "...", "data": { } } ],
  "ga4Properties": [ { "propertyId": "...", "label": "...", "collectedAt": "...", "data": { } } ],
  "combinedReport": { "reportId": 0, "generatedAt": "...", "dataSources": "ga+gsc", "missingConfig": null, "language": "zh-CN", "content": "## 1. 当前状况\n最近28天的活跃用户比前28天增长了12%...\n\n## 2. 今日核心瓶颈\n落地页A的跳出率高达78%,阻碍了流量转化...\n\n## 3. 依据\n[MEASURED] ...\n\n## 4. 现在应执行的操作\n对象: /pricing ...\n\n## 5. 暂缓判断\n..." }
}
  • gscSites[].data 原样保存该站点的最新 GSC 原始 JSON(totals、topQueries、topPageQueries、date、range、collectedAt、source)。
  • ga4Properties[].data 是该媒体资源的最新 GA4 原始 JSON 对象,包含以下字段(依据 giipfaw ProcessGaCollect 的采集结构):
    • propertyId、range(采集对应日期)、collectedAt、source
    • metrics: activeUsers、sessions、screenPageViews、bounceRate、conversions、averageSessionDuration
    • topPages: 按浏览量排名前 10 的页面数组 — 每项包含 pagePath、screenPageViews、bounceRate、averageSessionDuration
    • landingPages: 按会话数排名前 10 的落地页数组 — 每项包含 landingPage、sessions、bounceRate
    • events: 按发生次数排名前 20 的事件数组 — 每项包含 eventName、eventCount
    • coreWebVitals: 仅当同时设置了站点 URL 和组织自有的 PageSpeed API 密钥时才有值,否则为 null。有值时,mobile/desktop 各自包含 performanceScore、lcpMs、clsScore、inpMs、fcpMs、ttfbMs
    • periods: 按比较周期(current_3d、current_7d、current_28d、previous_28d、current_90d)分组的 startDate/endDate/metrics(该周期采集失败时为 null)
  • combinedReport 是最新的一份综合报告(若无则为 null)。content 是如上所示由 5 个部分(当前状况/今日核心瓶颈/依据/现在应执行的操作/暂缓判断)组成的 Markdown 字符串 —— 以上示例仅用于展示结构,实际取值因组织与周期而异。
  • gscKeyJson、gaKeyJson、Google 服务账号密钥、SK、AK、数据库连接信息都不会包含在任何响应中。

错误响应

错误正文始终为 { "error": { "code": "...", "message": "..." } } 格式。

条件HTTPerror.code
SK 缺失或无效401UNAUTHENTICATED
SK 无法访问请求的 csn403FORBIDDEN_CSN
csn 缺失、非数字或 ≤ 0400INVALID_CSN
服务器或数据库错误500INTERNAL_ERROR

调用示例 (不含真实密钥,使用环境变量)

export GIIP_API_BASE_URL="https://giipfaw.azurewebsites.net"
export GIIP_CSN="47"
export GIIP_SK="仅在运行时设置"

curl --fail-with-body \
  -H "x-api-key: ${GIIP_SK}" \
  "${GIIP_API_BASE_URL}/api/giipGareportSnapshot?csn=${GIIP_CSN}"

⚠️ 安全: 不要将 SK 放入 URL、Issue、代码仓库、提示词正文或日志。只能从运行时环境变量或密钥存储中传递。

状态值与 AI 应采取的行动

GSC 数据通常延迟两到三天(Google 确定延迟)。

状态含义AI 应采取的行动
READY有活动媒体资源且有最新采集的原始数据将该数据作为事实进行总结
NOT_CONFIGURED该 csn 无活动媒体资源不要臆测,原样报告为“未配置”
NO_DATA有活动媒体资源但无最新采集数据不要臆测,原样报告为“无数据”

AI 调用固定流程

  1. 只查询一次快照。
  2. 先检查 sources 中的每个状态。
  3. 只将 READY 的数据作为事实总结,NOT_CONFIGURED/NO_DATA 不臆测、原样报告。
  4. 将综合报告的 content 视为建议,将 GSC/GA4 data 中的数字视为事实数据,两者区分对待。
  5. 即使需要历史报告或每日历史数据,此 API 也无法查询 —— 只将最新快照视为事实,如收到需要历史数据的请求,应明确告知"此 API 仅提供最新数据"。

版本: 1.5 最后更新: 2026-09-18 变更记录: giip 2709 —— 为综合报告新增“生成报告时自动登记 issue”开关（开关关闭时保留手动登记按钮）。 / giip #2068 —— 明确说明该 API 仅提供最新的一份快照,补充 ga4Properties[].data 的实测字段结构,并扩充了 combinedReport.content 示例。 源文件: giipv3/public/help/gareport.zh-CN.md

相关指南

实时安全代理自主AI的主动威胁监控和审计智能体循环与任务分发基于 GitHub Issue 通过智能体循环执行任务的便捷方法任务状态流转指南智能体分发系统中任务状态变化的方式
← PreviousGA 媒体资源管理Back to Overview知识中心