# Advanced Analytics Tracking

The tracking module listens to all Joinchat custom events and automatically sends them to **Google Analytics 4 (GA4)** and **Google Tag Manager (GTM)**. This enables comprehensive tracking of user interactions with the chat.

## Integration

### Google Analytics 4 (GA4)

If `gtag()` is available on the page, events are sent using:

```
gtag('event', action, {
  event_category: 'JoinChat',
  event_label: label,
  value: value
});
Code language: JavaScript (javascript)
```

### Google Tag Manager (GTM)

If `dataLayer` is available, events are sent with additional information:

- `action` (string): Action name (e.g., 'chat\_open', 'goto', 'input')
- `label` (string, optional): Descriptive event label

## Tracked Events

### Joinchat Events

#### Chat Open

**Event:** `joinchat:show`
**GA Action:** `chat_open`
**Label:** Trigger type ('button', 'auto', 'hover', 'url', etc.)

Fired when the chat window opens.

#### Chat Close

**Click on:** `.joinchat__close`
**GA Action:** `chat_close`

Fired when the user closes the chat window.

#### Button Click

**Click on:** `.joinchat__btn` inside `.joinchat__bubble`
**GA Action:** `button_click`
**Label:** Button text (max 100 characters)
**Value:** Link URL

Fired when a button inside chat bubbles is clicked.

#### Link Click

**Click on:** `<a>` inside `.joinchat__bubble`
**GA Action:** `link_click`
**Label:** Link text (max 100 characters)
**Value:** Link URL

Fired when a link inside chat bubbles is clicked.

#### Opt-in Toggle

**Event:** `joinchat:optin`
**GA Action:** `optin_toggle`
**Label:** 'accept' or 'reject'

Fired when the user toggles the opt-in checkbox.

### Chat Funnels Events

#### Goto (Option Selected)

**Event:** `joinchat:goto`
**GA Action:** `goto`
**Label:** Selected option text
**Value:** Step number

Fired when the user selects an option in the funnel.

#### Input (Field Filled)

**Event:** `joinchat:input`
**GA Action:** `input`
**Label:** `field_name (type)`

Fired when the user submits an input field.

**Additional type-specific events:**

- `input_email` - Label: field name
- `input_phone` - Label: field name

For `select` type fields, the selected value is also included in the label.

#### Link Option Clicked

**Event:** `joinchat:link`
**GA Action:** `option_link`
**Label:** `type: url` (type can be 'anchor', 'internal', 'external')

Fired when the user clicks a link-type option.

#### AI Agent Activated

**Event:** `joinchat:ai`
**GA Action:** `ai_agent`

Fired when control is passed to an AI agent.

#### Contact Options Shown

**Event:** `joinchat:contact`
**GA Action:** `contact_show`
**Label:** Contact mode ('default', 'custom', 'custom\_message')

Fired when contact options are displayed.

#### Submit Success

**Event:** `joinchat:submitSuccess`
**GA Action:** `submit_success`

Fired when data is successfully submitted to the server.

#### Submit Error

**Event:** `joinchat:submitError`
**GA Action:** `submit_error`
**Label:** Error message

Fired when server data submission fails.

#### Webhook Success

**Event:** `joinchat:webhookSuccess`
**GA Action:** `webhook_success`

Fired when a webhook call completes successfully.

#### Webhook Error

**Event:** `joinchat:webhookError`
**GA Action:** `webhook_error`
**Label:** Error message

Fired when a webhook call fails.

#### Funnel Load

**Event:** `joinchat:funnel`
**GA Action:** `funnel_load`
**Label:** Funnel ID (e.g., 'Funnel 2')

Fired when a specific funnel is loaded.

### Media Events

#### Video Play/Pause

**Event:** `joinchat:video`
**GA Action:** `video_play` or `video_pause`
**Label:** `service: video_id` (service can be 'youtube', 'vimeo')

Fired when an embedded video is played or paused.

### Support Agents Events

#### Expand Agents List

**Event:** `joinchat:expand_agents`
**GA Action:** `agents_expand`
**Label:** `X/Y online` (X agents online out of Y total)

Fired when the collapsed agents list is expanded.

## Configuration

Tracking is activated automatically when the file loads. No manual initialization required.

### Custom Data Layer

The script searches for the data layer in the following order:

1. `joinchat_obj.settings.data_layer` - Custom configuration
2. `window.gtm4wp_datalayer_name` - GTM4WP plugin for WordPress
3. `window.dataLayer` - Default data layer

### Custom Event Category

By default, all events use the 'JoinChat' category, but it can be customized via:

```
joinchat_obj.settings.event_category = 'MyCategory';
Code language: JavaScript (javascript)
```

## Compatibility

- **Google Analytics 4** (gtag.js)
- **Google Tag Manager** (dataLayer)
- Compatible with WordPress and GTM4WP plugin

## Requirements

- `window.joinchat_obj` must be defined
- At least one of the following must be available: 
    - `gtag()` function (Google Analytics 4)
    - `dataLayer` object (Google Tag Manager)

## Technical Notes

- The script runs in an IIFE (Immediately Invoked Function Expression) to avoid polluting the global scope
- Uses 'strict mode' for enhanced security
- All event listeners are registered on `document` to capture events from the entire application
- Text labels are limited to 100 characters to avoid excessively long data