Pipeloom Docs
ConnectorsSources

Google Analytics 4 (GA4)

Set up the Google Analytics 4 (GA4) source connector.

Sync modes, namespaces and the columns Pipeloom adds are explained once in Connector concepts; workspace variables and custom components in Orchestration.

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

Google Analytics 4 (GA4) is the latest version of Google Analytics, introduced in 2020. It offers a new data model that emphasizes events and user properties, rather than pageviews and sessions. This updated model allows for more flexibility and customization in reporting, and provides more accurate measurement of user behavior across various devices and platforms.

This connector works with Google Analytics 4 (GA4) and Google Analytics 360 (GA360) properties.

Prerequisites

  • A Google Analytics account with access to the GA4 property and property ID you want to sync

Setup guide

Step 1: Set up Google Analytics 4 (GA4)

Create a Service Account for authentication

  1. Sign in to the Google Account you are using for Google Analytics as an admin.
  2. Go to the Service Accounts page in the Google Developers console.
  3. Select the project you want to use (or create a new one) and click Continue.
  4. Click + Create Service Account at the top of the page.
  5. Enter a name for the service account, and optionally, a description. Click Create and Continue.
  6. Choose the role for the service account. We recommend the Viewer role (Read & Analyze permissions). Click Continue.
  7. Select your new service account from the list, and open the Keys tab. Click Add Key > Create New Key.
  8. Select JSON as the Key type. This will generate and download the JSON key file that you'll use for authentication. Click Continue.

:::note When authenticating with a service account (Pipeloom), you must also grant that service account access to the GA4 property in Google Analytics. Creating a service account and downloading the JSON key does not automatically give it permission to read Analytics data.

  1. In Google Analytics, go to Admin → under Property, click Property access management.
  2. Click + → Add users, then add the service account email (for example, ...@...iam.gserviceaccount.com).
  3. Grant at least the Viewer role (read-only) for the target property. :::

Enable the Google Analytics APIs

Before you can use the service account to access Google Analytics data, you need to enable the required APIs:

  1. Go to the Google Analytics Reporting API dashboard. Make sure you have selected the associated project for your service account, and enable the API. You can also set quotas and check usage.
  2. Go to the Google Analytics API dashboard. Make sure you have selected the associated project for your service account, and enable the API.
  3. Go to the Google Analytics Data API dashboard. Make sure you have selected the associated project for your service account, and enable the API.

For Pipeloom:

  1. Navigate to the Pipeloom dashboard.

  2. In the left navigation bar, click Sources. In the top-right corner, click + New source.

  3. Find and select Google Analytics 4 (GA4) from the list of available sources.

  4. Select Service Account Key Authentication from the dropdown list and enter the Service Account JSON Key from Step 1.

  5. Enter the Property ID whose events are tracked. This ID should be a numeric value, such as 123456789. If you are unsure where to find this value, refer to Google's documentation. :::note If the Property Settings shows a "Tracking Id" such as "UA-123...-1", this denotes that the property is a Universal Analytics property, and the Analytics data for that property cannot be reported on in the Data API. You can create a new Google Analytics 4 property by following these instructions. :::

  6. (Optional) In the Start Date field, use the provided datepicker or enter a date programmatically in the format YYYY-MM-DD. All data added from this date onward will be replicated. Note that this setting is not applied to custom Cohort reports.

:::note If the start date is not provided, the default value will be used, which is two years from the initial sync. :::

:::caution Many analyses and data investigations may require 24-48 hours to process information from your website or app. To ensure the accuracy of the data, we subtract two days from the starting date. For more details, please refer to Google's documentation. :::

  1. (Optional) Toggle the switch Keep Empty Rows if you want each row with all metrics equal to 0 to be returned.
  2. (Optional) In the Custom Reports field, you may optionally describe any custom reports you want to sync from Google Analytics. See the Custom Reports section below for more information on formulating these reports.
  3. (Optional) In the Data Request Interval (Days) field, you can specify the interval in days (ranging from 1 to 364) used when requesting data from the Google Analytics API. 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. This field does not apply to custom Cohort reports. See the Data Sampling section below for more context on this field.
  4. (Optional) In the Lookback window (Days) field, specify how many days of past data to refresh on every run. Because attribution changes after the event date, and Google Analytics has data processing latency, this helps keep your data consistent. For example, setting this to 5 causes every sync to re-fetch data from the last bookmark date minus 5 days.
  5. (Optional) Enable One Stream per Report to create one stream per report covering all configured property IDs, instead of one stream per report per property. Recommended when syncing many properties. See the One Stream per Report section below — enabling it on an existing connection requires a full re-sync.

:::caution

It's important to consider how dimensions like month or yearMonth are specified. These dimensions organize the data according to your preferences. However, keep in mind that the data presentation is also influenced by the chosen date range for the report. In cases where a very specific date range is selected, such as a single day (Data Request Interval (Days) set to one day), duplicated data entries for each day might appear. To mitigate this, we recommend adjusting the Data Request Interval (Days) value to 364. By doing so, you can obtain more precise results and prevent the occurrence of duplicated data.

:::

  1. Click Set up source and wait for the tests to complete.

Supported sync modes

The Google Analytics 4 (GA4) source connector supports the following sync modes:

Supported Streams

This connector outputs the following streams:

Preconfigured and custom report streams use the Google Analytics Data API properties.runReport method. Each report stream represents a different combination of dimensions and metrics sent to the same API endpoint. Custom reports that specify pivots use the properties.runPivotReport method instead.

  • Preconfigured streams:
    • daily_active_users
    • devices
    • four_weekly_active_users
    • locations
    • pages
    • traffic_sources
    • website_overview
    • weekly_active_users
    • user_acquisition_first_user_medium_report
    • user_acquisition_first_user_source_report
    • user_acquisition_first_user_source_medium_report
    • user_acquisition_first_user_source_platform_report
    • user_acquisition_first_user_campaign_report
    • user_acquisition_first_user_google_ads_ad_network_type_report
    • user_acquisition_first_user_google_ads_ad_group_name_report
    • traffic_acquisition_session_source_medium_report
    • traffic_acquisition_session_medium_report
    • traffic_acquisition_session_source_report
    • traffic_acquisition_session_campaign_report
    • traffic_acquisition_session_default_channel_grouping_report
    • traffic_acquisition_session_source_platform_report
    • events_report
    • weekly_events_report
    • conversions_report
    • pages_title_and_screen_class_report
    • pages_path_report
    • pages_title_and_screen_name_report
    • content_group_report
    • ecommerce_purchases_item_name_report
    • ecommerce_purchases_item_id_report
    • ecommerce_purchases_item_category_report_combined
    • ecommerce_purchases_item_category_report
    • ecommerce_purchases_item_category_2_report
    • ecommerce_purchases_item_category_3_report
    • ecommerce_purchases_item_category_4_report
    • ecommerce_purchases_item_category_5_report
    • ecommerce_purchases_item_brand_report
    • publisher_ads_ad_unit_report
    • publisher_ads_page_path_report
    • publisher_ads_ad_format_report
    • publisher_ads_ad_source_report
    • demographic_country_report
    • demographic_region_report
    • demographic_city_report
    • demographic_language_report
    • demographic_age_report
    • demographic_gender_report
    • demographic_interest_report
    • tech_browser_report
    • tech_device_category_report
    • tech_device_model_report
    • tech_screen_resolution_report
    • tech_app_version_report
    • tech_platform_report
    • tech_platform_device_category_report
    • tech_operating_system_report
    • tech_os_with_version_report
  • Property metadata stream:
    • property_metadata
  • Custom stream(s)

The property_metadata stream is full-refresh and uses the Admin API properties.get method. It emits one record for each configured property ID and includes a property_id field for joining with report streams.

The property_metadata stream requires the Google Analytics Admin API (analyticsadmin.googleapis.com) to be enabled for the GCP project associated with the credentials; service-account users must enable it in their own project. If it is not enabled, this stream fails with a 403 SERVICE_DISABLED error, while report streams continue to work.

Connector-specific features

Custom Reports

Custom reports in Google Analytics allow for flexibility in querying specific data tailored to your needs. You can define the following components:

  • Name: The name of the custom report.
  • Dimensions: An array of categories for data, such as city, user type, etc.
  • Metrics: An array of quantitative measurements, such as active users, page views, etc.
  • CohortSpec: (Optional) An object containing specific cohort analysis settings, such as cohort size and date range. More information on this object can be found in the GA4 documentation.
  • Pivots: (Optional) An array of pivot tables for data, such as page views by city, etc. More information on pivots can be found in the GA4 documentation.

A full list of dimensions and metrics supported in the API can be found here. To ensure your dimensions and metrics are compatible for your GA4 property, you can use the GA4 Dimensions & Metrics Explorer.

The following is an example of a basic User Engagement report to track sessions and bounce rate, segmented by city:

[
  {
    "name": "User Engagement Report",
    "dimensions": ["city"],
    "metrics": ["sessions", "bounceRate"]
  }
]

By specifying a cohort with a 7-day range and pivoting on the city dimension, the report can be further tailored to offer a detailed view of engagement trends within the top 50 cities for the specified date range.

[
  {
    "name": "User Engagement Report",
    "dimensions": ["city"],
    "metrics": ["sessions", "bounceRate"],
    "cohortSpec": {
      "cohorts": [
        {
          "name": "Last 7 Days",
          "dateRange": {
            "startDate": "2023-07-27",
            "endDate": "2023-08-03"
          }
        }
      ],
      "cohortReportSettings": {
        "accumulate": true
      }
    },
    "pivots": [
      {
        "fieldNames": ["city"],
        "limit": 50,
        "metricAggregations": ["TOTAL"]
      }
    ]
  }
]

One Stream per Report

By default, the connector creates a separate stream for every combination of report and Property ID. With 57 built-in reports and 70 properties that is roughly 3,990 streams, which makes the catalog slow to load, the stream list hard to manage, and setup error-prone.

Enabling One Stream per Report creates one stream per report instead, covering every configured property. Each record carries a property_id field, and property_id is part of the stream's primary key, so rows from different properties remain distinct in the destination. Each property also keeps its own incremental cursor, so they sync independently.

Consolidated streams are named <report_name>Consolidated — for example, the devices report becomes devicesConsolidated. The per-property streams (devices, devicesProperty5729978930, and so on) are not created while this setting is enabled. The distinct name is deliberate: it guarantees the consolidated stream starts with a clean slate rather than inheriting the destination table and incremental cursor of the single-property stream it replaces.

The stream's schema is the union of the field definitions across all configured properties. This matters if you use custom metrics, which are defined per property in GA4: a custom metric that exists on only some of your properties is still included in the schema, so its data is not dropped. If the same metric name is typed differently across properties, the type from the property listed first in Property IDs is used.

:::caution

Enabling or disabling this setting changes stream names, so data is written to new destination tables and incremental state resets. This is not a setting to toggle casually on an established connection.

Changing it on an existing connection requires a schema refresh. The stream list you see in a connection is a snapshot of the last schema discovery, so the per-property streams keep appearing — and keep syncing nothing — until you refresh it. Follow these steps in order:

  1. Enable the setting on the source and save.
  2. Run Refresh source schema on each connection using this source. The per-property streams (devices, devicesProperty5729978930, and so on) are reported as removed, and the <report_name>Consolidated streams appear.
  3. Enable the consolidated streams you want and apply the changes.
  4. Run a sync. Because the consolidated streams are new, this is a full backfill covering every property.
  5. Once you have confirmed the backfill, you may drop the old per-property tables in your destination. Pipeloom leaves them in place. Keep them if there is any chance you will revert — see below.

Between steps 1 and 3 the connection still lists the old stream names, which no longer exist in the source. Syncs during that window return no records for them.

Reverting is supported and loses no data. Disabling the setting restores the per-property streams under their original names once you refresh the schema again. Each one resumes from the cursor it held before you enabled the setting, so the period the setting was on is re-fetched on the next sync and no gap is left behind.

The one exception is step 5. Deleting a destination table does not reset the stream's cursor, so if you dropped the old per-property tables and later revert, those streams resume from their old cursor and the recreated tables will be missing everything before it. Clear those streams when you revert, and they will backfill in full.

:::

:::caution

Adding a Property ID after enabling this setting. New properties are added to the existing consolidated streams as new partitions, and a new partition starts from the stream's current cursor rather than from your Start Date. The new property's historical data is not backfilled and no error is raised. To backfill it, clear the affected streams after adding the Property ID.

This does not apply when the setting is off, where a new Property ID produces new streams that backfill on their own.

:::

Syncs make the same number of API requests either way, so this setting reduces catalog size and destination table count rather than sync duration.

Data Sampling and Data Request Intervals

Data sampling in Google Analytics 4 refers to the process of estimating analytics data when the amount of data in an account exceeds Google's predefined compute thresholds. To mitigate the chances of data sampling being applied to the results, the Data Request Interval field allows users to specify the interval used when requesting data from the Google Analytics API.

By setting the interval to 1 day, users can reduce the data processed per request, minimizing the likelihood of data sampling and ensuring more accurate results. While larger time intervals (up to 364 days) can speed up the sync, we recommend choosing a smaller value to prioritize data accuracy unless there is a specific need for faster synchronization at the expense of some potential inaccuracies. Please note that this field does not apply to custom Cohort reports.

Refer to the Google Analytics documentation for more information on data sampling.

Performance Considerations

The Google Analytics connector is subject to Google Analytics Data API quotas. Please refer to Google's documentation for specific breakdowns on these quotas.

Data type map

Integration TypePipeloom Type
stringstring
numbernumber
arrayarray
objectobject

IP allow list

If you use Pipeloom and your organization restricts access to specific IPs, add the Pipeloom IP addresses to your allow list.

GitHub

Set up the GitHub source connector.

Google Sheets

Set up the Google Sheets source connector.

On this page

PrerequisitesSetup guideStep 1: Set up Google Analytics 4 (GA4)Create a Service Account for authenticationEnable the Google Analytics APIsFor Pipeloom:Supported sync modesSupported StreamsConnector-specific featuresCustom ReportsOne Stream per ReportData Sampling and Data Request IntervalsPerformance ConsiderationsData type mapIP allow list