Skip to main content
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:
  1. A Google Analytics 4 property created.
  2. The Google Analytics tracking script (gtag.js) OR Google Tag Manager snippet installed on the same page as your BubblaV widget.

​
Installation

The BubblaV integration is zero-configuration on the code side, but requires activation in your dashboard.

​
1. Enable in Dashboard

To start tracking events, you must enable the integration for your website:
  1. Go to your Project Dashboard.
  2. Navigate to the Integrations tab.
  3. Locate Google Analytics 4 and click Connect.
  4. Confirm the activation.

​
2. Automatic Detection

Once enabled, the widget automatically detects if window.gtag (GA4) or window.dataLayer (GTM) is present on your website and begins dispatching events immediately. You do not need to add any extra code to the BubblaV widget snippet.

​
How it works

  1. BubblaV loads on your page.
  2. It checks for the existence of the Global Site Tag (gtag) or GTM Data Layer.
  3. 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:
  1. Open your website and interact with the widget (open it, send a message).
  2. Go to Google Analytics > Reports > Realtime.
  3. 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:
  1. Go to Admin > Data display > Custom definitions.
  2. Click Create custom dimension.
  3. Add the following dimensions:
Dimension NameScopeEvent ParameterDescription
Search QueryEventqueryThe text users typed into the search.
Widget TypeEventwidget_type’chat’ or ‘search’.
Search SourceEventsource’input’ or ‘suggestion’.
Conversation IDEventconversation_idUnique 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.
  1. Create a Trigger:
    • Trigger Type: Custom Event
    • Event Name: bubblav_.* (Use regex matching) OR specific names like bubblav_search_query.
  2. Create Variables:
    • Variable Type: Data Layer Variable
    • Data Layer Variable Name: query (or other properties listed below).
  3. 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 NameDescriptionTriggerProperties
bubblav_chat_openedChat OpenedUser clicks the implementation bubble or calls BubblaV.open().widget_type: 'chat'
bubblav_chat_closedChat ClosedUser minimizes the chat window.widget_type: 'chat'
bubblav_message_sentMessage SentUser sends a message to the AI.conversation_id, message_id

​
Search Events

Event NameDescriptionTriggerProperties
bubblav_search_openedSearch OpenedUser clicks the search icon or calls BubblaV.openSearch().mode (e.g., ‘modal’, ‘inline’), widget_type: 'search'
bubblav_search_closedSearch ClosedUser closes the search modal.mode, widget_type: 'search'
bubblav_search_querySearch QueryUser submits a search or clicks a suggestion.query, source

​
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
  });
});