GA4
使用此技能進行 Google Analytics 4 報告,透過 Google Analytics Data API:工作階段、關鍵事件、收入、流量來源細分、到達頁面細分、時間序列查詢、臨機分析讀取、儀表板、排程報告、ETL 和監控。
範圍
- 為已設定的資源執行 GA4
runReport請求 - 將常見的英文分析師請求轉換為可審查的 Data API 負載
- 在執行前審查 GA4 請求 JSON
- 建立流量來源、管道群組、到達頁面、每日趨勢、收入、工作階段、使用者和關鍵事件報告
- 透過相同的閘道 Bearer 代碼合約,支援委派用戶 OAuth 和服務帳戶驗證
- 將驗證模式選擇保留在租戶/執行階段設定中,而非提示詞邏輯
- 透過正常的 HybridClaw
UsageTotals測量技能執行成本
預設工作流程
- 除非使用者已提供 GA4 Data API 請求 JSON,否則先從
report-plan開始處理自然語言請求。 - 在進行即時呼叫之前,使用
review-request審查產生的或使用者提供的請求 JSON。 - 對於 HybridClaw 內部的即時 GA4 API 呼叫,在可用時直接使用
http_request。將輔助工具產生的httpRequest物件傳遞給該工具。 - 當
http_request不可用時,使用輔助工具進行離線規劃/審查以及透過閘道代理的執行:python3 skills/ga4/scripts/ga4.py ... - 將此技能中的所有 GA4 操作視為唯讀。請勿嘗試 Admin API 變更、資源存取權限變更、關鍵事件變更或標籤變更。
驗證合約
此技能支援兩種驗證模式,且不會向模型暴露令牌或私鑰:
- 透過 Bearer 金鑰代碼的委派用戶 OAuth
- 透過閘道的 Google 服務帳戶 JWT Bearer 交換
租戶設定決定使用哪種模式。
預設委派用戶 OAuth 代碼:
hybridclaw auth login google \
--client-id "<google-oauth-client-id>" \
--client-secret "<google-oauth-client-secret>" \
--account [email protected] \
--scopes "https://www.googleapis.com/auth/analytics.readonly"
hybridclaw auth status google
對於委派 OAuth,使用預設的 bearerSecretName: "GOOGLE_WORKSPACE_CLI_TOKEN" 或 google-oauth URL 驗證路由。
對於服務帳戶自動化,將服務帳戶的 client_email 和 PEM private_key 儲存為加密的執行階段密鑰。閘道會讀取這些命名密鑰,在伺服器端簽署 JWT 斷言,將其交換為短期的 Google 存取令牌,並將該令牌注入 GA4 請求。
按此順序設定或更新這些密鑰:
- 瀏覽器管理員:開啟作用中 HybridClaw 管理員 URL,網址結尾為
/admin/secrets。 - 瀏覽器
/chat或 TUI 備用方案:/secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>"和/secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY "<pem-private-key>"。 - 本地主控台備用方案:
hybridclaw secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>"
hybridclaw secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY '<pem-private-key>'
請勿將 OAuth 存取令牌、重新整理令牌、服務帳戶私鑰或下載的 JSON 金鑰檔案貼到提示詞中。實際憑證保留在 HybridClaw 密鑰執行階段中,並由閘道在伺服器端使用。
可選的儲存預設值使用相同的設定順序:瀏覽器管理員位於 /admin/secrets,然後在瀏覽器 /chat 或 TUI 中使用 /secret set,最後是本地主控台備用方案。
hybridclaw secret set GA4_PROPERTY_ID "<numeric-property-id>"
hybridclaw secret set GA4_BEARER_SECRET_NAME "GOOGLE_WORKSPACE_CLI_TOKEN"
對於無人值守的服務帳戶作業,在租戶執行階段中設定環境預設值:
GA4_SERVICE_ACCOUNT_EMAIL_SECRET=GA4_SERVICE_ACCOUNT_EMAIL
GA4_SERVICE_ACCOUNT_PRIVATE_KEY_SECRET=GA4_SERVICE_ACCOUNT_PRIVATE_KEY
指令合約
從自然語言規劃報告:
python3 skills/ga4/scripts/ga4.py --format json report-plan \
"Show me last week's organic conversions vs the prior week"
為已規劃或手寫的請求建立 http_request 負載:
python3 skills/ga4/scripts/ga4.py --format json http-request 123456789 \
--request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"date"}],"metrics":[{"name":"sessions"}],"limit":25}'
透過閘道輔助路徑執行報告:
python3 skills/ga4/scripts/ga4.py --format json run-report 123456789 \
--request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"metrics":[{"name":"sessions"}]}'
透過選擇儲存的服務帳戶密鑰名稱來使用服務帳戶驗證:
python3 skills/ga4/scripts/ga4.py --format json http-request 123456789 \
--google-service-account-email-secret GA4_SERVICE_ACCOUNT_EMAIL \
--google-service-account-private-key-secret GA4_SERVICE_ACCOUNT_PRIVATE_KEY \
--request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"metrics":[{"name":"sessions"}]}'
離線審查請求 JSON:
python3 skills/ga4/scripts/ga4.py --format json review-request \
'{"dateRanges":[{"startDate":"30daysAgo","endDate":"yesterday"}],"dimensions":[{"name":"landingPagePlusQueryString"}],"metrics":[{"name":"sessions"},{"name":"totalRevenue"}],"limit":25}'
產出分析師查詢提示詞範本負載:
python3 skills/ga4/scripts/ga4.py --format json prompt-template \
"Daily sessions and revenue for the last 30 days"
執行內建評估套件:
python3 skills/ga4/scripts/ga4.py --format json eval-scenarios
運作規則
- 使用數值型 GA4 資源 ID。接受
properties/<id>輸入,但在 API 呼叫前將其標準化。 - 除非使用者明確要求自訂事件指標,否則使用
keyEvents進行轉換類型的報告。 - 在引入自訂維度之前,優先使用
sessionDefaultChannelGroup、sessionSourceMedium、landingPagePlusQueryString和date進行常見的生產細分。 - 包含行數限制。臨機報告預設為 25,僅在使用者要求匯出或 ETL 大小的結果時才增加。
- 當請求提到某個季度但未指定年份時,要求使用者澄清。
- 請勿在此技能中新增 Admin API 寫入操作。單獨的管理技能需要明確的核准層級和邊界測試。
評估套件
內建情境涵蓋 25 個代表性的分析師請求,範圍包括工作階段、關鍵事件、收入、流量來源、到達頁面、時間序列、比較、電子商務、地理、裝置以及安全性/澄清案例。