> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bubblav.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Google Analytics 4

> Integrate BubblaV events with Google Analytics 4 (GA4) and Google Tag Manager (GTM).

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 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.

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 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`                                         |

## 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:

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