ga4

Files (3)

• SKILL.md
• scenarios.json · evals/
• ga4.py · scripts/

SKILL.md (first lines)

# GA4

Use this skill for Google Analytics 4 reporting through the Google Analytics
Data API: sessions, key events, revenue, traffic-source breakdowns,
landing-page breakdowns, time-series queries, ad-hoc analyst reads, dashboards,
scheduled reporting, ETL, and monitoring.

## Scope

- run GA4 `runReport` requests for a configured property
- translate common English analyst requests into reviewable Data API payloads
- review GA4 request JSON before execution
- build traffic-source, channel-group, landing-page, daily trend, revenue,
  session, user, and key-event reports
- support delegated-user OAuth and service-account auth through the same
  gateway bearer handle contract
- keep auth-mode selection in tenant/runtime config, not in prompt logic
- measure skill run cost through normal HybridClaw `UsageTotals`

## Default Workflow

1. Start with `report-plan` for natural-language requests unless the user
   already supplied a GA4 Data API request JSON.
2. Review generated or user-supplied request JSON with `review-request` before
   a live call.
3. For live GA4 API calls inside HybridClaw, use `http_request` directly when
   available. Pass the emitted `httpRequest` object from the helper to the tool.
4. Use the helper for offline planning/review and for gateway-proxied execution
   when `http_request` is unavailable:
   ```bash
   python3 skills/ga4/scripts/ga4.py ...
   ```
5. Treat all GA4 operations in this skill as read-only. Do not attempt Admin
   API mutations, property access changes, key-event changes, or tag changes.

## Auth Contract

The skill supports two auth modes without exposing tokens or private keys to
the model:

- delegated-user OAuth through a bearer secret handle
- Google service-account JWT bearer exchange through the gateway

Tenant config decides which mode to use.

Default delegated-user OAuth handle:

```bash
hybridclaw auth login google \
  --client-id "<google-oauth-client-id>" \
  --client-secret "<google-oauth-client-secret>" \
  --account you@example.com \
  --scopes "https://www.googleapis.com/auth/analytics.readonly"

hybridclaw auth status google
```

For delegated OAuth, use the default `bearerSecretName:
"GOOGLE_WORKSPACE_CLI_TOKEN"` or a `google-oauth` URL auth route.

For service-account automation, store the service-account `client_email` and
PEM `private_key` as encrypted runtime secrets. The gateway reads those named
secrets, signs the JWT assertion server-side, exchanges it for a short-lived
Google access token, and injects that token into the GA4 request.

Set or update those secrets in this order:

1. Browser admin: open the active HybridClaw admin URL ending in `/admin/secrets`.
2. Browser `/chat` or TUI fallback:
   `/secret set GA4_SERVICE_ACCOUNT_EMAIL "<client-email>"` and
   `/secret set GA4_SERVICE_ACCOUNT_PRIVATE_KEY "<pem-private-key>"`.
3. Local console fallback:

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

Do not paste OAuth access tokens, refresh tokens, service-account private keys,
or downloaded JSON key files into the prompt. Real credentials stay in the
HybridClaw secret runtime and are used server-side by the gateway.

Optional stored defaults use the same setup order: browser admin at
`/admin/secrets`, then `/secret set` in browser `/chat` or
TUI, then local console fallback.

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

For unattended service-account jobs, set environment defaults in the tenant
runtime:

```bash
GA4_SERVICE_ACCOUNT_EMAIL_SECRET=GA4_SERVICE_ACCOUNT_EMAIL
GA4_SERVICE_ACCOUNT_PRIVATE_KEY_SECRET=GA4_SERVICE_ACCOUNT_PRIVATE_KEY
```

## Command Contract

Plan a report from natural language:

```bash
python3 skills/ga4/scripts/ga4.py --format json report-plan \
  "Show me last week's organic conversions vs the prior week"
```

Build an `http_request` payload for a planned or hand-written request:

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

Run a report through the gateway helper path:

```bash
python3 skills/ga4/scripts/ga4.py --format json run-report 123456789 \

From HybridAIOne/hybridclaw, MIT.

More from HybridAIOne/hybridclaw