Google Analytics 4 (GA4)

This page contains the setup guide and reference information for the Google Analytics 4 source connector.

note

Google Analytics Universal Analytics (UA) connector, uses the older version of Google Analytics, which has been the standard for tracking website and app user behavior since 2012.

Google Analytics 4 (GA4) connector is the latest version of Google Analytics, which was introduced in 2020. It offers a new data model that emphasizes events and user properties, rather than pageviews and sessions. This new model allows for more flexible and customizable reporting, as well as more accurate measurement of user behavior across devices and platforms.

Prerequisites

• JSON credentials for the service account that has access to Google Analytics. For more details check instructions
• OAuth 2.0 credentials for the service account that has access to Google Analytics
• Property ID

Step 1: Set up Source

Create a Service Account

First, you need to select existing or create a new project in the Google Developers Console:

1. Sign in to the Google Account you are using for Google Analytics as an admin.
2. Go to the Service Accounts page.
3. Click Create service account.
4. Create a JSON key file for the service user. The contents of this file will be provided as the credentials_json in the UI when authorizing GA after you grant permissions (see below).

Add service account to the Google Analytics account

Use the service account email address to add a user to the Google analytics view you want to access via the API. You will need to grant Viewer permissions.

Enable the APIs

1. Go to the Google Analytics Reporting API dashboard in the project for your service user. Enable the API for your account. You can set quotas and check usage.
2. Go to the Google Analytics API dashboard in the project for your service user. Enable the API for your account.

Step 2: Set up the Google Analytics connector in Airbyte

For Airbyte Cloud:

1. Login to your Airbyte Cloud account.
2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
3. On the source setup page, select Google Analytics 4 (GA4) from the Source type dropdown and enter a name for this connector.
4. Click Authenticate your account by selecting Oauth or Service Account for Authentication.
5. Log in and Authorize the Google Analytics account.
6. Enter the Property ID whose events are tracked.
7. Enter the Start Date from which to replicate report data in the format YYYY-MM-DD. (Not applied to custom Cohort reports).
8. Enter the Custom Reports (Optional) a JSON array describing the custom reports you want to sync from Google Analytics.
9. Enter the Data request time increment in days (Optional). The bigger this value is, the faster the sync will be, but the more likely that sampling will be applied to your data, potentially causing inaccuracies in the returned results. We recommend setting this to 1 unless you have a hard requirement to make the sync faster at the expense of accuracy. The minimum allowed value for this field is 1, and the maximum is 364. (Not applied to custom Cohort reports).

For Airbyte Open Source:

1. Navigate to the Airbyte Open Source dashboard.
2. In the left navigation bar, click Sources. In the top-right corner, click + new source.
3. On the source setup page, select Google Analytics 4 (GA4) from the Source type dropdown and enter a name for this connector.
4. Select Service Account for Authentication in dropdown list and enter Service Account JSON Key from Step 1.
5. Enter the Property ID whose events are tracked.
6. Enter the Start Date from which to replicate report data in the format YYYY-MM-DD. (Not applied to custom Cohort reports).
7. Enter the Custom Reports (Optional) a JSON array describing the custom reports you want to sync from Google Analytics.
8. Enter the Data request time increment in days (Optional). The bigger this value is, the faster the sync will be, but the more likely that sampling will be applied to your data, potentially causing inaccuracies in the returned results. We recommend setting this to 1 unless you have a hard requirement to make the sync faster at the expense of accuracy. The minimum allowed value for this field is 1, and the maximum is 364. (Not applied to custom Cohort reports).

Supported sync modes

The Google Analytics source connector supports the following sync modes:

• Full Refresh - Overwrite
• Full Refresh - Append
• Incremental - Append
• Incremental - Deduped History

Supported Streams

This connector outputs the following incremental streams:

• Preconfigured streams:
  • daily_active_users
  • devices
  • four_weekly_active_users
  • locations
  • pages
  • traffic_sources
  • website_overview
  • weekly_active_users
• Custom stream(s)

Connector-specific features

note

• Custom reports should be provided in format [{"name": "<report-name>", "dimensions": ["<dimension-name>", ...], "metrics": ["<metric-name>", ...], "cohortSpec": "<cohortSpec>", "pivots": "<pivots>"}]
• Both pivots and cohortSpec are optional. Detailed description of the cohortSpec and the pivots objects you can find here and here.
• To enable Incremental sync for Custom reports, you need to include the date dimension (except for custom Cohort reports). :::

Performance Considerations

Google Analytics Data API Quotas docs.

Data type map

Integration Type	Airbyte Type	Notes
string	string
number	number
array	array
object	object

Changelog

Version	Date	Pull Request	Subject
1.1.2	2023-07-03	27909	Limit the page size of custom report streams
1.1.1	2023-06-26	27718	Limit the page size when calling check()
1.1.0	2023-06-26	27738	License Update: Elv2
1.0.0	2023-06-22	26283	Added primary_key and lookback window
0.2.7	2023-06-21	27531	Fix formatting
0.2.6	2023-06-09	27207	Improve api rate limit messages
0.2.5	2023-06-08	27175	Improve Error Messages
0.2.4	2023-06-01	26887	Remove authSpecification from connector spec in favour of advancedAuth
0.2.3	2023-05-16	26126	Fix pagination
0.2.2	2023-05-12	25987	Categorized Config Errors Accurately
0.2.1	2023-05-11	26008	Added handling for 429 - potentiallyThresholdedRequestsPerHour error
0.2.0	2023-04-13	25179	Implement support for custom Cohort and Pivot reports
0.1.3	2023-03-10	23872	Fix parse + cursor for custom reports
0.1.2	2023-03-07	23822	Improve rate limits customer faced error messages and retry logic for 429
0.1.1	2023-01-10	21169	Slicer updated, unit tests added
0.1.0	2023-01-08	20889	Improved config validation, SAT
0.0.3	2022-08-15	15229	Source Google Analytics Data Api: code refactoring
0.0.2	2022-07-27	15087	fix documentationUrl
0.0.1	2022-05-09	12701	Introduce Google Analytics Data API source