Google Analytics 4

​

Required fields in Ocular

• Project ID — your Google Cloud project that hosts the GA4 → BigQuery export
• Service-Account Key (JSON) — the contents of a JSON key file for a service account that can read BigQuery and view the GA4 property
• Schema name — the schema name in which your BigQuery export happens
• Start Date & Event Start Date — the date after which you want your data to be fetched and used by Ocular
• GA4 Property ID — located under company name
• Location of the BigQuery — the location of the schema in the BigQuery you specified

​

Step 1 · 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.

Click + Create Service Account

Name it and click Create and Continue

Name it (e.g., ocular-ga4-reader) and click Create and Continue.

Grant roles

Grant these roles:

BigQuery Data Viewer

Read dataset and table data.

BigQuery Job User

Run BigQuery jobs in the project.

BigQuery Read Session User

For faster large-table reads.

Create a JSON key

Click Done, then go back into the service account and choose Keys → Add key → Create new key → JSON.

Save the key file

Save the file — it contains your service-account key.

​

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

​

Step 3 · Link GA4 to BigQuery

Open BigQuery Linking

In your GA4 property, click Admin and then BigQuery Linking.

Create a new link

Click Link to create a new connection.

Choose your BigQuery project

Click Choose a BigQuery project. Select your existing BigQuery (Google Cloud) project and click Confirm.

If your project is not listed, make sure you’ve added it in Google Cloud and refresh this page.

Select your data location

Select your preferred data location. Make sure you choose the location where you run your queries.

If you choose the wrong region and need to change it after you’ve created the link, you’ll have to move the dataset in Google Cloud and then create a new link, or delete the link and dataset and start over.

Select the export frequency

Select the desired frequency of the data export:

• Daily — for once a day updates.
• Optional Streaming — adds a table where data from today is stored until the day is complete, then a new daily table is added.

Optional — add another data stream

If you have another data stream (app or web), you can add it to the same BigQuery dataset via Edit.

The Streaming option is not available for BigQuery sandbox environments. You can enable streaming export later if you upgrade to a billing-enabled account.

Optional — filter events

You may see an additional step where you can filter events that will be sent to BigQuery. This is useful for events you don’t need or to avoid exceeding the daily limit of 1 million events.

Submit

Review the settings and if everything is correct, click Submit. The BigQuery link is created. It will take some time (up to 24 hours) for your data to appear in BigQuery.

​

Step 4 · Find your BigQuery schema name and location

​

Finding the schema name

​

Finding the Property ID

​

Finding the BigQuery location

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

Return to Data Management → Connectors → Add connector → Google Analytics 4.

Enter your values

Connector Name

Any name you choose.

Start Date

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

Lookback Days

The number of past days from which data will be fetched during synchronization. This ensures recent historical data is included and kept up to date. The default setting is 30 days.

Events Start Date *

Select the date from which you want to start loading events data.

UTM Attribution Level

Choose campaign-level if UTMs are defined at the campaign level — attribution is applied at the campaign level. Choose ad-level if UTMs are defined at the ad level — attribution is applied at the individual ad level.

Schema name

The analytics_* dataset name from Step 4.

Service-account JSON key

Upload or paste the JSON file contents from Step 1.

Project ID

Your Google Cloud project ID. Automatically extracted from your service account JSON file.

GA4 Property ID

Located under company name — see Step 4 for the exact location.

Location of the BigQuery

The region from Step 4.

Create the connector

On success, click Create — your first daily sync kicks off automatically.

​

Troubleshooting

​

GA4 Historical Connector

• 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

​

Step H1 · Locate your GA4 Property ID

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.

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

​

Step H2 · Create a service account with appropriate permissions

​

Step H3 · Set up the connector in Ocular

​

Step H4 · Test and create the connection