rafa/feadulta
1
0
Fork 0
Code Issues 71 Pull Requests 5 Actions Packages Projects Releases Wiki Activity

GA4 analytics access and reporting assistant workflow #16

New Issue
Open
opened 2026-06-28 19:12:51 +00:00 by rafa · 1 comment
rafa commented 2026-06-28 19:12:51 +00:00
Owner
Copy Link
Copy Source

Labels: area:infra, improvement

Summary

Set up a practical workflow so Codex can help inspect Google Analytics 4 data, extract useful report slices, and explain trends or anomalies in plain language.

The goal is not just raw access to GA4, but a repeatable way to answer questions like:

  • why traffic dropped this week
  • which channels bring traffic but low engagement or low conversion
  • which landing pages perform best or worst
  • how mobile vs desktop mix is changing
  • what campaigns or sources are improving or degrading over time

Desired outcome

Have at least one reliable path for working with GA4 data from this environment:

  1. manual import path
  2. API-based report extraction path
  3. optional BigQuery path for deeper analysis later

Recommended implementation path

Phase 1: manual analysis from exports

Support a low-friction workflow where GA4 reports can be exported as CSV/XLSX and analyzed locally.

Deliverables:

  • documented list of useful GA4 exports to request regularly
  • local analysis script or notebook for CSV-based summarization
  • prompt/playbook for interpreting top channels, landing pages, devices, and conversion trends

Phase 2: GA4 Data API integration

Add a local script or small tool that queries the GA4 Data API directly.

Suggested capabilities:

  • users / sessions / engaged sessions for last 7 / 28 / 90 days
  • source / medium breakdown
  • landing page performance
  • device category mix
  • country / city / browser / OS slices
  • key events / conversions if configured
  • compare current period vs previous period
  • export results to CSV and markdown summaries

Suggested auth options:

  • service account if property access allows it
  • OAuth if direct user-granted access is easier

Likely primary endpoint:

  • GA4 Data API runReport

Optional Phase 3: BigQuery export

If the site needs deeper analytics, evaluate GA4 -> BigQuery export.

Use cases:

  • custom funnels
  • event-level analysis
  • cohorts
  • attribution investigations
  • joining GA4 with content or CRM data

Technical notes

GA4 official references:

Proposed local deliverables

  • scripts/ga4_report.py or equivalent
  • docs/analytics/ga4-setup.md
  • docs/analytics/ga4-report-recipes.md
  • support for .env configuration of GA4_PROPERTY_ID
  • support for export to CSV
  • support for markdown summary output

Questions to resolve

  • Which GA4 property is in scope?
  • Is service-account access possible for that property?
  • Are conversions / key events already configured correctly?
  • Is BigQuery export already enabled?
  • Should the first version live in this repo or in a shared tooling repo?

Acceptance criteria

  • Codex can analyze a manually exported GA4 CSV with a documented workflow
  • Codex can query at least one useful GA4 report directly by API from this machine
  • The setup is documented clearly enough to repeat without rediscovering credentials and steps
  • At least 3 reusable report recipes exist: traffic overview, landing pages, source-medium
**Labels:** area:infra, improvement ## Summary Set up a practical workflow so Codex can help inspect Google Analytics 4 data, extract useful report slices, and explain trends or anomalies in plain language. The goal is not just raw access to GA4, but a repeatable way to answer questions like: - why traffic dropped this week - which channels bring traffic but low engagement or low conversion - which landing pages perform best or worst - how mobile vs desktop mix is changing - what campaigns or sources are improving or degrading over time ## Desired outcome Have at least one reliable path for working with GA4 data from this environment: 1. manual import path 2. API-based report extraction path 3. optional BigQuery path for deeper analysis later ## Recommended implementation path ### Phase 1: manual analysis from exports Support a low-friction workflow where GA4 reports can be exported as CSV/XLSX and analyzed locally. Deliverables: - documented list of useful GA4 exports to request regularly - local analysis script or notebook for CSV-based summarization - prompt/playbook for interpreting top channels, landing pages, devices, and conversion trends ### Phase 2: GA4 Data API integration Add a local script or small tool that queries the GA4 Data API directly. Suggested capabilities: - users / sessions / engaged sessions for last 7 / 28 / 90 days - source / medium breakdown - landing page performance - device category mix - country / city / browser / OS slices - key events / conversions if configured - compare current period vs previous period - export results to CSV and markdown summaries Suggested auth options: - service account if property access allows it - OAuth if direct user-granted access is easier Likely primary endpoint: - GA4 Data API `runReport` ## Optional Phase 3: BigQuery export If the site needs deeper analytics, evaluate GA4 -> BigQuery export. Use cases: - custom funnels - event-level analysis - cohorts - attribution investigations - joining GA4 with content or CRM data ## Technical notes GA4 official references: - Data API overview: https://developers.google.com/analytics/devguides/reporting/data/v1 - `runReport`: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport - BigQuery export: https://support.google.com/analytics/answer/9358801 ## Proposed local deliverables - [ ] `scripts/ga4_report.py` or equivalent - [ ] `docs/analytics/ga4-setup.md` - [ ] `docs/analytics/ga4-report-recipes.md` - [ ] support for `.env` configuration of `GA4_PROPERTY_ID` - [ ] support for export to CSV - [ ] support for markdown summary output ## Questions to resolve - [ ] Which GA4 property is in scope? - [ ] Is service-account access possible for that property? - [ ] Are conversions / key events already configured correctly? - [ ] Is BigQuery export already enabled? - [ ] Should the first version live in this repo or in a shared tooling repo? ## Acceptance criteria - [ ] Codex can analyze a manually exported GA4 CSV with a documented workflow - [ ] Codex can query at least one useful GA4 report directly by API from this machine - [ ] The setup is documented clearly enough to repeat without rediscovering credentials and steps - [ ] At least 3 reusable report recipes exist: traffic overview, landing pages, source-medium
rafa commented 2026-08-08 13:38:24 +00:00
Author
Owner
Copy Link
Copy Source

Incidente 2026-08-08: cron feadulta-ga4-daily con invalid_grant tras renovación reciente

Síntoma: el cron diario llevaba 3 días fallando (06-ago a 08-ago) con
invalid_grant: Token has been expired or revoked, a pesar de que el token
se había renovado el 05-ago (y ese mismo día funcionó bien).

Diagnóstico:

  • Descartado que fuera un problema de ruta/token viejo: el wrapper de Hermes
    (~/.hermes/scripts/feadulta_ga4_daily.py → feadulta_ga4_digest.py)
    apunta correctamente a /mnt/c/Users/Chia/feadulta-git/.secrets/ga4-token.json.
    Reproducido el fallo a mano con --token-path explícito sobre ese mismo
    fichero: mismo error. El token recién renovado murió en <24h.
  • Causa más probable (no confirmada al 100%): el cliente OAuth sigue en modo
    "Testing" en Google Cloud Console. analytics.readonly es un scope
    "sensible", y Google limita/expira agresivamente los refresh tokens de apps
    no verificadas para esos scopes. Si esto se repite en pocos días más,
    hay que publicar/verificar la app OAuth para dejar de depender de
    renovaciones manuales frecuentes.

Renovado: 08-ago 09:33, verificado con un informe real (report --preset summary --days 1).

Gotcha nuevo durante la renovación — reenvío de puertos WSL2 roto:
El flujo --no-browser de ga4_report.py levanta un servidor local en
127.0.0.1:<puerto> dentro de WSL y espera el callback de Google. Esta vez
el reenvío automático localhost de Windows→WSL2 (localhostForwarding=true
en .wslconfig) no funcionó para ese puerto efímero — confirmado con
Test-NetConnection desde Windows (el puerto 3000 de Docker/Gitea sí
respondía, el puerto del callback no). Probar la IP de la VM directamente
tampoco sirvió porque el servidor solo escucha en 127.0.0.1, no en la
interfaz externa.

Workaround que sí funcionó: cuando el navegador de Windows mostró
"localhost refused to connect", la URL de redirect con el code de Google ya
estaba en la barra de direcciones. En vez de reintentar por red, se hizo
curl de esa misma URL desde dentro de WSL contra 127.0.0.1:<puerto>
(loopback puro, sin cruzar la frontera Windows↔VM) — entregó el code al
servidor local a tiempo y completó el intercambio antes de que caducara.

Recomendación para ga4-oauth-renewal.md (skill feadulta-analytics): si
Windows no puede alcanzar el localhost:<puerto> de los pasos 4-6, no
reintentar sin más — copiar la URL de callback que ya llegó al navegador y
hacer curl de ella desde dentro de WSL contra 127.0.0.1:<puerto> antes de
que el code caduque.

## Incidente 2026-08-08: cron `feadulta-ga4-daily` con `invalid_grant` tras renovación reciente **Síntoma:** el cron diario llevaba 3 días fallando (06-ago a 08-ago) con `invalid_grant: Token has been expired or revoked`, a pesar de que el token se había renovado el 05-ago (y ese mismo día funcionó bien). **Diagnóstico:** - Descartado que fuera un problema de ruta/token viejo: el wrapper de Hermes (`~/.hermes/scripts/feadulta_ga4_daily.py` → `feadulta_ga4_digest.py`) apunta correctamente a `/mnt/c/Users/Chia/feadulta-git/.secrets/ga4-token.json`. Reproducido el fallo a mano con `--token-path` explícito sobre ese mismo fichero: mismo error. El token recién renovado murió en <24h. - Causa más probable (no confirmada al 100%): el cliente OAuth sigue en modo **"Testing"** en Google Cloud Console. `analytics.readonly` es un scope "sensible", y Google limita/expira agresivamente los refresh tokens de apps no verificadas para esos scopes. Si esto se repite en pocos días más, hay que **publicar/verificar la app OAuth** para dejar de depender de renovaciones manuales frecuentes. **Renovado:** 08-ago 09:33, verificado con un informe real (`report --preset summary --days 1`). **Gotcha nuevo durante la renovación — reenvío de puertos WSL2 roto:** El flujo `--no-browser` de `ga4_report.py` levanta un servidor local en `127.0.0.1:<puerto>` dentro de WSL y espera el callback de Google. Esta vez el reenvío automático `localhost` de Windows→WSL2 (`localhostForwarding=true` en `.wslconfig`) **no funcionó** para ese puerto efímero — confirmado con `Test-NetConnection` desde Windows (el puerto 3000 de Docker/Gitea sí respondía, el puerto del callback no). Probar la IP de la VM directamente tampoco sirvió porque el servidor solo escucha en `127.0.0.1`, no en la interfaz externa. **Workaround que sí funcionó:** cuando el navegador de Windows mostró "localhost refused to connect", la URL de redirect con el `code` de Google ya estaba en la barra de direcciones. En vez de reintentar por red, se hizo `curl` de esa misma URL **desde dentro de WSL** contra `127.0.0.1:<puerto>` (loopback puro, sin cruzar la frontera Windows↔VM) — entregó el `code` al servidor local a tiempo y completó el intercambio antes de que caducara. **Recomendación para `ga4-oauth-renewal.md`** (skill `feadulta-analytics`): si Windows no puede alcanzar el `localhost:<puerto>` de los pasos 4-6, no reintentar sin más — copiar la URL de callback que ya llegó al navegador y hacer `curl` de ella desde dentro de WSL contra `127.0.0.1:<puerto>` antes de que el `code` caduque.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
inma rafa
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: rafa/feadulta#16
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?