Google Analytics 4 Connector

The Google Analytics 4 Connector provides guidelines for using the GA4 Data API to retrieve user behavior data and securely send it to HCL CDP (Customer Data Platform).

Introduction

The Google Analytics 4 connector uses the GA4 Data API to fetch user behavior data from your Google Analytics 4 properties and integrate it into HCL CDP. The connector operates on a "day-1" data availability concept, meaning that if a flow runs on August 6, it will retrieve data for August 5 from GA4 and insert it into CDP.

Prerequisites

Before using the GA4 Data API and Google Analytics 4 Connector, ensure you have the following configured:

  • Google Cloud Account: An active Google Cloud account with the Google Analytics Data API enabled.
  • Google Analytics Account: An active Google Analytics 4 account and property.

Connection Box Properties

The connection defines the parameters to establish communication between GA4 and HCL CDP:

Property Description
Base URL The GA4 Data API base URL (e.g., https://analyticsdata.googleapis.com/).
Redirect URI The redirect URI configured in your Google Cloud Project.
Client ID The Client ID for GA4 from the Google Cloud Project.
Client Secret The Client secret for GA4 from the Google Cloud Project.
Access Token / Refresh Token The authentication tokens for the account (auto-populated).
GA4 Property ID The specific Property ID of your Google Analytics Account.
CDP API URL The CDP API endpoint URL where data will be ingested.
Activity Fetch Units The fetch interval time unit (hours, minutes, seconds).
Activity Fetch Interval The fetch interval time value (e.g., 2).
Number of Retries The number of times to retry the API call if the server is inaccessible.

Action Box Properties

The action configuration specifies the data retrieval parameters:

Property Description
CDP API Key / Pass Key The keys used to authenticate the CDP tenant.
Start Date The date from which the data should be retrieved.
Dimension Values The selected dimension fields from the list.
Metrics Values The selected metrics fields from the list.
CDP Primary Identifier The primary identifier name for CDP (e.g., identity).
Batch Size The batch size to send to CDP (Default is 500).
Maximum Instances The number of instances to run in parallel (Default is 1).
Delay Days The number of delay days based on data availability.
Duration The duration in days that the flow should run.

Dimension and Metrics Limits

Maximum values enforced by the GA4 Data API:

  • Dimensions per request: Maximum of 9.
  • Metrics per request: Maximum of 10.
  • Date ranges per request: Maximum of 4.
  • Rows per response: 250,000 rows.
  • Pagination: 10,000 rows per page.

Mandatory Fields for Execution:

  • Dimensions: custom_user_id and eventName.
  • Metrics: eventCount.

API Details and Event Tracking

The connector relies on OAuth 2.0 authentication to generate a bearer access token using https://www.googleapis.com/auth/analytics.readonly.

Success Scenario Example

status,status_code,message_id,status_message,timestamp
                Success,200,e4c597a3-616d-4f59-9f7c-7dd91ce94bb5,Data Processed successfully,2025-08-04T18:53:56

Error Scenario Example

status,status_code,message_id,status_message,timestamp
                Error,,,Forbidden,2025-08-04T18:51:56

Known Issues and Resolutions

Known Issue Resolution
FORBIDDEN ERROR (Incorrect API key/passkey) Provide the correct CDP URL, API key, and passkey corresponding to your tenant.
401 UNAUTHENTICATED (Invalid or expired token) Regenerate the Access Token using your Refresh Token.
403 PERMISSION_DENIED (Insufficient permissions) In GA4 Admin, assign the Viewer or Analyst role via Property Access Management.
404 NOT_FOUND (Incorrect Property ID) Verify and copy the correct Property ID from the GA4 Admin panel.
429 RESOURCE_EXHAUSTED (Quota exceeded) Implement retry with exponential backoff and reduce API call frequency.
403 API_NOT_ENABLED Enable the Google Analytics Data API within your Google Cloud Console.
INVALID_CREDENTIALS / invalid_grant Regenerate token and ensure Redirect URI matches your configuration exactly.