Google Analytics 4

BubblaV enables you to track user interactions with your AI chatbot and search widget directly in your Google Analytics 4 (GA4) dashboard. This integration allows you to see:

How many users open the chat or search widget.
What users are searching for (Search Queries).
How many messages are sent to the AI.
Which pages users are on when they interact.

Prerequisites

Before getting started, ensure you have:

A Google Analytics 4 property created.
The Google Analytics tracking script (gtag.js) OR Google Tag Manager snippet installed on the same page as your BubblaV widget.

Installation

The widget detects window.gtag (GA4) and window.dataLayer (GTM) on the page and sends events to them. You do not need to change the BubblaV widget snippet. For GTM, configure the event tags described below. This connection sends widget events to your analytics setup. It does not let Copilot read your GA4 reports. Copilot’s chat-volume and content-gap answers use BubblaV’s own data, not data from GA4.

The widget’s event forwarding does not currently check the integration’s dashboard connection state. Disconnecting Google Analytics in the dashboard does not stop these events. Manage event forwarding in your website’s analytics and tag configuration.

Message events include the message text and conversation ID. Review your analytics configuration and privacy requirements before forwarding chat content.

How it works

BubblaV loads on your page.
It checks for the existence of the Global Site Tag (gtag) or GTM Data Layer.
When a user interacts (e.g., opens chat), BubblaV pushes an event to the detected analytics instance.

Configuration

While events are sent automatically, you may want to configure Custom Definitions in GA4 to see granular data like “Search Query” in your reports.

Step 1: Check Real-time Data

To verify the integration is working:

Open your website and interact with the widget (open it, send a message).
Go to Google Analytics > Reports > Realtime.
Look for events named bubblav_chat_opened or bubblav_search_query in the Event Count card.

Step 2: Create Custom Dimensions (Optional)

To report on specific event parameters (like query or conversation_id), create custom dimensions:

Go to Admin > Data display > Custom definitions.
Click Create custom dimension.
Add the following dimensions:

Dimension Name	Scope	Event Parameter	Description
Search Query	Event	`query`	The text users typed into the search.
Widget Type	Event	`widget_type`	’chat’ or ‘search’.
Search Source	Event	`source`	’input’ or ‘suggestion’.
Conversation ID	Event	`conversation_id`	Unique ID of the chat session.

Google Tag Manager (GTM) Setup

If you use Google Tag Manager, BubblaV pushes events to the dataLayer. You need to create triggers to capture them.

Create a Trigger:
- Trigger Type: Custom Event
- Event Name: bubblav_.* (Use regex matching) OR specific names like bubblav_search_query.
Create Variables:
- Variable Type: Data Layer Variable
- Data Layer Variable Name: query (or other properties listed below).
Create a Tag:
- Go to Tags and click New.
- Click Tag Configuration and select Google Analytics: GA4 Event.
- Measurement ID: Enter your GA4 Measurement ID (e.g., G-XXXXXXXXXX) or select your Google Tag variable.
- Event Name: Enter {{Event}}. This dynamically passes the event name (e.g., bubblav_search_query) from the Data Layer to GA4.
- Event Parameters: Expand this section to send additional data:
  - Parameter Name: search_term (or match your GA4 Custom Dimension).
  - Value: Click the + icon and select the Data Layer Variable you created in Step 2 (e.g., {{dlv - query}}).
- Triggering: Click to select a trigger and choose the Custom Event trigger you created in Step 1.
- Save the tag and Submit/Publish your GTM container changes.

Event Reference

Chat Events

Event Name	Description	Trigger	Properties
`bubblav_chat_opened`	Chat Opened	User clicks the implementation bubble or calls `BubblaV.open()`.	`widget_type: 'chat'`
`bubblav_chat_closed`	Chat Closed	User minimizes the chat window.	`widget_type: 'chat'`
`bubblav_widget_expanded`	Widget Expanded	User expands the widget for a better view.	`widget_type: 'chat'`
`bubblav_widget_collapsed`	Widget Collapsed	User collapses the widget back to normal view.	`widget_type: 'chat'`
`bubblav_message_sent`	Message Sent	User sends a message to the AI.	`conversation_id`, `message_id`, `text`
`bubblav_message_received`	Message Received	User receives a response from the AI.	`conversation_id`, `message_id`, `text`
`bubblav_conversation_rated`	Conversation Rated	User rates the overall conversation.	`conversation_id`, `rating`
`bubblav_message_rated`	Message Rated	User rates a specific message (up/down).	`conversation_id`, `message_id`, `rating`

Search Events

Event Name	Description	Trigger	Properties
`bubblav_search_opened`	Search Opened	User clicks the search icon or calls `BubblaV.openSearch()`.	`mode` (e.g., ‘modal’, ‘inline’), `widget_type: 'search'`
`bubblav_search_closed`	Search Closed	User closes the search modal.	`mode`, `widget_type: 'search'`
`bubblav_search_query`	Search Query	User submits a search or clicks a suggestion.	`query`, `source`

Help Center Events

These events fire from the Help tab of the chat widget. See Help Center. All events also carry widget_type: 'chat' and site_id.

Event Name	Description	Trigger	Properties
`bubblav_help_center_opened`	Help Center Opened	Visitor opens the Help tab.	`widget_type: 'chat'`, `site_id`
`bubblav_help_center_closed`	Help Center Closed	Visitor leaves the Help tab for another tab.	`widget_type: 'chat'`, `site_id`
`bubblav_help_group_opened`	Help Group Opened	Visitor opens a group.	`group_id`, `group_title`
`bubblav_help_article_opened`	Help Article Opened	Visitor opens an article.	`article_id`, `article_title`, `article_type` (‘text’ or ‘link’), `entry_point` (‘browse’ or ‘search’)
`bubblav_help_search_query`	Help Search Query	Visitor presses Enter in the Help search box, or leaves the box, with a new non-empty query.	`query`, `results_count`
`bubblav_help_ask_clicked`	Help Ask Clicked	Visitor clicks the Ask a question button in the Help tab.	`widget_type: 'chat'`, `site_id`

Troubleshooting

Events not showing up?

Check Ad Blockers: Ensure your ad blocker isn’t blocking Google Analytics.
Wait: GA4 standard reports can take 24-48 hours to update. Use the Realtime report for testing.
Debug Mode: Install the “Google Analytics Debugger” Chrome extension to see events in the developer console.

Using a different analytics provider?

If you use Mixpanel, Amplitude, or others, you can manually listen to BubblaV SDK events and forward them:

window.BubblaV.on('search:query', (data) => {
  mixpanel.track('Site Search', {
    query: data.query
  });
});

Get Started

Chat Features

Grow & Improve

Account & Billing

Knowledge Setup

Integrations

Live Support

Reports

Prerequisites

Installation

How it works

Configuration

Step 1: Check Real-time Data

Step 2: Create Custom Dimensions (Optional)

Google Tag Manager (GTM) Setup

Event Reference

Chat Events

Search Events

Help Center Events

Troubleshooting

Events not showing up?

Using a different analytics provider?

​Prerequisites

​Installation

​How it works

​Configuration

​Step 1: Check Real-time Data

​Step 2: Create Custom Dimensions (Optional)

​Google Tag Manager (GTM) Setup

​Event Reference

​Chat Events

​Search Events

​Help Center Events

​Troubleshooting

​Events not showing up?

​Using a different analytics provider?

Prerequisites

Installation

How it works

Configuration

Step 1: Check Real-time Data

Step 2: Create Custom Dimensions (Optional)

Google Tag Manager (GTM) Setup

Event Reference

Chat Events

Search Events

Help Center Events

Troubleshooting

Events not showing up?

Using a different analytics provider?