> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ocular.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Google Analytics 4
> Connect Google Analytics 4 to Ocular through the GA4 BigQuery export using a Google Cloud service account for full session and event-level reporting.
Ocular reads GA4 data through the **GA4 → BigQuery export**. You'll link GA4 to a BigQuery project, create a service account with read access, grant that service account access to the GA4 property, then paste the credentials into Ocular.
Project ID, Service-Account JSON key, BigQuery dataset/schema name, dataset location, GA4 Property ID, and Start / Events Start datesGA4 Property ID, and Start / Events Start dates.
Storefront-attributed ROAS, the User Activity Cohort (event-based retention), and the full session-to-checkout funnel.
**Prerequisites:** a GA4 property, a Google Cloud project with billing or sandbox enabled, BigQuery Owner on that project, and at least GA4 **Editor** access on the property.
***
## Step 1 · Link GA4 to BigQuery
Skip this step if you already have GA4 exporting to BigQuery.
In your GA4 property, click **Admin** → **BigQuery Linking**.
In your GA4 property, click **Admin** → **BigQuery Linking**In your GA4 property, click **Admin** → **BigQuery Linking**.
Click **Link** to start a new connection**Link** to start a new connection.
Click **Link** to start a new connectionClick **Link** to start a new connection.
Click **Choose a BigQuery project**, select your existing project, and click **Confirm**.
If your project isn't listed, confirm you've created it in Google Cloud and refresh.
Click **Choose a BigQuery project**, select your existing project, and click **Confirm**.
If your project isn't listed, confirm you've created it in Google Cloud and refresh.
Select the region where you'll run your queries.
If you choose the wrong region and need to change it later, you'll have to move the dataset in Google Cloud and create a new link, or delete the link + dataset and start over.
* **Daily** — one update per day (recommended).
* **Streaming (optional)** — a same-day table that fills until the day completes, then a new daily table is added.
Streaming is **not** available on BigQuery sandbox accounts. Enable it later if you upgrade to a billing-enabled project.
Click **Choose a BigQuery project**, select your existing project, and click **Confirm**.
If your project isn't listed, confirm you've created it in Google Cloud and refresh.
Click **Choose a BigQuery project**, select your existing project, and click **Confirm**.
If your project isn't listed, confirm you've created it in Google Cloud and refresh.
Select the region where you'll run your queries.
If you choose the wrong region and need to change it later, you'll have to move the dataset in Google Cloud and create a new link, or delete the link + dataset and start over.
* **Daily** — one update per day (recommended).
* **Streaming (optional)** — a same-day table that fills until the day completes, then a new daily table is added.
Streaming is **not** available on BigQuery sandbox accounts. Enable it later if you upgrade to a billing-enabled project.
* **Daily** — one update per day (recommended).
* **Streaming (optional)** — a same-day table that fills until the day completes, then a new daily table is added.
Streaming is **not** available on BigQuery sandbox accounts. Enable it later if you upgrade to a billing-enabled project.
If you have an additional data stream (app or web), add it to the same dataset via **Edit**. You may also see a step to filter events sent to BigQuery — useful to skip events you don't need or stay under the 1-million-events daily limit.
Review the settings and click **Submit**. The BigQuery link is created — first data takes up to **24 hours** to appear in BigQuery.
When you link GA4 to BigQuery, Google creates a service account `firebase-measurement@system.gserviceaccount.com`. Verify it's been added as a project member with the **BigQuery User** role. If it was given **Editor** previously, you'll need to unlink and relink GA4 to BigQuery to change the role.
When data starts flowing, GA4 writes `events_*` tables into a dataset named `analytics_PROPERTY_ID` inside the selected project.
***
## Step 2 · Create a service account with BigQuery access
In Google Cloud console, open the same project and navigate to **IAM & Admin → Service Accounts**.
In Google Cloud console, open the same project and navigate to **IAM & Admin → Service Accounts**In Google Cloud console, open the same project and navigate to **IAM & Admin → Service Accounts**.
Click **+ Create Service Account**, name it (e.g., `ocular-ga4-reader`), and click **Create and Continue**.Click **+ Create Service Account**, name it (e.g., `ocular-ga4-reader`), and click **Create and Continue**.
Click **+ Create Service Account**, name it (e.g., `ocular-ga4-reader`), and click **Create and Continue**.
Add these three roles:
Read dataset and table data.
Run BigQuery jobs in the project.
Faster reads on large tables.
Add these three roles:
Read dataset and table data.
Run BigQuery jobs in the project.
Faster reads on large tables.
Click **Done**, open the service account, then **Keys → Add key → Create new key → JSON**. Save the file securely — it contains the service-account key Ocular will use.
Click **+ Create Service Account**, name it (e.g., `ocular-ga4-reader`), and click **Create and Continue**.
Add these three roles:
Read dataset and table data.
Run BigQuery jobs in the project.
Faster reads on large tables.
Add these three roles:
Read dataset and table data.
Run BigQuery jobs in the project.
Faster reads on large tables.
Click **Done**, open the service account, then **Keys → Add key → Create new key → JSON**. Save the file securely — it contains the service-account key Ocular will use.
Click **Done**, open the service account, then **Keys → Add key → Create new key → JSON**. Save the file securely — it contains the service-account key Ocular will use.
Full Google reference: [Creating and managing service accounts](https://cloud.google.com/iam/docs/service-accounts-create).
***
## Step 3 · Give the service account access to the GA4 property
From IAM & Admin, copy the service account's email address.
In GA4, go to **Admin → Property Access Management**, then click **+ → Add users**.
Paste the email, assign the **Viewer** (read-only) role, and click **Save**.
The service account can now query GA4 event tables via BigQuery without using OAuth.
***
## Step 4 · Find your schema name, Property ID,schema name, Property ID, and location
### Schema name
In Google Cloud Console, navigate to **BigQuery**.
In the **Explorer** panel, expand your Project ID.
Look for a dataset named `analytics_` followed by your GA4 property ID. The full string is your schema name — e.g., `analytics_123456789`.
### Property ID
In Google Analytics, click on your account / company name.
The Property ID is listed under **Properties & Apps**. It's a numeric value (e.g., `123456789`).
### Dataset location
Click on the `analytics_*` dataset in the BigQuery Explorer.
In the **Dataset info** panel on the right, find **Data location**. Note the region (e.g., `US`, `EU`, `asia-southeast1`).
### Property ID
In Google Analytics, click on your account / company name.
The Property ID is listed under **Properties & Apps**. It's a numeric value (e.g., `123456789`).
### Dataset location
Click on the `analytics_*` dataset in the BigQuery Explorer.
In the **Dataset info** panel on the right, find **Data location**. Note the region (e.g., `US`, `EU`, `asia-southeast1`).
Or run this query to get both values at once:
```sql theme={null}
SELECT schema_name, location
FROM `your-project-id.INFORMATION_SCHEMA.SCHEMATA`
WHERE schema_name LIKE 'analytics_%';
```
***
## Step 5 · Plug the credentials into Ocular
In Ocular, open **Data Management → Connectors → Add connector → Google Analytics 4**.
In Ocular, open **Data Management → Connectors → Add connector → Google Analytics 4**.
Any name you choose.
Your Google Cloud project ID.
Upload or paste the JSON file contents from Step 2.
The `analytics_*` dataset name from Step 4.
Earliest date for data sync (e.g., `2023-01-01`).
The region from Step 4.
In Ocular, open **Data Management → Connectors → Add connector → Google Analytics 4**.
Any name you choose.
Your Google Cloud project ID.
Upload or paste the JSON file contents from Step 2.
The `analytics_*` dataset name from Step 4.
Earliest date for data sync (e.g., `2023-01-01`).
The region from Step 4.
Any name you choose.
Earliest date for data sync (e.g., `2023-01-01`)Earliest date for data sync (e.g., `2023-01-01`).
Number of past days re-fetched on each sync so late-updating data stays current. Default is 30 daysNumber of past days re-fetched on each sync so late-updating data stays current. Default is 30 days.
The date from which you want to start loading events datadate from which you want to start loading events data.
Choose **Campaign** if your UTMs are defined at the campaign level, or **Ad** if they're defined at the ad level — attribution is applied at the level you pickChoose **Campaign** if your UTMs are defined at the campaign level, or **Ad** if they're defined at the ad level — attribution is applied at the level you pick.
The `analytics_*` dataset name from Step 4.
Upload or paste the JSON file contents from Step 2.
Automatically extracted from your service-account JSON file.
Your GA4 Property ID — see Step 4 for where to find it.
The `analytics_*` dataset name from Step 4.
Upload or paste the JSON file contents from Step 2.
Automatically extracted from your service-account JSON file.
Your GA4 Property ID — see Step 4 for where to find it.
The region from Step 4.
Click **Create Connection**. Ocular validates the key by running `SELECT COUNT(1) FROM .analytics_* LIMIT 1`.
On success, click **Create** — the first daily sync kicks off automatically.
***
## Troubleshooting
GA4 → BigQuery takes up to **24 hours** for the first export. If nothing appears after 24 hours, verify:
* The link is still active in **GA4 Admin → BigQuery Linking**.
* `firebase-measurement@system.gserviceaccount.com` is a project member with the **BigQuery User** role.
* You haven't hit the 1-million-events daily cap on a sandbox project.
Confirm the **Schema name** matches the actual dataset (`analytics_`, not just `analytics_`) and the **Location** matches the dataset's region. A region mismatch causes BigQuery to silently return zero rows.
The service account must have all three roles: **BigQuery Data Viewer**, **BigQuery Job User**, **BigQuery Read Session User**. Re-check under **IAM & Admin → IAM** in Google Cloud and re-grant if any are missing.
BigQuery datasets can't be moved across regions in place. Either move the dataset using Google Cloud's transfer service, or unlink GA4 → BigQuery, delete the existing dataset, and re-link with the correct region.
For ticket-writing format when filing a connector issue, see [Working with the Ocular team → Connector-not-working tickets](/overview/working-with-the-ocular-team).
***
## GA4 Historical Connector
The GA4 Historical connector lets you import historical Google Analytics 4 data through the **Google Analytics Reporting API** — without needing a BigQuery export pipeline. Unlike the standard GA4 connector above, this one pulls pre-aggregated report data directly from the GA4 API.
This is particularly useful when you need to:
* Analyze data from **before** your GA4–BigQuery integration was set up
* Access aggregated metrics and dimensions that may be pre-processed by Google
* Backfill historical data for specific time periods
* Pull historical reporting data without setting up the full BigQuery export pipeline
GA4 Property ID, Google Cloud Project ID, Service Account JSON key, and a Project Location.
Pre-aggregated GA4 reporting data for historical periods not covered by your BigQuery export.
**Prerequisites:** A GA4 property with historical data, a Google Cloud project with the Google Analytics Reporting API enabled, and a service account with Viewer role on the GA4 property.
***
### Step H1 · Locate your GA4 Property ID
Go to your GA4 property in the Google Analytics interface.
The Property ID can be found in your GA4 property settings or in the URL of your GA4 property. It's a numeric value (e.g., `123456789`).
If you're not sure where to find it, check the URL when viewing your GA4 property — it will contain the Property ID.
***
### Step H2 · Create a service account with appropriate permissions
In Google Cloud console, open your project and navigate to **IAM & Admin → Service Accounts**.
Click **+ Create Service Account**, name it (e.g., `ocular-ga4-reader`), and click **Create and Continue**.
Add these roles:
Read dataset and table data.
Run BigQuery jobs in the project.
Faster reads on large tables.
Access the GA4 Reporting API.
Click **Done**, open the service account, then **Keys → Add key → Create new key → JSON**. Save the file securely.
Copy the service account email address. In GA4, go to **Admin → Property Access Management**, click **+ → Add users**, paste the email, assign the **Viewer** role, and click **Save**.
If you are not sure how to create a service account, follow the [Google Cloud Service Account documentation](https://cloud.google.com/iam/docs/service-accounts-create).
***
### Step H3 · Set up the connector in Ocular
In Ocular, navigate to **Data Management → Connectors → Add connector → GA4 Historical**.
A descriptive name for your connector (e.g., `GA4 Historical Main`).
The date from which you want to start loading data. Leave empty to use the default configuration.
Your Google Analytics 4 Property ID (e.g., `123456789`).
The geographic location where your Google Cloud project is located (e.g., Asia South 1 (Mumbai)).
Upload your JSON key file or paste its contents. The Google Cloud Project ID is automatically extracted from this file.
A descriptive name for your connector (e.g., `GA4 Historical Main`).
The date from which you want to start loading data. Leave empty to use the default configuration.
Your Google Analytics 4 Property ID (e.g., `123456789`).
The geographic location where your Google Cloud project is located (e.g., Asia South 1 (Mumbai)).
Upload your JSON key file or paste its contents. The Google Cloud Project ID is automatically extracted from this file.
A descriptive name for your connector (e.g., `GA4 Historical Main`).
The date from which you want to start loading data. Leave empty to use the default configuration.
Your Google Analytics 4 Property ID (e.g., `123456789`).
The geographic location where your Google Cloud project is located (e.g., Asia South 1 (Mumbai)).
Upload your JSON key file or paste its contents. The Google Cloud Project ID is automatically extracted from this file.
A descriptive name for your connector (e.g., `GA4 Historical Main`).
The date from which you want to start loading data. Leave empty to use the default configuration.
Your Google Analytics 4 Property ID (e.g., `123456789`).
The geographic location where your Google Cloud project is located (e.g., Asia South 1 (Mumbai)).
Upload your JSON key file or paste its contents. The Google Cloud Project ID is automatically extracted from this file.
***
### Step H4 · Test and create the connection
Click **Test Connection** to verify your credentials and API access.
Once successful, click **Update Connector** to create the connection and begin retrieving historical GA4 data.
Unlike the standard GA4 connector that pulls raw event data from BigQuery, the Historical connector uses the Google Analytics Reporting API to retrieve pre-aggregated data. This means it may have different metrics and dimensions available than what you'd find in the raw BigQuery export.