HybridAIOne/hybridclaw

GA4

Utilisez cette compétence pour les rapports Google Analytics 4 via l'API Google Analytics Data : sessions, événements clés, revenus, ventilations par source de trafic, ventilations par page de destination, requêtes en séries temporelles, lectures analytiques ad-hoc, tableaux de bord, rapports planifiés, ETL et surveillance.

Périmètre

• exécuter des requêtes runReport GA4 pour une propriété configurée
• traduire des demandes analytiques courantes en anglais en charges utiles Data API révisables
• réviser le JSON de requête GA4 avant l'exécution
• construire des rapports sur les groupes de canaux de source de trafic, les pages de destination, les tendances quotidiennes, les revenus, les sessions, les utilisateurs et les événements clés
• prendre en charge l'OAuth utilisateur délégué et l'authentification par compte de service via le même contrat de gestion du jeton porteur de la passerelle
• conserver la sélection du mode d'authentification dans la configuration du locataire/d'exécution, pas dans la logique d'invite
• mesurer le coût d'exécution de la compétence via les UsageTotals normaux d'HybridClaw

Flux de travail par défaut

1. Commencez par report-plan pour les requêtes en langage naturel, sauf si l'utilisateur a déjà fourni un JSON de requête GA4 Data API.
2. Révisez le JSON de requête généré ou fourni par l'utilisateur avec review-request avant un appel en direct.
3. Pour les appels en direct à l'API GA4 dans HybridClaw, utilisez http_request directement lorsque c'est disponible. Transmettez l'objet httpRequest émis par l'assistant à l'outil.
4. Utilisez l'assistant pour la planification/révision hors ligne et pour l'exécution via proxy de passerelle lorsque http_request n'est pas disponible :

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

5. Traitez toutes les opérations GA4 de cette compétence comme étant en lecture seule. N'essayez pas les mutations de l'API Admin, les modifications d'accès aux propriétés, les modifications d'événements clés ou les modifications de balises.

Contrat d'authentification

La compétence prend en charge deux modes d'authentification sans exposer les tokens ou les clés privées au modèle :

• OAuth utilisateur délégué via un identifiant secret porteur
• échange JWT porteur de compte de service Google via la passerelle

La configuration du locataire décide du mode à utiliser.

Identifiant OAuth utilisateur délégué par défaut :

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

Pour l'OAuth délégué, utilisez le bearerSecretName par défaut : "GOOGLE_WORKSPACE_CLI_TOKEN" ou une route d'authentification URL google-oauth.

Pour l'automatisation par compte de service, stockez le client_email du compte de service et la clé privée PEM sous forme de secrets d'exécution chiffrés. La passerelle lit ces secrets nommés, signe l'assertion JWT côté serveur, l'échange contre un token d'accès Google de courte durée et injecte ce token dans la requête GA4.

Définissez ou mettez à jour ces secrets dans cet ordre :

1. Administration navigateur : ouvrez l'URL admin HybridClaw active se terminant par /admin/secrets.
2. Navigateur /chat ou solution de rechange TUI : /secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>" et /secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY "<pem-private-key>".
3. Solution de rechange console locale :

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

Ne collez pas les tokens d'accès OAuth, les tokens d'actualisation, les clés privées de compte de service ou les fichiers JSON de clé téléchargés dans l'invite. Les identifiants réels restent dans l'environnement d'exécution secret HybridClaw et sont utilisés côté serveur par la passerelle.

Les valeurs par défaut stockées facultatives utilisent le même ordre de configuration : administration navigateur à /admin/secrets, puis /secret set dans le navigateur /chat ou TUI, puis solution de rechange console locale.

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

Pour les travaux de compte de service sans surveillance, définissez les valeurs par défaut d'environnement dans l'environnement d'exécution du locataire :

GA4_SERVICE_ACCOUNT_EMAIL_SECRET=GA4_SERVICE_ACCOUNT_EMAIL
GA4_SERVICE_ACCOUNT_PRIVATE_KEY_SECRET=GA4_SERVICE_ACCOUNT_PRIVATE_KEY

Contrat de commandes

Planifiez un rapport à partir du langage naturel :

python3 skills/ga4/scripts/ga4.py --format json report-plan \
  "Affichez les conversions organiques de la semaine dernière par rapport à la semaine précédente"

Construisez une charge utile http_request pour une requête planifiée ou écrite manuellement :

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

Exécutez un rapport via le chemin de l'assistant passerelle :

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

Utilisez l'authentification par compte de service en choisissant les noms de secrets de compte de service stockés :

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

Révisez le JSON de requête hors ligne :

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

Émettez la charge utile du modèle d'invite de requête analytique :

python3 skills/ga4/scripts/ga4.py --format json prompt-template \
  "Sessions et revenus quotidiens pour les 30 derniers jours"

Exécutez la suite d'évaluation groupée :

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

Règles de travail

• Utilisez des identifiants de propriété GA4 numériques. Acceptez l'entrée properties/<id>, mais normalisez-la avant les appels API.
• Utilisez keyEvents pour les rapports de type conversion, sauf si l'utilisateur demande explicitement une métrique d'événement personnalisée.
• Utilisez sessionDefaultChannelGroup, sessionSourceMedium, landingPagePlusQueryString et date pour les ventilations de production courantes avant d'utiliser des dimensions personnalisées.
• Incluez une limite de lignes. Par défaut à 25 pour les rapports ad-hoc et augmentez uniquement lorsque l'utilisateur demande un export ou un résultat de taille ETL.
• Demandez des éclaircissements lorsque la requête mentionne un trimestre sans année.
• N'ajoutez pas d'écritures API Admin à cette compétence. Une compétence d'administration distincte nécessiterait des niveaux d'approbation explicites et des tests de limites.

Suite d'évaluation

Les scénarios groupés couvrent 25 demandes analytiques représentatives couvrant les sessions, les événements clés, les revenus, les sources de trafic, les pages de destination, les séries temporelles, les comparaisons, le e-commerce, la géographie, l'appareil et les cas de sécurité/clarification.