# GA4 API setup for feadulta

This document describes the simplest practical path for querying Google Analytics 4 from this repo.

> **Where the code lives vs where it runs (2026-07-31).** This script used to live only in the
> separate `feadulta-git` checkout, which points at the *archived* Gitea and never made it into
> this repo. The canonical copy is now here, in `rafa/feadulta` on `gitea.feadulta.com`.
> The **runtime environment stays in `/mnt/c/Users/Chia/feadulta-git`**: `.venv/` and, above all,
> `.secrets/` (OAuth client + cached token) are gitignored and were never versioned anywhere.
> That is why the commands below still use absolute paths into `feadulta-git` — the paths are
> correct, the code is just no longer only there.

## Current known identifier

The site is tagged with GA4 measurement ID:

- `G-6RT9ZRS4LW`

Important:

- the GA4 **measurement ID** (`G-...`) is **not** the same as the GA4 **property ID**
- the Data API `runReport` endpoint needs the **property ID**
- the script added in this repo can resolve the property automatically if the authenticated Google user has access to the property

Official references:

- Data API `runReport`: https://developers.google.com/analytics/devguides/reporting/data/v1/rest/v1beta/properties/runReport
- Admin API overview: https://developers.google.com/analytics/devguides/config/admin/v1
- Where to find the measurement ID in GA4: https://support.google.com/analytics/answer/9304153

## Recommended auth model

Use **OAuth desktop app credentials** for a Google user that already has access to the GA4 property.

Why this is the easiest first step:

- no need to create a service account and grant property access separately
- no need to know the property ID upfront
- the script can authenticate as you and search the accessible properties for the matching `G-...`

## One-time Google Cloud setup

1. Open Google Cloud Console.
2. Create or reuse a project.
3. Enable:
   - Google Analytics Data API
   - Google Analytics Admin API
4. Create an OAuth client of type `Desktop app`.
5. Download the client secrets JSON file.

Suggested local path:

- `/mnt/c/Users/Chia/feadulta-git/.secrets/ga4-oauth-client.json`

Do not commit it.

## Local Python environment

This repo is set up to use a local virtualenv so the host Python installation does not need to be modified.

Create it once:

```bash
python3 -m venv /mnt/c/Users/Chia/feadulta-git/.venv
```

Install the required packages inside that environment:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python -m pip install google-auth google-auth-oauthlib requests
```

## Environment variables

You can configure the script with environment variables:

```bash
export GA4_CLIENT_SECRETS_PATH=/mnt/c/Users/Chia/feadulta-git/.secrets/ga4-oauth-client.json
export GA4_TOKEN_PATH=/mnt/c/Users/Chia/feadulta-git/.secrets/ga4-token.json
export GA4_MEASUREMENT_ID=G-6RT9ZRS4LW
export GA4_PROPERTY_ID=508378818
```

If `GA4_PROPERTY_ID` is omitted, the script can try to resolve it from `GA4_MEASUREMENT_ID`.

## First run

Authenticate and resolve the property:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --measurement-id G-6RT9ZRS4LW resolve-property
```

If the local environment cannot open a browser directly, use manual mode:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --measurement-id G-6RT9ZRS4LW --no-browser resolve-property
```

This prints a Google authorization URL. Open it in the browser, sign in with a Google user that has access to the GA4 property, and complete the redirect back to the `localhost` callback URL shown in the command output.

On successful first run, the script stores a reusable token locally at:

- `/mnt/c/Users/Chia/feadulta-git/.secrets/ga4-token.json`

Current known resolved property:

- measurement ID: `G-6RT9ZRS4LW`
- property ID: `508378818`
- property name: `https://feadulta.com`
- account name: `Portal feadulta.com`
- stream name: `https://www.feadulta.com/`

## Example reports

Traffic overview:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset traffic --days 28
```

Top content:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset content --days 28 --limit 25
```

Landing pages:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset landing-pages --days 28 --limit 25
```

Traffic by source / medium:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset source-medium --days 28 --limit 25
```

Device mix:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset device --days 28 --limit 25
```

Export to CSV:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset content --days 28 --csv /tmp/ga4-content.csv
```

## Splitting the live site from the static archive (`--host`)

This single property (`G-6RT9ZRS4LW`) collects several hostnames at once: the live
WordPress (`www.feadulta.com`), the frozen Joomla archive (`antiguo.feadulta.com`,
which carries the same GA tag inside its captured HTML), plus leftovers like
`wp-nuevo.feadulta.com`. **Any report without a host filter mixes them and means
nothing.**

Which hostnames are actually reporting:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset hosts --days 28
```

Only the live site:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset content --host www.feadulta.com --days 28 --limit 25
```

Only the archive:

```bash
/mnt/c/Users/Chia/feadulta-git/.venv/bin/python scripts/ga4_report.py --property-id 508378818 report --preset content --host antiguo.feadulta.com --days 28 --limit 25
```

`--host` takes a comma-separated list (exact match, case-insensitive) and combines
with `--page-path-regex` as an AND group. `--host-not` negates it.

## Practical future access

For future use, the shortest path is:

1. Confirm these files still exist locally:
   - `/mnt/c/Users/Chia/feadulta-git/.secrets/ga4-oauth-client.json`
   - `/mnt/c/Users/Chia/feadulta-git/.secrets/ga4-token.json`
   - `/mnt/c/Users/Chia/feadulta-git/.venv/`
2. Run reports directly with `--property-id 508378818`.
3. Only rerun `resolve-property` if the token was deleted or the Google access changed.
4. If the token expires, the script should refresh it automatically when possible.

## About WordPress logs

If the question is “what content is being seen?”, GA4 is usually the better first tool because it gives:

- page-level views
- landing pages
- traffic sources
- device mix
- trends over time

WordPress itself does **not** log page views by default in a way that is useful for editorial analysis.

If GA4 turns out to be incomplete or unreliable, the next fallback is usually:

1. web server access logs
2. reverse proxy logs
3. plugin-specific event logging if the site has a dedicated analytics plugin

In this repo, there is no obvious WordPress analytics plugin configuration under `wordpress/wp-content/mu-plugins/`, so GA4 or server logs are the most likely useful sources.

## Useful questions this script should answer

- Which pages got the most views in the last 28 days?
- Which landing pages attract the most traffic?
- Which sources or source/medium pairs bring traffic?
- Is mobile traffic increasing or decreasing?
- Did traffic fall because fewer users arrived, or because fewer pages were viewed per session?