GA4 보고서 (HybridAIOne/hybridclaw)

GA4

이 스킬은 Google Analytics 4 Data API를 통한 GA4 보고(세션, 주요 이벤트, 매출, 트래픽 소스 분석, 랜딩 페이지 분석, 시계열 쿼리, 임시 분석, 대시보드, 예약 보고, ETL 및 모니터링)에 사용합니다.

범위

• 구성된 속성에 대해 GA4 runReport 요청 실행
• 일반 영어 분석 요청을 검토 가능한 Data API 페이로드로 변환
• 실행 전 GA4 요청 JSON 검토
• 트래픽 소스, 채널 그룹, 랜딩 페이지, 일별 추세, 매출, 세션, 사용자 및 주요 이벤트 보고서 작성
• 동일한 게이트웨이 베어러 핸들 계약을 통해 위임된 사용자 OAuth 및 서비스 계정 인증 지원
• 인증 모드 선택을 프롬프트 로직이 아닌 테넌트/런타임 구성에 유지
• 일반 HybridClaw UsageTotals를 통해 스킬 실행 비용 측정

기본 워크플로우

1. 사용자가 이미 GA4 Data API 요청 JSON을 제공하지 않은 경우 자연어 요청에 대해 report-plan으로 시작합니다.
2. 생성된 또는 사용자가 제공한 요청 JSON을 실제 호출 전에 review-request로 검토합니다.
3. HybridClaw 내에서 라이브 GA4 API 호출 시, 가능하면 http_request를 직접 사용합니다. 헬퍼에서 생성된 httpRequest 객체를 도구에 전달합니다.
4. 오프라인 계획/검토 및 http_request를 사용할 수 없는 경우 게이트웨이 프록시 실행을 위해 헬퍼를 사용합니다:

   python3 skills/ga4/scripts/ga4.py ...
   

5. 이 스킬의 모든 GA4 작업은 읽기 전용으로 처리합니다. Admin API 변경, 속성 액세스 변경, 주요 이벤트 변경 또는 태그 변경을 시도하지 마십시오.

인증 계약

이 스킬은 모델에 토큰이나 비공개 키를 노출하지 않고 두 가지 인증 모드를 지원합니다:

• 베어러 비밀 핸들을 통한 위임된 사용자 OAuth
• 게이트웨이를 통한 Google 서비스 계정 JWT 베어러 교환

테넌트 구성이 사용할 모드를 결정합니다.

기본 위임된 사용자 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 요청에 주입합니다.

해당 시크릿을 다음 순서로 설정하거나 업데이트합니다:

1. 브라우저 관리자: /admin/secrets로 끝나는 활성 HybridClaw 관리자 URL을 엽니다.
2. 브라우저 /chat 또는 TUI 대체: /secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>" 및 /secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY "<pem-private-key>".
3. 로컬 콘솔 대체:

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 \
  "지난 주 유기적 전환을 이전 주와 비교하여 보여줘"

계획되거나 직접 작성된 요청에 대한 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 \
  "지난 30일간 일별 세션 및 매출"

번들 평가 제품군 실행:

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개의 대표적인 분석가 요청을 다룹니다.