Google Analytics (GA4) connector tools

  • Updated

The Google Analytics (GA4) connector tools in Optimizely Opal let you ask and visualize any question about your web traffic tracked in GA4 directly in Opal. Complete the following steps to enable them.

Add the Google Analytics 4 Opal app in OCP

In the OCP App Directory, complete the following:

  1. Click on the Google Analytics 4 Opal connector tool. 

  2. Click Install App.

    Install Google Analytics 4 app
  3. Decide which authentication method you want to implement. Click on your desired authentication method to jump to that section.

Service account authorization

Service accounts in GA4 are accounts usually used by an application rather than a person. A service account is identified by its unique email address. See Service accounts overview in the Google documentation for more information. Complete the following steps to create a service user in Google and use it to authenticate in OCP.  

Enable the Google Analytics Data API in your Google Cloud project

  1. Go to the Google Cloud Console.
  2. Create a project if you do not have one. See the Create a Google Cloud project documentation for information.

  3. Enable the Google Analytics Data API from the Marketplace for your project. 

    Click enable

Create service account in Google Cloud

  1. Go to AIM & Admin for your project.
  2. Click Create service account.
  3. Enter Optimizely Opal for the Service Account Name.
  4. Copy the Service account email address as you use it in the next section.
  5. (Optional) Enter a Service account description. 
  6. Skip the Permissions and Principals with access sections. You do not need these for this type of account.

  7. Click Done. 

    Copy email address

Create key in Google Cloud

  1. Click on the account for the Service account ID you created in step 5 in the previous section.

  2. Go to Keys > Add key > Create new key 

    Create a new key

  3. Select JSON and click Create. 

    Select JSON
  4. After clicking Create, a JSON file downloads. Open this file on your computer in a text editor and copy the entire JSON to your clipboard. You will paste the JSON into the app settings in OCP in the Use the service user to authenticate in OCP section.

Add the service user in GA4

  1. Go to your Google Analytics property or account.
  2. Add a new user with at least Viewer role permissions using the same Service account ID email address from the previous section. For steps, see the Google documentation on [GA4] Add, edit, and delete Analytics users and user groups.

Use the service user to authenticate in OCP

In the OCP App Directory, complete the following:

  1. Click on the Google Analytics 4 Opal connector tool, if it is not already selected.

  2. On the Settings tab, select Service Account Authentication. 

    Select Service Account Authentication
  3. Enter the following information:
    • Service Account JSON – Paste the content of the JSON file from the Create key in Google Cloud section.

    • Google Cloud Project ID – To get your Project ID go to the Google Cloud Console and copy your ID. 

      Copy your project id

    • Google Analytics Property ID – To get your Property ID, go to Google Analytics. Click Admin and click Property details. 

      Click Property Details

      Copy your Property ID from the Property Details section.

      Copy Property ID
  4. Click Save.

Next, optionally Add a default filter or register the GA4 connector tool in OCP.

Application default credentials

Application Default Credentials (ADC) is a strategy used by the authentication libraries to automatically find credentials based on the application environment. See How Application Default Credentials works in the Google documentation for information.

To set up ADC authentication, you must be assigned a role that grants you serviceusage.services.use permissions for the GA4 project.

  1. Run the following gcloud CLI command:

    gcloud auth application-default login --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/analytics.readonly"

    See Google's gcloud auth application-default login reference and gcloud CLI documentation for information.

  2. Copy the client_id, client_secret, and refresh_token from the generated $HOME/.config/gcloud/application_default_credentials.json file.

In the OCP App Directory, complete the following:

  1. Click on the Google Analytics 4 Opal connector tool, if it is not already selected.
  2. On the Settings tab, select Application Default Credentials (ADC). Select ADC
  3. Enter the following information:
    • Client ID – client_id from the application_default_credentials.json file.
    • Client Secret – client_secret from the application_default_credentials.json file.
    • Refresh Token – refresh_token from the application_default_credentials.json file.

    • Google Cloud Project ID – To get your Project ID go to the Google Cloud Console and copy your ID. 

      Copy project id

    • Google Analytics Property ID – To get your Property ID, go to Google Analytics. Click Admin and click Property details. 

      Property details
  4. Click Save.

Next, optionally Add a default filter or register the GA4 connector tool in OCP.

Add a default filter (optional)

You can designate a domain to use as the default for all queries. This is helpful if you have multiple domains in GA4. If you set a default, you can still query other domains in your prompts, but Opal defaults to the designated domain when a domain is not specified. You can leave this field empty to show all data for all tracked hostnames. 

To set a default, complete the following:

  1. Click Settings > Default Filter.
  2. Enter just the hostname in the Hostname Filter field. Do not include a protocol (https://). For example, enter www.optimizely.com.

  3. Click Save Filter.

    Save Filter

Next, register the GA4 connector tool in OCP.

Register the GA4 connector tool in OCP

After you authenticate your GA4 app in OCP using Service account authorization or Application default credentials and optionally Add a default filter, complete the following in OCP:

  1. Click Settings > Add to Opal.

  2. Click Add to Opal for the Opal Account you want to add the GA4 connector tools to.

    Add to opal

The GA4 connector tools are now discoverable and available for use within Opal. Click Remove from Opal to remove the connection to Opal.

GA4 connector tools

After you add and register the GA4 connector tools, you can call the following tools in Opal. Click on a tool to expand it to learn when to use the tool, available parameters, and example prompts. If you do not provide a required parameter, Opal prompts you for it.

get_custom_dimensions_and_metrics – Lists custom dimensions and metrics configured in GA4. These user-defined data points expand the standard GA4 offerings, letting you tailor your analysis. See [GA4] About custom dimensions and metrics in the Google documentation.
  • When to use
    • See a comprehensive list of all custom dimensions and metrics available in GA4.
    • Understand what specific custom data points you can use for reporting and analysis.
    • Prepare to build custom reports or queries that involve your unique analytics data.
  • Parameters
    • None
  • Example prompts
    • What custom dimensions and metrics do I have in Google Analytics?
    • List all available custom dimensions and metrics.
    • Show me my custom analytics fields.
get_dimensions – Lists standard GA4 dimensions available for reporting. Dimensions are descriptive attributes of user activity (for example, country, deviceCategory, browser, pagePath, and trafficSource) that you can use to categorize and segment your data in reports. See Analytics dimensions and metrics in the Google documentation. 
  • When to use
    • See a list of all standard dimensions available in Google Analytics.
    • Understand what attributes you can use to segment or filter your analytics data.
    • Prepare to build reports or queries that require standard dimensions.
  • Parameters
    • None
  • Example prompts
    • What are the available dimensions in Google Analytics?
    • List all standard dimensions I can use for reporting.
    • Show me the different ways I can break down my user data.
get_metrics – Lists standard GA4 metrics available for reporting. Metrics are quantitative measurements (for example, activeUsers, eventCount, conversions, and revenue) representing the numerical values you want to analyze and aggregate in your reports. See Analytics dimensions and metrics in the Google documentation. 
  • When to use
    • See a list of all standard metrics available in Google Analytics.
    • Understand what quantitative data points you can use for analysis and reporting.
    • Prepare to build reports or queries that require standard metrics.
  • Parameters
    • None
  • Example prompts
    • What metrics can I use in Google Analytics?
    • List all standard metrics for my reports.
    • Show me the quantitative data I can analyze.
run_realtime_report – Returns immediate, up-to-the-minute GA4 insights into user activity for the past 30 minutes. Use this tool to monitor live traffic, validate analytics configurations, and observe immediate impacts. See [GA4] Realtime report in the Google documentation.
  • When to use
    • Monitor live traffic – See who is on your site right now, where they are coming from, and what they are doing.
    • Validate analytics setups – Quickly check if new events or tracking configurations are working correctly.
    • Get real-time data – Query active users, events, traffic sources, device breakdowns, and conversions as they happen.
  • Parameters
    • dimensions – The attributes of user activity you want to see in your report (for example, 'country', 'deviceCategory', 'eventName'). You can find available standard dimensions using the get_dimensions tool.
    • metrics – The quantitative measurements you want to analyze (for example, 'activeUsers', 'eventCount', 'sessions'). You can find available standard metrics using the get_metrics tool.
    • (Optional) dimensionFilter – Object type that lets you filter your report based on specific dimension values. For example, you could filter to only show data for a specific country or device category.
    • (Optional) metricsFilter – Object type that lets you to filter your report based on specific metric values. For example, you could filter to only show data where the number of sessions is greater than 100.
    • (Optional) limit – The maximum number of rows to return in your report. Defaults to a reasonable number if not specified.
    • (Optional) offset – The starting row for your report, useful for paginating through large reports.
    • (Optional) currencyCode – The currency code (for example, "USD", "EUR") to use for currency values in the report. If left empty, the property's default currency is used.
    • (Optional) returnPropertyQuota – Set to True if you want to see information about your Google Analytics property quota usage in the response.
    • (Optional) orderBys – List of objects that specify how you want to sort the results of your report, either by dimensions or metrics, and in ascending or descending order.
  • Example prompts
    • Show me the current active users on my site.
    • What countries are my active users coming from right now?
    • How many sessions are active in the last 30 minutes, broken down by device type?
    • Are there any conversions happening in real-time?
    • Show me active users and their device categories, but only for users from the United States.
run_report – Generates historical GA4 reports across properties, including user demographics, traffic sources, engagement, conversions, ecommerce performance, and time-based trends.
  • When to use
    • Analyze historical data – Look at how your website or app has performed over days, weeks, months, or years.
    • Understand user behavior – Examine user demographics, where they come from, and how they interact with your content.
    • Track key performance indicators (KPIs) – Monitor conversions, revenue, event counts, and other important metrics.
    • Segment your data – Break down your reports by various dimensions like country, device, or traffic source.
    • Identify trends – See how your metrics and dimensions change over time.
  • Parameters

    • dateRanges (list of objects) – Specifies the time periods for your report. You can define one or more date ranges, each with a startDate, endDate, and an optional name. Dates can be absolute (for example, "2025-01-01") or relative (for instance, "yesterday", "30 days ago", "today").

      If you use multiple date ranges, do not include "dateRange" in your dimensions list, as Google Analytics handles this automatically.
    • dimensions – List of attributes you want to include in your report to break down your data (for example, 'country', 'deviceCategory', 'eventName'). You can find available standard dimensions using the get_dimensions tool, and custom dimensions using get_custom_dimensions_and_metrics.
    • metrics – List of the quantitative measurements you want to analyze (for example, 'activeUsers', 'sessions', 'conversions', or 'totalRevenue'). You can find available standard metrics using the get_metrics tool, and custom metrics using get_custom_dimensions_and_metrics.
    • (Optional) dimensionFilter – Lets you filter your report based on specific dimension values. For example, you can filter to only include data from a certain country, device, or for specific events. This uses a structured filter expression.
    • (Optional) metricsFilter – Lets you filter your report based on specific metric values. For example, you can filter to only include data where sessions are greater than 100 or revenue is within a certain range. This also uses a structured filter expression.
    • (Optional) limit – The maximum number of rows you want to see in your report. This is useful for managing large datasets.
    • (Optional) offset – The starting row for your report, which helps you paginate through very large reports.
    • (Optional) currencyCode – The currency code (for example, "USD", "EUR") to use for any currency values in the report. If you leave this empty, the report uses your property's default currency.
    • (Optional) returnPropertyQuota – If set to True, the response will include information about your Google Analytics property quota usage.
    • (Optional) orderBys – Specifies how you want to sort the results of your report. You can sort by dimensions or metrics, in ascending or descending order (for instance, sort by 'sessions' in descending order).
  • Example prompts
    • Show me the active users and sessions for the last 30 days.
    • What were the top 5 countries for conversions last month?
    • How many purchases did we have in Q3 2024, broken down by device category?
    • Compare the bounce rate and average session duration between August and July 2025.
    • Give me a report on event counts for 'add_to_cart' and 'purchase' events, but only for users coming from 'google / cpc'.

Troubleshoot connection configuration issues

Cannot locate the GA4 project ID within gcloud CLI when running gcloud init before the ADC authentication command.
Choose Create a new project by entering the corresponding row number. Enter the GA4 project ID retrieved from the Google Cloud Console. Enter y to continue.

Received warning after running gcloud ADC authentication command: Cannot add the project "[projectID]" to ADC as the quota project because the account in ADC does not have the "serviceusage.services.use" permission on this project. You might receive a "quota_exceeded" or "API not enabled" error. Run $ gcloud auth application-default set-quota-project to add a quota project.
Ensure the user setting up ADC authentication has been assigned a role that grants them serviceusage.services.use permissions for the GA4 project.

Received "Authentication failed: Access forbidden (403)" error in OCP when setting up ADC authentication.
Ensure the user setting up ADC authentication has been assigned a role that grants them serviceusage.services.use permissions for the GA4 project.

Opal is "Already registered from another OCP account" for GA4.
This error means that the tool was already added to Opal from another OCP instance, or the tool registry in Opal was not cleaned up properly when the app was uninstalled.

  • If the tool was added to Opal from another OCP instance, an OCP administrator must go to the other OCP instance, then go to Google Analytics 4 app > Settings > Add to Opal and click Remove from Opal.
  • If the tool was not cleaned up properly, an Opal administrator must go to Opal > Tools > Registries > GA4 > ... and click Delete.

If you use Opti ID, administrators can turn off generative AI in the Opti ID Admin Center. See Turn generative AI off across Optimizely applications.