Події віджета асистента в GA4: підключення за 10 хвилин

Якщо у вас на сайті вже стоїть віджет асистента CallAIder, ви можете дуже швидко почати відстежувати взаємодії користувача в GA4: відкриття/закриття віджета, старт сесії, повідомлення користувача та відповіді асистента.

У цій статті - проста інструкція без зайвої теорії: що саме відправляє віджет, який код додати на сайт і як переконатися, що події реально дійшли в аналітику.

Що віджет відправляє в браузер

Віджет диспатчить події в window як CustomEvent:

• назва браузерної події: callaider_widget_event
• основні дані лежать у event.detail

Базова структура така:

{
  eventName: 'callaider_chat_open',
  params: {
    assistant_shortcode: 'abc123',
    chat_mode: 'text'
  }
}

Які події ви отримаєте

Подія	Text-віджет	Voice-віджет	Що означає
callaider_chat_open	так	так	Користувач відкрив віджет
callaider_chat_close	так	так	Користувач закрив віджет
callaider_session_started	так	так	Сесію створено/відновлено
callaider_session_ended	так	так	Сесія завершилась
callaider_message_sent	так	ні	Користувач надіслав повідомлення
callaider_message_received	так	ні	Асистент надіслав відповідь

Важливо: у голосовому режимі (chat_mode = voice) події callaider_message_sent і callaider_message_received не відправляються.

Куди вставити код на сайті

Найкращий порядок у HTML:

1. Ініціалізація GA4 (gtag) або GTM контейнер.
2. Ваш listener для callaider_widget_event.
3. Embed-скрипт віджета CallAIder.

Це потрібно, щоб не пропустити перші події, які можуть прилетіти одразу після ініціалізації віджета.

Крок 1. Перевірте події в Console

Спочатку переконайтесь, що браузер дійсно отримує події:

<script>
window.addEventListener('callaider_widget_event', function (e) {
  console.log('[Callaider Event]', e.detail);
});
</script>

Після відкриття віджета ви маєте бачити в Console об’єкти на кшталт:

• eventName: 'callaider_chat_open'
• eventName: 'callaider_session_started'
• eventName: 'callaider_message_sent'
• eventName: 'callaider_message_received'

Крок 2. Передайте події в GA4 через gtag

Якщо у вас вже підключений gtag, достатньо цього listener:

<script>
window.addEventListener('callaider_widget_event', function (e) {
  var d = e.detail || {};
  if (!d.eventName) return;

  if (typeof window.gtag === 'function') {
    window.gtag('event', d.eventName, d.params || {});
  }
});
</script>

Що отримає GA4:

• назву події з d.eventName
• параметри з d.params (наприклад, assistant_shortcode, chat_mode, session_id, trigger)

Крок 3. Або передайте події через GTM (dataLayer)

Якщо ви працюєте через Google Tag Manager:

<script>
window.dataLayer = window.dataLayer || [];

window.addEventListener('callaider_widget_event', function (e) {
  var d = e.detail || {};
  if (!d.eventName) return;

  window.dataLayer.push(Object.assign({
    event: d.eventName
  }, d.params || {}));
});
</script>

Далі у GTM можна зробити:

• Custom Event trigger з назвою подій callaider_*
• GA4 Event tag, який бере назву події з {{Event}}
• передачу потрібних параметрів у GA4 Event Parameters

Детальний набір даних у params для кожної події

Нижче - точна структура payload, яку варто очікувати в event.detail.params.

Базові поля, які повторюються майже скрізь:

• assistant_shortcode (string) - shortcode асистента
• chat_mode (text або voice) - режим віджета
• trigger (string) - що спричинило подію

1) callaider_chat_open

Поле	Тип	Обов’язкове	Коментар
assistant_shortcode	string	так	Ідентифікатор асистента
chat_mode	text | voice	так	Режим віджета
trigger	string	так	Наприклад launcher_button, auto_open, api

Приклад:

{
  "eventName": "callaider_chat_open",
  "params": {
    "assistant_shortcode": "abc123",
    "chat_mode": "text",
    "trigger": "launcher_button"
  }
}

2) callaider_chat_close

Поле	Тип	Обов’язкове	Коментар
assistant_shortcode	string	так	Ідентифікатор асистента
chat_mode	text | voice	так	Режим віджета
trigger	string	так	Наприклад close_button, widget_closed, api

Приклад:

{
  "eventName": "callaider_chat_close",
  "params": {
    "assistant_shortcode": "abc123",
    "chat_mode": "voice",
    "trigger": "close_button"
  }
}

3) callaider_session_started

Поле	Тип	Обов’язкове	Коментар
assistant_shortcode	string	так	Ідентифікатор асистента
chat_mode	text | voice	так	Режим віджета
session_id	string | null	так	ID сесії
trigger	string	так	Наприклад socket_ready, server_event
session_action	started | resumed	ні	Зазвичай у text-режимі

Приклад:

{
  "eventName": "callaider_session_started",
  "params": {
    "assistant_shortcode": "abc123",
    "chat_mode": "text",
    "session_id": "8d6c...",
    "trigger": "socket_ready",
    "session_action": "started"
  }
}

4) callaider_session_ended

Поле	Тип	Обов’язкове	Коментар
assistant_shortcode	string	так	Ідентифікатор асистента
chat_mode	text | voice	так	Режим віджета
session_id	string | null	так	ID сесії
close_reason	string	так	Причина завершення, наприклад user_ended
trigger	string	так	Наприклад client, socket_disconnect, session_error

Приклад:

{
  "eventName": "callaider_session_ended",
  "params": {
    "assistant_shortcode": "abc123",
    "chat_mode": "text",
    "session_id": "8d6c...",
    "close_reason": "user_ended",
    "trigger": "client"
  }
}

5) callaider_message_sent (тільки text)

Поле	Тип	Обов’язкове	Коментар
assistant_shortcode	string	так	Ідентифікатор асистента
chat_mode	text	так	Для цієї події завжди text
session_id	string | null	так	ID сесії
trigger	string	так	Зазвичай user_send
message_length	number	так	Довжина текстового повідомлення
files_count	number	так	Кількість вкладень
message_type	text_only | files_only | text_and_files	так	Тип повідомлення

Приклад:

{
  "eventName": "callaider_message_sent",
  "params": {
    "assistant_shortcode": "abc123",
    "chat_mode": "text",
    "session_id": "8d6c...",
    "trigger": "user_send",
    "message_length": 25,
    "files_count": 0,
    "message_type": "text_only"
  }
}

6) callaider_message_received (тільки text)

Поле	Тип	Обов’язкове	Коментар
assistant_shortcode	string	так	Ідентифікатор асистента
chat_mode	text	так	Для цієї події завжди text
session_id	string | null	так	ID сесії
trigger	string	так	Зазвичай assistant_response
message_length	number	так	Довжина відповіді асистента

Приклад:

{
  "eventName": "callaider_message_received",
  "params": {
    "assistant_shortcode": "0563d6ab5f97",
    "chat_mode": "text",
    "session_id": "006f4f87-fe6c-4015-898f-47fa4e07fc0a",
    "trigger": "assistant_response",
    "message_length": 27
  }
}

Типові значення trigger

Залежно від сценарію, найчастіше зустрічаються:

• launcher_button
• close_button
• auto_open
• api
• iframe_request
• socket_ready
• client
• server_event
• new_conversation
• user_send
• assistant_response
• widget_closed
• socket_disconnect
• session_error
• connect_error

Швидкий чеклист перед запуском

• callaider_widget_event видно в Console.
• Listener підключений до embed-скрипта віджета.
• gtag або GTM контейнер завантажується без помилок.
• Події видно в GA4 DebugView.
• У звітах є щонайменше callaider_chat_open і callaider_session_started.

Типові проблеми і як виправити

Подій немає в Console

Найчастіше причина в тому, що listener доданий занадто пізно або скрипт виконується з помилкою JavaScript. Перевірте порядок підключення і вкладку Console на помилки.

Події є в Console, але немає в GA4

Зазвичай це одна з причин:

• gtag не ініціалізований на сторінці,
• блокування трекінгу (consent/adblock),
• помилка в GTM тригері або тегу.

Є chat_open, але немає message_*

Це нормально для voice-режиму. Події повідомлень відправляються тільки для chat_mode = text.

Висновок

Інтеграція подій віджета асистента з GA4 займає кілька хвилин, але одразу дає вимірювану картину: скільки користувачів відкривають віджет, стартують сесію, пишуть повідомлення і отримують відповіді.

Як стартовий мінімум достатньо одного listener і 2-3 цільових подій у звітах. Далі можна поступово додавати сегменти, конверсії та порівняння між різними асистентами.