HybridAIOne/hybridclaw

GA4

Use esta skill para relatórios do Google Analytics 4 através da API Data do Google Analytics: sessões, eventos-chave, receita, análises de origem de tráfego, análises de landing page, consultas de séries temporais, leituras analíticas ad-hoc, dashboards, relatórios agendados, ETL e monitoramento.

Escopo

• Executar requisições runReport do GA4 para uma propriedade configurada
• Traduzir solicitações analíticas comuns em inglês para payloads da API Data revisáveis
• Revisar o JSON da requisição GA4 antes da execução
• Construir relatórios de origem de tráfego, grupo de canais, landing page, tendência diária, receita, sessão, usuário e eventos-chave
• Suportar autenticação OAuth com usuário delegado e conta de serviço através do mesmo contrato de handle bearer do gateway
• Manter a seleção do modo de autenticação na configuração do tenant/runtime, não na lógica do prompt
• Medir o custo de execução da skill através do UsageTotals normal do HybridClaw

Fluxo de Trabalho Padrão

1. Comece com report-plan para solicitações em linguagem natural, a menos que o usuário já tenha fornecido um JSON de requisição da API Data do GA4.
2. Revise o JSON da requisição gerado ou fornecido pelo usuário com review-request antes de uma chamada ao vivo.
3. Para chamadas ao vivo da API GA4 dentro do HybridClaw, use http_request diretamente quando disponível. Passe o objeto httpRequest emitido pelo helper para a ferramenta.
4. Use o helper para planejamento/revisão offline e para execução com proxy de gateway quando http_request não estiver disponível:

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

5. Trate todas as operações GA4 nesta skill como somente leitura. Não tente mutações da API Admin, alterações de acesso à propriedade, alterações de eventos-chave ou alterações de tags.

Contrato de Autenticação

A skill suporta dois modos de autenticação sem expor tokens ou chaves privadas ao modelo:

• OAuth com usuário delegado através de um handle secreto bearer
• Troca de JWT bearer de conta de serviço Google através do gateway

A configuração do tenant decide qual modo usar.

Handle OAuth padrão para usuário delegado:

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

Para OAuth delegado, use o bearerSecretName padrão: "GOOGLE_WORKSPACE_CLI_TOKEN" ou uma rota de autenticação URL google-oauth.

Para automação com conta de serviço, armazene o client_email da conta de serviço e a private_key PEM como segredos de runtime criptografados. O gateway lê esses segredos nomeados, assina a afirmação JWT no lado do servidor, troca-a por um token de acesso Google de curta duração e injeta esse token na requisição GA4.

Defina ou atualize esses segredos nesta ordem:

1. Admin do navegador: abra a URL admin ativa do HybridClaw terminando em /admin/secrets.
2. Navegador /chat ou fallback TUI: /secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>" e /secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY "<pem-private-key>".
3. Console local fallback:

hybridclaw secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>"
hybridclaw secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY '<pem-private-key>'

Não cole tokens de acesso OAuth, tokens de atualização, chaves privadas de conta de serviço ou arquivos JSON de chave baixados no prompt. As credenciais reais permanecem no runtime de segredos do HybridClaw e são usadas no lado do servidor pelo gateway.

Os padrões armazenados opcionais usam a mesma ordem de configuração: admin do navegador em /admin/secrets, depois /secret set no navegador /chat ou TUI, depois fallback no console local.

hybridclaw secret set GA4_PROPERTY_ID "<numeric-property-id>"
hybridclaw secret set GA4_BEARER_SECRET_NAME "GOOGLE_WORKSPACE_CLI_TOKEN"

Para jobs não supervisionados com conta de serviço, defina os padrões de ambiente no runtime do tenant:

GA4_SERVICE_ACCOUNT_EMAIL_SECRET=GA4_SERVICE_ACCOUNT_EMAIL
GA4_SERVICE_ACCOUNT_PRIVATE_KEY_SECRET=GA4_SERVICE_ACCOUNT_PRIVATE_KEY

Contrato de Comandos

Planejar um relatório a partir de linguagem natural:

python3 skills/ga4/scripts/ga4.py --format json report-plan \
  "Mostre as conversões orgânicas da semana passada comparadas com a semana anterior"

Construir um payload http_request para uma requisição planejada ou escrita à mão:

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}'

Executar um relatório através do caminho helper do gateway:

python3 skills/ga4/scripts/ga4.py --format json run-report 123456789 \
  --request-json '{"dateRanges":[{"startDate":"7daysAgo","endDate":"yesterday"}],"metrics":[{"name":"sessions"}]}'

Usar autenticação de conta de serviço escolhendo os nomes de segredos da conta de serviço armazenados:

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"}]}'

Revisar o JSON da requisição offline:

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}'

Emitir o payload do modelo de prompt da consulta analítica:

python3 skills/ga4/scripts/ga4.py --format json prompt-template \
  "Sessões e receita diárias dos últimos 30 dias"

Executar o conjunto de avaliação incluído:

python3 skills/ga4/scripts/ga4.py --format json eval-scenarios

Regras de Trabalho

• Use IDs de propriedade GA4 numéricos. Aceite entrada properties/<id>, mas normalize antes das chamadas de API.
• Use keyEvents para relatórios do tipo conversão, a menos que o usuário solicite explicitamente uma métrica de evento personalizada.
• Use sessionDefaultChannelGroup, sessionSourceMedium, landingPagePlusQueryString e date para as análises comuns de produção antes de recorrer a dimensões personalizadas.
• Inclua um limite de linhas. Use o padrão de 25 para relatórios ad-hoc e aumente apenas quando o usuário solicitar um resultado de exportação ou tamanho ETL.
• Peça esclarecimento quando a solicitação mencionar um trimestre sem ano.
• Não adicione gravações da API Admin a esta skill. Uma skill de administração separada precisaria de níveis de aprovação explícitos e testes de limite.

Conjunto de Avaliação

Os cenários incluídos cobrem 25 solicitações analíticas representativas em sessões, eventos-chave, receita, origem de tráfego, landing page, séries temporais, comparações, ecommerce, geográfico, dispositivo e casos de segurança/esclarecimento.