Google Analytics (GA4) connector tools

  • Updated

The Google Analytics 4 (GA4) connector tools in Optimizely Opal let you query and visualize the web traffic data tracked in GA4 directly from Opal. Use them to monitor live visitors, compare conversion funnels, or break down traffic sources without leaving Opal. To enable the tools, an Optimizely Connect Platform (OCP) administrator installs the app, authenticates it against GA4, and registers it with Opal. When registration is complete, you authenticate to Opal individually so the GA4 connector tools return only the data your Google account is permitted to view.

If you previously used a service account or Application Default Credentials (ADC), your existing installation continues to work. To migrate, uninstall the GA4 Opal app in the OCP App Directory and complete the steps in this article. The new flow uses Google OAuth and supports multiple GA4 properties.

Install Google Analytics 4 Opal

In the OCP App Directory, complete the following steps:

  1. Click Google Analytics 4 Opal.

    screenshot of OCP App Directory with the Google Analytics 4 Opal tile highlighted
  2. Click Install App.

Configure the Google Analytics settings

After installing the GA4 app, configure it in OCP. The configuration has three main parts that most organizations follow: add the GA4 properties Opal queries, optionally set a default domain filter, and register the connector tools with your Opal instance. Only follow the Override the OAuth provider section if your organization requires it.

Override the OAuth provider (optional)

This section is to manage your own OAuth provider and is not common. Most administrators can skip this section.

If your organization manages its own OAuth provider, see Configure instance-level Opal OAuth.

Configure GA4 properties

Add the GA4 properties you want Opal to access. You can add multiple properties and assign nicknames for easy identification.

  1. Go to the Settings tab.
  2. Expand the GA4 Properties section.
  3. (Optional) Enter a Nickname for the property. This makes it easier to find the property later.
  4. Enter the GA4 Property ID.

  5. Click Add Property.

    Screenshot of the GA4 Properties section with the Add Property button highlighted.
  6. Repeat steps 3–5 for each property you want to add.

Add a default filter (optional)

After adding your GA4 properties, you can optionally limit the data Opal queries to a single domain. Designate a default domain for queries when your GA4 property tracks multiple hostnames. Opal applies the default to every query that does not name a domain explicitly, and you can still target other domains from a prompt. Leave the field empty to query all tracked hostnames.

To set a default, complete the following:

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

  3. Click Save Filter.

    Screenshot of the Default filter section of the GA4 connector with the Save Filter button highlighted.

Next, register the GA4 connector tools in OCP.

Register the GA4 connector tools in OCP

After you install Google Analytics 4 Opal and configure the Google Analytics settings, complete the following steps in OCP to register it with your Opal instance:

  1. Click Settings > Add to Opal.

  2. Click Add to Opal for the Opal account where you want to host the GA4 connector tools.

    Screenshot of the GA4 connector tools with the Add to Opal section expanded with the Add to Opal button highlighted.

Click Remove from Opal to disconnect the tools from your Opal account.

Authenticate with Google

After an OCP administrator installs the GA4 Opal app in OCP and registers the GA4 connector tools, log in to Google from Opal to access your GA4 data. The connector tools authenticate each Opal user individually, so you only see GA4 data your Google account is already permitted to view.

To authenticate, complete the following steps in Opal:

  1. Go to Tools > Connectors.
  2. Click Connect on the Google Analytics 4 tile.
  3. Log in to Google.

After you authenticate, the GA4 connector tools become available in Opal Chat, agents, and workflows.

GA4 connector tools

After an OCP administrator installs and registers the GA4 connector tools and you authenticate with Google in Opal, you can call the following tools in Opal.

The GA4 connector tools are Opal-native tools that translate your prompts into GA4 Data API queries. Use them in chat, agents, and workflows to monitor live traffic, build funnel reports, look up dimensions and metrics, and generate historical reports without leaving Opal.

Click a tool name to expand it and see when to use the tool, its required and optional parameters, and example prompts for calling 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_funnel_report – Runs a funnel report to visualize user journey steps and conversion rates. Use this tool to analyze how users progress through a defined sequence of steps and identify where they exit the flow.
  • When to use
    • Analyze how users move through a specific sequence of actions, such as a checkout or sign-up flow.
    • Identify drop-off points between steps in a user journey.
    • Compare funnel performance across devices, traffic sources, or other dimensions.
    • Measure conversion rates between key events, such as page views to purchases.
    • Understand what users do after completing or abandoning a funnel step.
  • Parameters
    • dateRanges – The time periods for the report. Accepts up to four date ranges. Supports relative values such as 30daysAgo or absolute dates such as 2025-01-01.
    • funnel – Defines the funnel steps. Each step requires a name and a filterExpression. Supports event filters (funnelEventFilter) and field filters (funnelFieldFilter), along with orGroup, andGroup, and notExpression combinations. Optional step properties include isDirectlyFollowedBy and withinDurationFromPriorStep.
    • (Optional) funnelBreakdown – Breaks down funnel results by a dimension, such as deviceCategory or country. Accepts an optional limit value (default is 5).
    • (Optional) funnelNextAction – Analyzes what users do after completing or abandoning a funnel step. Accepts a dimension such as eventName or pagePath, and an optional limit.
    • (Optional) segments – Defines user segments to compare funnel performance, such as mobile versus desktop users.
    • (Optional) dimensionFilter – Filters the entire funnel by a dimension value, such as country or device category.
    • (Optional) limit – Maximum number of rows to return. Accepts values between 1 and 100,000. Defaults to 10.
    • (Optional) returnPropertyQuota – Set to true to include Google Analytics property quota usage in the response.
  • Example prompts
    • Show me a funnel from page view to purchase over the last 30 days.
    • Analyze the checkout funnel (add to cart, begin checkout, and purchase) broken down by device type.
    • Where are users dropping off in the sign-up flow this month?
    • Compare the purchase funnel between mobile and desktop users.
    • Show me a funnel for organic visitors from first visit to session start to purchase.
    • What do users do after abandoning the checkout step?
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
    • See who is on your site right now, where they are coming from, and what they are doing.
    • Check if new events or tracking configurations are working correctly.
    • 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, or eventName). You can find available standard dimensions using the get_dimensions tool.
    • metrics – The quantitative measurements you want to analyze (for example, activeUsers, eventCount, or sessions). You can find available standard metrics using the get_metrics tool.
    • (Optional) dimensionFilter – Filters the report by dimension values (for example, a specific country or device category).
    • (Optional) metricsFilter – Filters the report by metric value (for example, sessions greater than 100).
    • (Optional) limit – The maximum number of rows to return in your report. Defaults to 10,000 when not specified.
    • (Optional) offset – The starting row for your report. Use it with limit to paginate through large reports.
    • (Optional) currencyCode – The currency code to use for currency values in the report (for example, USD, EUR). When this field is empty, the report uses the property's default currency.
    • (Optional) returnPropertyQuota – Set to true to include Google Analytics property quota usage in the response.
    • (Optional) orderBys – A list of objects that sort the report by dimensions or metrics 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
    • Examine user demographics, where they come from, and how they interact with your content.
    • Monitor conversions, revenue, event counts, and other important metrics.
    • Break down your reports by various dimensions like country, device, or traffic source.
    • See how your metrics and dimensions change over time.
  • Parameters

    • dateRanges (list of objects) – The time periods for your report. Each range needs a startDate and endDate, plus an optional name. Dates can be absolute (for example, 2025-01-01) or relative (for example, yesterday, 30daysAgo, today).

      If you use multiple date ranges, do not include dateRange in your dimensions list because 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, or 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 – Filters the report by dimension value using a structured filter expression (for example, a specific country, device, or event).
    • (Optional) metricsFilter – Filters the report by metric value using a structured filter expression (for example, sessions greater than 100 or revenue in a range).
    • (Optional) limit – The maximum number of rows you want to see in your report. Use it to manage large datasets.
    • (Optional) offset – The starting row for your report. Use it with limit to paginate through large reports.
    • (Optional) currencyCode – The currency code (for example, USD or 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 – Set to true to include Google Analytics property quota usage in the response.
    • (Optional) orderBys – Sorts the report by dimensions or metrics in ascending or descending order (for example, sort by sessions descending).
  • 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 July and August 2025.
    • Give me a report on event counts for add_to_cart and purchase events, but only for users coming from google / cpc.

Configure instance-level Opal OAuth

Configure this only if your organization manages its own OAuth provider. Most administrators can skip this section.

In the OCP App Directory, complete the following steps:

  1. Click the Settings tab of the Google Analytics 4 Opal tool.
  2. Expand the Google Analytics Settings section.
  3. Toggle Instance level Opal OAuth on if you want to use a custom Google Analytics authentication provider connection.
  4. Enter your Google Analytics Auth Provider ID.

  5. Click Save Settings.

    Screenshot of the Google Analytics tool in OCP with the Google Analytics Settings expanded with the Save Settings button highlighted.

Troubleshoot registration configuration issues

Already registered from another OCP account error in Opal when registering the GA4 connector tools.
Opal returns this error when the GA4 tools are already registered from another OCP instance, or when the previous registration was not removed before the OCP app was uninstalled.

  • If the tools were registered from another OCP instance, an OCP administrator opens that OCP instance, goes to Google Analytics 4 Opal > Settings > Add to Opal, and clicks Remove from Opal.

    Screenshot of the GA4 settings in OCP with the Remove from Opal highlighted.

  • If the previous registration was not removed, an Opal administrator goes to Opal > Tools > Registries > GA4, clicks More (…) for the GA4 entry, and clicks Delete.

    screenshot of Opal Tools Registries page with the GA4 entry's More menu expanded

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.