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:
Click Google Analytics 4 Opal.
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.
Add the GA4 properties you want Opal to access. You can add multiple properties and assign nicknames for easy identification.
Go to the Settings tab.
Expand the GA4 Properties section.
(Optional) Enter a Nickname for the property. This makes it easier to find the property later.
Enter the GA4 Property ID.
Click Add Property.
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:
Click Settings > Default Filter.
Enter only the hostname in the Hostname Filter field. Do not include a protocol (for example, omit https://). For example, enter www.optimizely.com.
Click Add to Opal for the Opal account where you want to host the GA4 connector tools.
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:
Go to Connectors > Connectors.
Click Connect on the Google Analytics 4 tile.
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's name to expand it and learn when to use it, its required and optional parameters, and example prompts for calling the tool. If you do not provide a required parameter, Opal prompts you for it.
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.
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.
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.
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?
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.
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:
Click the Settings tab of the Google Analytics 4 Opal tool.
Expand the Google Analytics Settings section.
Toggle Instance level Opal OAuth on if you want to use a custom Google Analytics authentication provider connection.
Enter your Google Analytics Auth Provider ID.
Click Save Settings.
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.
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.
