# Connecting your GA4 properties (one-time, ~10 minutes)

The dashboard reads every site through **one service account** — a robot Google identity you grant read-only access to each GA4 property. This works even when your properties live under different Google accounts: you never share passwords, you just add the robot's email as a viewer wherever you (or your client) have admin rights.

## Step 1 — Create a Google Cloud project

1. Go to https://console.cloud.google.com (any Google account — use your agency one).
2. Top bar → project picker → **New project**. Name it e.g. `lav-pulse`. Create and select it.

## Step 2 — Enable the GA4 Data API

1. In the search bar, find **"Google Analytics Data API"**.
2. Click **Enable**.

## Step 3 — Create the service account + key

1. Menu → **IAM & Admin → Service accounts** → **Create service account**.
2. Name: `lav-pulse-reader`. Skip the optional role/access steps — it needs no project roles.
3. Open the created account → **Keys** tab → **Add key → Create new key → JSON** → Create.
4. A JSON file downloads. Save it in the project folder as `ga4-service-account.json`.
   **Treat it like a password** — don't commit it to git (it's already in `.gitignore`).
5. Copy the service account's email address — it looks like
   `lav-pulse-reader@lav-pulse.iam.gserviceaccount.com`.

## Step 4 — Grant it access to each GA4 property

For **each** website's GA4 property (repeat per property, under whichever Google account owns it):

1. Open https://analytics.google.com → select the property → **Admin** (gear, bottom left).
2. Property column → **Property access management**.
3. **+ → Add users** → paste the service account email.
4. Role: **Viewer**. Untick "Notify by email". Add.

If a client owns the property, they can do this step themselves — you just send them the email address to add.

## Step 5 — Collect property IDs and fill in sites.config.json

1. For each property: **Admin → Property settings** → copy the numeric **Property ID** (e.g. `421337555`).
2. Edit `sites.config.json` — one entry per site:

```json
{
  "sites": [
    { "id": "client-a", "name": "Client A Ltd", "url": "https://clienta.co.uk", "propertyId": "421337555" },
    { "id": "client-b", "name": "Client B Shop", "url": "https://clientb.com", "propertyId": "398211002" }
  ]
}
```

`id` is just an internal slug (lowercase, hyphens). You can mix real properties and `"propertyId": "demo"` entries while you migrate.

## Step 6 — Switch off demo mode

In `.env`:

```
DEMO_MODE=0
GOOGLE_APPLICATION_CREDENTIALS=./ga4-service-account.json
```

Restart the server (`node server/index.js`). Real data should appear immediately. If a property errors, the API response will say why — the two usual causes are the service account not yet added as Viewer on that property (step 4), or a typo'd property ID (step 5).
