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:

joinchat_obj.settings.data_layer – Custom configuration
window.gtm4wp_datalayer_name – GTM4WP plugin for WordPress
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

Docs