Skip to main content

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.

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.

What you need

Project ID, Service-Account JSON key, BigQuery dataset/schema name, dataset location, and a Start Date.

What it unlocks

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.
GA4 connector placeholder
Skip this step if you already have GA4 exporting to BigQuery.

Open BigQuery Linking

In your GA4 property, click Admin → BigQuery Linking.

Create a new link

Click Link to start a new connection.

Choose your Google Cloud 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.

Pick a data location

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.

Choose export frequency

  • 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.

Optional — add another stream or event filter

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.

Submit

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

Open IAM & Admin → Service Accounts

In Google Cloud console, open the same project and navigate to IAM & Admin → Service Accounts.

Create the service account

Click + Create Service Account, name it (e.g., ocular-ga4-reader), and click Create and Continue.

Grant roles

Add these three roles:

BigQuery Data Viewer

Read dataset and table data.

BigQuery Job User

Run BigQuery jobs in the project.

BigQuery Read Session User

Faster reads on large tables.

Create a JSON key

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.

​
Step 3 · Give the service account access to the GA4 property

Copy the service account email

From IAM & Admin, copy the service account’s email address.

Open GA4 Property Access Management

In GA4, go to Admin → Property Access Management, then click + → Add users.

Add the service account as Viewer

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 BigQuery schema and location

​
Schema name

Open BigQuery

In Google Cloud Console, navigate to BigQuery.

Expand your project

In the Explorer panel, expand your Project ID.

Find the analytics_ dataset

Look for a dataset named analytics_ followed by your GA4 property ID. The full string is your schema name — e.g., analytics_123456789.

​
Dataset location

Click the dataset

Click on the analytics_* dataset in the BigQuery Explorer.

Read Data location

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: 
SELECT schema_name, location
FROM `your-project-id.INFORMATION_SCHEMA.SCHEMATA`
WHERE schema_name LIKE 'analytics_%';

​
Step 5 · Plug the credentials into Ocular

Open the connector form

In Ocular, open Data Management → Connectors → Add connector → Google Analytics 4.

Fill the fields

Connector Name

Any name you choose.

Project ID

Your Google Cloud project ID.

Service-account JSON key

Upload or paste the JSON file contents from Step 2.

Schema name

The analytics_* dataset name from Step 4.

Start Date

Earliest date for data sync (e.g., 2023-01-01).

Location of the BigQuery

The region from Step 4.

Create the connection

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_<property_id>, 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.