Google Analytics 4

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, GA4 Property ID, and Start / Events Start datesGA4 Property ID, and Start / Events Start dates.

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.

Step 1 · Link GA4 to BigQuery

Skip this step if you already have GA4 exporting to BigQuery.

Open BigQuery Linking

In your GA4 property, click Admin → BigQuery Linking.

Open BigQuery LinkingOpen BigQuery Linking

In your GA4 property, click Admin → BigQuery LinkingIn your GA4 property, click Admin → BigQuery Linking.

Create a new linkreate a new link

Click Link to start a new connectionLink to start a new connection.

Create a new linkCreate a new link

Click Link to start a new connectionClick 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.

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.

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.

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.

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.

Open IAM & Admin → Service AccountsOpen IAM & Admin → Service Accounts

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

Create the service accountCreate the service account

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.

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.

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.

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.

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.

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 schema name, Property ID,schema name, Property ID, 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.

Property ID

Open your account

In Google Analytics, click on your account / company name.

Read the Property ID

The Property ID is listed under Properties & Apps. It’s a numeric value (e.g., 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).

Property ID

Open your account

In Google Analytics, click on your account / company name.

Read the Property ID

The Property ID is listed under Properties & Apps. It’s a numeric value (e.g., 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.

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.

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.

Fill the fields

Connector Name

Any name you choose.

Start DateStart Date

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

Lookback DaysLookback Days

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.

Events Start DatEvents Start Date

The date from which you want to start loading events datadate from which you want to start loading events data.

UTM Attribution LevelUTM Attribution Level

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.

Schema name

The analytics_* dataset name from Step 4.

Service-account JSON key

Upload or paste the JSON file contents from Step 2.

Project ID

Automatically extracted from your service-account JSON file.

GA4 Property ID

Your GA4 Property ID — see Step 4 for where to find it.

Schema name

The analytics_* dataset name from Step 4.

Service-account JSON key

Upload or paste the JSON file contents from Step 2.

Project ID

Automatically extracted from your service-account JSON file.

GA4 Property ID

Your GA4 Property ID — see Step 4 for where to find it.

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

No data in BigQuery after linking

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.

Connection succeeds but Ocular sees no rows

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.

Permission denied on BigQuery

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.

Need to change the region after linking

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.

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

What you need

GA4 Property ID, Google Cloud Project ID, Service Account JSON key, and a Project Location.

What it unlocks

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

Open your GA4 property

Go to your GA4 property in the Google Analytics interface.

Find the Property ID

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

Open IAM & Admin → Service Accounts

In Google Cloud console, open your 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 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.

Google Analytics Admin

Access the GA4 Reporting API.

Create a JSON key

Click Done, open the service account, then Keys → Add key → Create new key → JSON. Save the file securely.

Add service account to GA4

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.

Step H3 · Set up the connector in Ocular

Open the connector form

In Ocular, navigate to Data Management → Connectors → Add connector → GA4 Historical.

Fill the fields

Connector Name

A descriptive name for your connector (e.g., GA4 Historical Main).

Start Date (optional)

The date from which you want to start loading data. Leave empty to use the default configuration.

GA4 Property ID

Your Google Analytics 4 Property ID (e.g., 123456789).

Project Location

The geographic location where your Google Cloud project is located (e.g., Asia South 1 (Mumbai)).

Service Account JSON

Upload your JSON key file or paste its contents. The Google Cloud Project ID is automatically extracted from this file.

Fill the fields

Connector Name

A descriptive name for your connector (e.g., GA4 Historical Main).

Start Date (optional)

The date from which you want to start loading data. Leave empty to use the default configuration.

GA4 Property ID

Your Google Analytics 4 Property ID (e.g., 123456789).

Project Location

The geographic location where your Google Cloud project is located (e.g., Asia South 1 (Mumbai)).

Service Account JSON

Upload your JSON key file or paste its contents. The Google Cloud Project ID is automatically extracted from this file.

GA4 Historical connector form screenshot

Fill the fields

Connector Name

A descriptive name for your connector (e.g., GA4 Historical Main).

Start Date (optional)

The date from which you want to start loading data. Leave empty to use the default configuration.

GA4 Property ID

Your Google Analytics 4 Property ID (e.g., 123456789).

Project Location

The geographic location where your Google Cloud project is located (e.g., Asia South 1 (Mumbai)).

Service Account JSON

Upload your JSON key file or paste its contents. The Google Cloud Project ID is automatically extracted from this file.

Fill the fields

Connector Name

A descriptive name for your connector (e.g., GA4 Historical Main).

Start Date (optional)

The date from which you want to start loading data. Leave empty to use the default configuration.

GA4 Property ID

Your Google Analytics 4 Property ID (e.g., 123456789).

Project Location

The geographic location where your Google Cloud project is located (e.g., Asia South 1 (Mumbai)).

Service Account JSON

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

Test the connection

Click Test Connection to verify your credentials and API access.

Create the connector

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.

What you need

What it unlocks

​ Step 1 · Link GA4 to BigQuery

​ Step 2 · Create a service account with BigQuery access

BigQuery Data Viewer

BigQuery Job User

BigQuery Read Session User

BigQuery Data Viewer

BigQuery Job User

BigQuery Read Session User

BigQuery Data Viewer

BigQuery Job User

BigQuery Read Session User

BigQuery Data Viewer

BigQuery Job User

BigQuery Read Session User

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

​ Step 4 · Find your schema name, Property ID,schema name, Property ID, and location

​Schema name

​Property ID

​Dataset location

​Property ID

​Dataset location

​ Step 5 · Plug the credentials into Ocular

Connector Name

Project ID

Service-account JSON key

Schema name

Start Date

Location of the BigQuery

Connector Name

Project ID

Service-account JSON key

Schema name

Start Date

Location of the BigQuery

Connector Name

Start DateStart Date

Lookback DaysLookback Days

Events Start DatEvents Start Date

UTM Attribution LevelUTM Attribution Level

Schema name

Service-account JSON key

Project ID

GA4 Property ID

Schema name

Service-account JSON key

Project ID

GA4 Property ID

Location of the BigQuery

​ Troubleshooting

​ GA4 Historical Connector

What you need

What it unlocks

​ Step H1 · Locate your GA4 Property ID

​ Step H2 · Create a service account with appropriate permissions

BigQuery Data Viewer

BigQuery Job User

BigQuery Read Session User

Google Analytics Admin

​ Step H3 · Set up the connector in Ocular

Connector Name

Start Date (optional)

GA4 Property ID

Project Location

Service Account JSON

Connector Name

Start Date (optional)

GA4 Property ID

Project Location

Service Account JSON

Connector Name

Start Date (optional)

GA4 Property ID

Project Location

Service Account JSON

Connector Name

Start Date (optional)

GA4 Property ID

Project Location

Step 1 · Link GA4 to BigQuery

Step 2 · Create a service account with BigQuery access

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

Step 4 · Find your schema name, Property ID,schema name, Property ID, and location

Schema name

Property ID

Dataset location

Property ID

Dataset location

Step 5 · Plug the credentials into Ocular

Troubleshooting

GA4 Historical Connector

Step H1 · Locate your GA4 Property ID

Step H2 · Create a service account with appropriate permissions

Step H3 · Set up the connector in Ocular

Step H4 · Test and create the connection