GA 分析報告指南
檢視貴組織的 GA4 + Search Console 綜合 AI 分析報告(核心內容),以及所選資源/網站的最新指標與歷史(輔助資訊)。
📋 概述
本頁面分為兩層:
- 綜合報告(核心) — 結合 GA4 與 Search Console 資料的 AI 分析。在右側歷史清單中點擊過去的日期,可檢視當時的報告;對喜歡的建議點擊**「將此建議登記為 Issue」即可直接登記為 giip issue。開啟其下方的「產生報告時自動登記 issue」**開關後,日後每次產生新的綜合報告都會自動將其建議登記為 giip issue(開啟時,目前顯示的最新報告若尚未登記,也會立即登記 1 筆)。開關關閉時,仍可照舊使用手動登記按鈕。
- 個別 GA4 / GSC 面板(輔助) — 綜合報告下方分別顯示各資源的最新指標(KPI 卡片)、最近每日歷史表,以及 GSC 熱門搜尋字詞。這些面板不再單獨產生 AI 分析(上方的綜合報告是唯一的最終分析),僅供直接檢視原始數字時參考。
✅ 前提條件
- GA4 資源與(可選)Search Console 網站需已在您的組織註冊 — 見 GA 資源管理、GSC 網站。若任一來源未註冊,綜合報告會為該項顯示「需要設定」的連結。
- 採集正在執行,已有資料(見下方「設定採集」)。
🔎 檢視報告
- 開啟頁面後綜合報告會自動載入。點擊右側歷史清單中的日期可切換至當天的報告,點擊「返回最新」可回到最新報告。
- 若要檢視單項指標,請在下方的 GA4/GSC 面板中從下拉選單選擇已註冊的資源/網站(或手動輸入)。
📊 指標
| 指標 | 意義 |
|---|---|
| 活躍使用者 | 去重活躍使用者 |
| 工作階段 | 工作階段數 |
| 頁面瀏覽量 | 螢幕/頁面瀏覽量 |
| 跳出率 | 單次互動工作階段占比(以 % 顯示) |
| 轉換次數 | 轉換事件 |
| 平均工作階段(秒) | 平均工作階段時長(秒) |
| 點擊次數 / 曝光次數 (GSC) | Search Console 搜尋結果的點擊/曝光次數 |
| CTR / 平均排名 (GSC) | 點擊率(%) / 平均搜尋排名 |
🤖 AI 如何區分頁面
綜合報告背後的 AI 會讀取每個 URL 路徑,自動區分行銷/公開頁面(訪客無需登入即可檢視的到達頁、部落格等)與登入後的產品/管理畫面(如儀表板、僅管理員可見的頁面)。後者會自動排除在「轉換入口」相關的評論之外。
如果自動分類與貴組織的實際情況不符(例如刻意將部分公開頁面設為無需登入),或希望 AI 更能反映貴公司自身的服務方向與目標客戶,可在 管理員 > Gareport AI 自訂提示詞 中輸入僅適用於本組織(csn)的附加說明。該說明不會取代全域規則,而是附加在其後。
🔍 AEO/GEO 就緒度
依 8 個項目檢查搜尋引擎、回答引擎與生成式 AI 是否容易引用我們的頁面結構,並給出每個頁面的分數。此面板顯示在綜合報告下方。
檢查的 8 個項目
| 項目 | 看什麼 |
|---|---|
| 結構化 FAQ | 問題與回答是否以機器可讀的形式寫在頁面裡 |
| 作者 | 撰寫者個人或組織的名稱,以及可查證的網址是否都已寫明 |
| 組織 | 發布頁面的組織名稱,以及代表網址或標誌是否已寫明 |
| 日期 | 發布日與更新日是否以機器可讀的形式存在,且彼此不矛盾 |
| 來源 | 本文是否有指向外部網站的依據連結,且這些來源是否沒有只集中在一處 |
| 可比較資訊 | 本文是否有真正能比較的表格(有表頭列,且比較對象在兩個以上) |
| 數值與依據 | 本文裡的每個數值是否都附上期間、來源或依據連結 |
| 實體關係 | 這個頁面所談的對象是否與外部對應的識別碼建立了關聯 |
每個項目判定為達標(2 分)/ 部分達標(1 分)/ 缺少(0 分),無法判定的項目則自分數中排除。
怎麼讀這個分數
- 一定要和
已判定 n/8一起看。 只看分數是不夠的:分數的意思是「在已判定的項目中拿到了可得分數的百分之幾」,而分母是幾個只寫在旁邊的已判定 n/8裡。 - 這不是整站分數。 測量對象是搜尋流量較高的頁面(每次最多 20 個),其餘頁面不測量。因此我們也不會把頁面分數取平均當作「本站分數」。
–(自分數中排除)與0(缺少)不同。0是「已讀取頁面且確實沒有這個要素」這項事實,–則表示「沒有判定」。把讀不到的頁面算成 0 分,等於報告一個不存在的缺陷,所以我們不這麼做。- 各項目的分母可能不同。 本文完全沒有數值的頁面,「數值與依據」這一項本來就以不適用排除。所以即使測量了 10 個頁面,「數值與依據」的已判定頁面也可能只有 6 個。這正是依項目彙總的表格不設百分比欄的原因。
- 等級(A/B/C、好與壞)、與同業平均的比較、百分位都不提供。 唯一的比較是同一頁面自己過去的測量值。
測量每週一次
測量每週日執行一次。剛修改完內容不會立即反映,分數從下一次測量開始變化。面板上方的測量日期告訴你這些值是什麼時候測的;若該日期已超過 14 天,面板會同時提示「之後的內容變更未納入」。
AEO 不是分數,而是以報告敘述的形式呈現
對問題的直接回答、明確的事實、服務定義、術語定義、案例 — 這 5 項不產生分數。 而是由 AI 在綜合報告本文中判斷,並帶上 [EXPERT_HYPOTHESIS](專家假設)標記,寫成「應該在哪個頁面的哪個小標題下補什麼」。
不給分數的原因是:這不是重測也會給出同一答案的測量。 8 個項目是機器照著頁面結構直接數出來的,重複執行結果相同。而「這一段是否直接回答了問題」屬於解讀,若每次執行答案都變,分數走勢就失去意義。因此 8 項計分、5 項敘述。報告中原樣引用測量值的地方會帶 [MEASURED](實測)標記。
看不到分數時
| 現象 | 原因 | 處理 |
|---|---|---|
| 「尚無 AEO/GEO 測量資料」 | 該組織還從未執行過每週一次的測量 | 確認已註冊 GSC 網站或 GA4 資源,然後等待下一次測量。 |
| 某個頁面不在清單裡 | 測量對象只有搜尋流量較高的頁面 — 其餘頁面不測量 | 等該頁面累積了搜尋流量,之後的測量就會將它納入。 |
| 分數欄顯示「未能測量 — 無分數」 | 未能讀取頁面 — 網址不存在(4xx)、擷取失敗,或 robots.txt 禁止採集 | 查看「擷取」欄顯示的原因,檢查網址、連線與 robots.txt。 |
| 分數欄顯示「判定項目不足 — 無分數」 | 頁面讀到了,但 8 項中能判定的不足 6 項 | 表示結構化資料為空,或未能確定本文區域。僅靠 JavaScript 繪製的頁面,其結構化資料我們讀不到。 |
項目欄顯示 – | 該頁面本來就沒有這一項的測量對象(例如本文數值為 0 個) | 這不是缺陷,它會自分數的分母中排除。 |
⚙️ 設定採集 (管理員)
指標由 GIIP 代理/伺服器採集,並由 AI 定期綜合分析。一次性設定:
- 註冊 GA4 資源(GA 資源管理)與註冊 GSC 網站(GSC 網站) — 兩個資料來源都需註冊,綜合報告才完整。
- 服務帳號金鑰 — 建立具有 GA4 讀取權限的 Google 服務帳號並將資源共用給它。將金鑰 JSON 放置於 giipdb
mgmt/ga-collector.config.json.sample中serviceAccountKeyFile欄位指定的路徑(實際路徑:giipdb/.secrets/ga-service-account.json,gitignore)。giipfaw 的ProcessGaCollect讀取此檔案並直接呼叫 Google Data API。 - 採集作業 — giipfaw 的計時器函式(
ProcessGaCollect)透過讀取 DB(tGaConfig) 中註冊的活動資源清單自動執行採集。無需單獨的 PC/代理部署。CQE 指南 和 giipdbdocs/30_Specs/CQE_SPECIFICATION.md僅適用於舊版基於代理的採集方式。 - AI 分析(綜合) — giipfaw 的
ProcessComboReport會同時讀取 GA4 與 GSC 資料並產生綜合報告。若樣本數過小(例如訪客數不足),報告會一併註明此限制。
採集執行後本頁會自動填入。
疑難排解
| 症狀 | 原因 | 解決 |
|---|---|---|
| 「尚無報告」 | 綜合報告批次尚未執行 | 確認採集/設定狀態,並等待下次執行。 |
| 出現「需要設定」連結 | GA4 資源或 GSC 網站其中之一未註冊 | 透過提示的連結(GA 資源管理 / GSC 網站)完成註冊。 |
| 資源/網站下拉選單為空 | 該組織無已註冊資源/網站 | 在對應管理頁面中註冊。 |
| 403 / 存取被拒 | 無該資源組織的權限 | 使用您所屬的組織。 |
| AI 分析誤解了我們的服務結構 | 自動頁面分類未涵蓋本組織的特殊情況 | 在 Gareport AI 自訂提示詞頁面中補充說明。 |
🔌 供 AI 使用的最新資料查詢 API
這是一個唯讀 API,讓外部 AI 無需解讀畫面或登入 Google 帳號,僅憑組織識別值(csn)與該組織的密鑰(SK),即可一次讀取 GIIP 已採集的 GA4/GSC 最新快照與綜合報告。它不包含任何重新採集、重新分析或修改設定的功能。
⚠️ 範圍限制: 此 API 僅提供最新的一份快照,不包含畫面上的歷史清單(按日期查看的歷史報告)或完整的每日歷史表格 — 只能查詢最近一次採集/產生的資料。若需要按日期查看的歷史報告或每日歷史資料,請改用下方的 「供 AI 使用的歷史(按日期多筆)查詢 API」(giipGareportHistory) 一節。
請求
| 項目 | 值 |
|---|---|
| 方法 | GET |
| URL | https://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-TW", "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 物件,包含以下欄位(依據 giipfawProcessGaCollect的採集結構):propertyId、range(採集對應日期)、collectedAt、sourcemetrics:activeUsers、sessions、screenPageViews、bounceRate、conversions、averageSessionDurationtopPages: 按瀏覽量排名前 10 的頁面陣列 — 每項包含pagePath、screenPageViews、bounceRate、averageSessionDurationlandingPages: 按工作階段數排名前 10 的到達頁陣列 — 每項包含landingPage、sessions、bounceRateevents: 按發生次數排名前 20 的事件陣列 — 每項包含eventName、eventCountcoreWebVitals: 僅當同時設定了網站 URL 與組織自有的 PageSpeed API 金鑰時才有值,否則為null。有值時,mobile/desktop各自包含performanceScore、lcpMs、clsScore、inpMs、fcpMs、ttfbMsperiods: 依比較區間(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": "..." } } 格式。
| 條件 | HTTP | error.code |
|---|---|---|
| SK 缺失或無效 | 401 | UNAUTHENTICATED |
| SK 無法存取請求的 csn | 403 | FORBIDDEN_CSN |
csn 缺失、非數字或 ≤ 0 | 400 | INVALID_CSN |
| 伺服器或資料庫錯誤 | 500 | INTERNAL_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 呼叫固定流程
- 只查詢一次快照。
- 先檢查
sources中的每個狀態。 - 只將
READY的資料作為事實摘要,NOT_CONFIGURED/NO_DATA不臆測、原樣報告。 - 將綜合報告的
content視為建議,將 GSC/GA4data中的數字視為事實資料,兩者區分對待。 - 若需要過去的報告或每日歷史資料,請勿使用此快照 API,改用下方的 歷史(按日期多筆)查詢 API(giipGareportHistory) —— 快照負責「目前的最新狀態」,歷史 API 負責「期間內按日期的變化」。
🔌 供 AI 使用的歷史(按日期多筆)查詢 API
與上方快照 API 只給「最新 1 筆」不同,這個唯讀歷史 API會回傳期間(from/to)內的綜合報告與 GA4/GSC 每日原始資料多筆(分頁)。當要以日期為單位判定「到昨天為止採集是否正常」時,就使用這個 API。與快照 API 一樣,它沒有重新採集、重新分析或修改設定的功能。
請求
| 項目 | 值 |
|---|---|
| 方法 | GET |
| URL | https://giipfaw.azurewebsites.net/api/giipGareportHistory?csn={CSN}&from={YYYY-MM-DD}&to={YYYY-MM-DD}&page={N}&pageSize={N} |
| 標頭 | x-api-key: {SK} |
| 參數 | 必填 | 意義 |
|---|---|---|
csn | 必填 | 組織編號(正整數) |
from | 選填 | 查詢起始日(YYYY-MM-DD)。省略時為 to 往前 30 天 |
to | 選填 | 查詢結束日(YYYY-MM-DD,含當日)。省略時為今日(UTC) |
page | 選填 | 從 1 開始的頁碼。省略時為 1 |
pageSize | 選填 | 每頁筆數。省略時為 30,最大 100(超過時限制為 100) |
page/pageSize會各自獨立套用於綜合報告歷史與各 GA4 資源/GSC 網站的每日歷史(各來源各自的視窗)。每個來源會各自回傳自己的totalCount/hasMore(或combinedReportPagination)中繼資料。
成功回應 (HTTP 200)
{
"csn": 47,
"retrievedAt": "2026-10-30T00:00:00Z",
"from": "2026-09-30",
"to": "2026-10-30",
"page": 1,
"pageSize": 30,
"combinedReportPagination": { "page": 1, "pageSize": 30, "totalCount": 12, "hasMore": false },
"combinedReportHistory": [
{ "reportId": 0, "generatedAt": "2026-10-30T00:00:00Z", "dataSources": "ga+gsc", "missingConfig": null, "language": "ko", "content": "## 1. 현재 상황 ...\n## 2. 오늘의 핵심 병목 ...\n## 3. 근거 ...\n## 4. 지금 실행할 작업 ...\n## 5. 보류할 판단 ..." }
],
"gscSites": [
{ "siteUrl": "...", "label": "...", "totalCount": 30, "page": 1, "pageSize": 30, "dailyHistory": [ { "collectedAt": "2026-10-29T00:00:00Z", "data": { } } ] }
],
"ga4Properties": [
{ "propertyId": "...", "label": "...", "totalCount": 30, "page": 1, "pageSize": 30, "dailyHistory": [ { "collectedAt": "2026-10-29T00:00:00Z", "data": { } } ] }
]
}
combinedReportHistory[]以最新順序多筆回傳期間內的綜合報告。每個content與快照 API 相同,是由 5 個部分(目前狀況/今日核心瓶頸/依據/現在應執行的動作/暫緩判斷)組成的 Markdown 字串 —— 以上範例僅用於說明結構,實際數值因組織與區間而異。gscSites[].dailyHistory[].data/ga4Properties[].dailyHistory[].data是該日期的 GSC/GA4 原始採集 JSON,與快照 API 的data欄位為相同結構(GA4 含metrics、topPages、landingPages、events、coreWebVitals、periods等,GSC 含totals、topQueries、topPageQueries、date、range等)。差別僅在於不是「最新 1 筆」,而是「期間內按日期的多筆」。collectedAt是該每日紀錄的採集時刻(UTC)。是否以日期為單位完成採集,由此值與data中的date/range判定。gscKeyJson、gaKeyJson、Google 服務帳號金鑰、SK、AK、資料庫連線資訊都不會包含在任何回應中。
錯誤回應
錯誤內文始終為 { "error": { "code": "...", "message": "..." } } 格式(與快照 API 相同)。
| 條件 | HTTP | error.code |
|---|---|---|
| SK 缺失或無效 | 401 | UNAUTHENTICATED |
| SK 無法存取請求的 csn | 403 | FORBIDDEN_CSN |
csn 缺失、非數字或 ≤ 0 | 400 | INVALID_CSN |
from/to 格式錯誤或 from > to | 400 | INVALID_DATE_RANGE |
page 非整數 | 400 | INVALID_PAGE |
pageSize 非整數 | 400 | INVALID_PAGE_SIZE |
| 伺服器或資料庫錯誤 | 500 | INTERNAL_ERROR |
呼叫範例 (不含真實密鑰,使用環境變數)
export GIIP_API_BASE_URL="https://giipfaw.azurewebsites.net"
export GIIP_CSN="47"
export GIIP_SK="僅在執行時設定"
# 最近 7 天歷史(以日期為單位確認到昨天為止是否已採集時)
curl --fail-with-body \
-H "x-api-key: ${GIIP_SK}" \
"${GIIP_API_BASE_URL}/api/giipGareportHistory?csn=${GIIP_CSN}&from=2026-10-23&to=2026-10-29&page=1&pageSize=30"
⚠️ 安全: 不要將 SK 放入 URL、Issue、程式碼儲存庫、提示詞內文或日誌。只能從執行環境變數或密鑰儲存中傳遞。
AI 呼叫固定流程 (採集缺漏判定)
- 設定判定期間: 若要檢視「到昨天為止是否已採集」,將
to設為昨天的日期、from設為足夠的過去(例如 7 天前)進行查詢。 - 逐來源確認日期: 在
ga4Properties[]、gscSites[]各項的dailyHistory[]中,確認collectedAt(或data中的date/range)是否包含昨天的日期。 - 缺漏判定: 若已註冊活動資源/網站(該陣列中有項目),卻沒有任何昨天日期的每日歷史,則報告為「採集缺漏」。但 GSC 通常延遲 2~3 天(Google 確定延遲)屬正常,因此 GSC 的缺漏判定須將此延遲納入考量(GA4 幾乎無延遲)。
- 掃遍所有 csn: 對帳號可存取的每個 csn 重複 1~3。管理員 SK 可存取所有 csn,一般 SK 只能存取自己的 csn(其他 csn 的請求回傳 403)。
- 區分事實/建議:
combinedReportHistory[].content(綜合報告)是建議,dailyHistory[].data中的數字是事實資料 —— 採集缺漏判定務必以後者(事實資料)的日期有無為準。
版本: 1.7
最後更新: 2026-10-30
變更紀錄: giip 4313 —— 新增「供 AI 使用的歷史(按日期多筆)查詢 API」(giipGareportHistory) 一節(含以日期範圍判定採集缺漏的流程),並將快照 API 一節中「無法查詢歷史」的敘述更新為參照歷史 API。 / giip #4023 —— 新增「AEO/GEO 就緒度」章節(檢查的 8 個項目、把分數和 已判定 n/8 一起讀、–(排除)與 0(缺少)的差別、每週一次的測量、AEO 為何以報告敘述而非分數呈現、看不到分數時怎麼辦)。 / giip 2709 —— 為綜合報告新增「產生報告時自動登記 issue」開關(開關關閉時保留手動登記按鈕)。 / giip #2068 —— 明確說明該 API 僅提供最新的一份快照,補充 ga4Properties[].data 的實測欄位結構,並擴充了 combinedReport.content 範例。
原始檔: giipv3/public/help/gareport.zh-TW.md