# AI Analytics Insights – Setup Guide

The **Analytics insights** feature lets admins ask natural language questions about their GA4 tracking data and get CEO-level answers. It uses the GA4 Data API and OpenAI.

## Prerequisites

- **GA4 property** with Blueprint tracking enabled (events flowing to GA4)
- **OpenAI API key** (already used by AI Assist)
- **Google Cloud service account** with GA4 Data API access

## 1. Create a Google Cloud service account

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Select or create a project
3. **IAM & Admin** → **Service Accounts** → **Create Service Account**
4. Name it (e.g. `blueprint-ga4-reader`) → **Create** → **Done**
5. Click the new service account → **Keys** → **Add Key** → **Create new key** → **JSON**
6. Save the JSON file securely

## 2. Enable the Google Analytics Data API

1. In [Google Cloud Console](https://console.cloud.google.com/), select the **same project** your service account belongs to
2. Go to **APIs & Services** → **Library**
3. Search for **Google Analytics Data API**
4. Click it → **Enable**

If you skip this, you'll see: *"Google Analytics Data API has not been used in project X before or it is disabled"*

## 3. Grant GA4 access to the service account

1. Go to [GA4 Admin](https://analytics.google.com/) → **Admin** (gear icon)
2. Under **Property**, click **Property access management**
3. **Add users** → enter the service account email (e.g. `blueprint-ga4-reader@your-project.iam.gserviceaccount.com`)
4. Role: **Viewer** (read-only)
5. **Add**

## 4. Get your GA4 Property ID

1. In GA4 Admin → **Property settings**
2. Copy the **Property ID** (numeric, e.g. `123456789`)

The Measurement ID (e.g. `G-XXXXXXXXXX`) is different; use the **Property ID**.

## 5. Add Supabase Edge Function secrets

1. Open **Supabase Dashboard** → your project → **Edge Functions** → **Secrets**
2. Add these secrets:

| Secret | Value |
|--------|-------|
| `OPENAI_API_KEY` | Your OpenAI API key (if not already set) |
| `GA4_PROPERTY_ID` | Your GA4 Property ID (e.g. `123456789`) |
| `GA4_SERVICE_ACCOUNT_JSON` | The **entire** contents of the service account JSON file |

For `GA4_SERVICE_ACCOUNT_JSON`, paste the full JSON object. It should look like:

```json
{
  "type": "service_account",
  "project_id": "...",
  "private_key_id": "...",
  "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
  "client_email": "...@....iam.gserviceaccount.com",
  "client_id": "...",
  ...
}
```

## 6. Deploy the Edge Function

```bash
supabase functions deploy ai-analytics-insights --no-verify-jwt
```

Use `--no-verify-jwt` because the function verifies the JWT and admin role itself.

## 7. Test

1. Sign in as **admin**
2. Go to **Admin** → **Analytics insights**
3. Ask a question, e.g. *"What are the top events this month?"*
4. Click **Ask**

## Troubleshooting

- **"GA4 not configured"** – Add `GA4_PROPERTY_ID` and `GA4_SERVICE_ACCOUNT_JSON` to Edge Function secrets
- **"GA4 auth failed"** – Check the service account JSON is valid and the private key has correct line breaks
- **"GA4 report failed"** – Enable the [Google Analytics Data API](https://console.cloud.google.com/apis/library/analyticsdata.googleapis.com) in your Google Cloud project. Also ensure the service account has Viewer access to the GA4 property.
- **"Admin access required"** – Only users with `role = 'admin'` can use this feature
- **Empty or sparse data** – GA4 can have a 24–48 hour delay for standard reports. Enable tracking in Admin → Tracking and ensure events are flowing.

## What questions can you ask?

- *What are the top events this month?*
- *How is engagement trending over the last 7 days?*
- *Which traffic sources bring the most sessions?*
- *What’s our daily active user trend?*
- *Which Blueprint events get the most clicks?*

The AI selects the best GA4 report and date range, then summarizes the results in plain language.