Як використовувати Custom Code для віджету

Custom Code дозволяє додати кастомний JavaScript код, який виконується перед ініціалізацією віджету. Це корисно для інтеграції з третіми сторонами (Google Analytics, Intercom), модифікації параметрів віджету та створення глобальних helper функцій.

Що таке Custom Code?

Custom Code — це JavaScript код, який:

Виконується перед ініціалізацією Vue компонентів віджету
Має доступ до embed_state, kw_event(), kw_event_trigger()
Може модифікувати параметри віджету перед ініціалізацією
Підтримує Event Queue для обробки подій, що виникли до завантаження коду

Де налаштувати Custom Code?

Перейдіть в Налаштування → Боти → оберіть бота → Widget
Знайдіть розділ Custom Code
Введіть ваш JavaScript код
Збережіть налаштування

Доступні об'єкти

В Custom Code доступні:

embed_state — стан віджету перед ініціалізацією (можна модифікувати)
kw_event() — функція для виклику подій
kw_event_trigger() — функція для тригеру подій
window — глобальний об'єкт браузера

Модифікація параметрів віджету

Змініть параметри віджету перед ініціалізацією:

// Додати параметри на основі URL
embed_state.params_from_site = {
  ...embed_state.params_from_site,
  page_url: window.location.href,
  page_path: window.location.pathname,
  user_agent: navigator.userAgent
};

// Змінити заголовок на основі сторінки
if (window.location.pathname === '/products') {
  embed_state.title = 'Питання про товари';
  embed_state.subtitle = 'Наші консультанти допоможуть';
}

Інтеграція з Google Analytics

Відстежуйте події віджету в Google Analytics:

// Перевірка наявності Google Analytics
if (window.gtag) {
  // Відстеження відкриття чату
  window.addEventListener('widgetChatOpened', function() {
    window.gtag('event', 'widget_chat_opened', {
      event_category: 'Widget',
      event_label: 'Chat Opened'
    });
  });

  // Відстеження закриття чату
  window.addEventListener('widgetChatClosed', function() {
    window.gtag('event', 'widget_chat_closed', {
      event_category: 'Widget',
      event_label: 'Chat Closed'
    });
  });
}

Інтеграція з Intercom

Інтегруйте віджет з Intercom:

// Перевірка наявності Intercom
if (window.Intercom) {
  window.addEventListener('widgetChatOpened', function() {
    window.Intercom('trackEvent', 'widget-chat-opened');
  });
}

Використання Event Queue

Обробляйте події, що виникли до завантаження Custom Code:

// Встановити обробник подій
window.__kw_custom_handler_ready = true;

// Обробити накопичені події
if (window.__kw_event_queue && window.__kw_event_queue.length > 0) {
  window.__kw_event_queue.forEach(function(event) {
    // Ваша обробка події
    console.log('Обробка події:', event.event_name, event.event_data);
  });
  
  // Очистити чергу
  window.__kw_event_queue = [];
}

Створення helper функцій

Створіть глобальні функції для спрощення інтеграції:

// Створити helper функцію для відкриття чату з продуктом
window.openProductChat = function(productId, productName) {
  kw_event('kwsetparamsfromsite', {
    params_from_site: {
      product_id: productId,
      product_name: productName,
      action: 'product_inquiry'
    }
  });
  kw_event('command', {
    title: 'Питання про товар',
    subtitle: productName
  });
  kw_event('emitevent', {
    event: 'alias',
    alias: 'product-inquiry'
  });
  kw_event('openchat', 1);
};

// Використання на сайті
// <button onclick="openProductChat('12345', 'iPhone 15')">Запитати про товар</button>

Динамічна конфігурація на основі URL

Налаштуйте віджет залежно від поточної сторінки:

// Аналіз URL та зміна конфігурації
const path = window.location.pathname;
const searchParams = new URLSearchParams(window.location.search);

// Зміна заголовка залежно від сторінки
if (path.startsWith('/products')) {
  embed_state.title = 'Питання про товари';
} else if (path.startsWith('/support')) {
  embed_state.title = 'Технічна підтримка';
} else {
  embed_state.title = 'Допомога';
}

// Додавання параметрів з URL
if (searchParams.has('utm_source')) {
  embed_state.params_from_site = {
    ...embed_state.params_from_site,
    utm_source: searchParams.get('utm_source'),
    utm_campaign: searchParams.get('utm_campaign')
  };
}

Обробка помилок

Custom Code обгортається в IIFE, тому помилки не ламають віджет:

try {
  // Ваш код
  if (window.someExternalService) {
    window.someExternalService.init();
  }
} catch (error) {
  console.error('Помилка в Custom Code:', error);
  // Помилка не вплине на роботу віджету
}

Обмеження

Код завантажується тільки якщо widget_custom_code: true та вказано engine_url при ініціалізації
Код виконується синхронно перед ініціалізацією Vue компонентів
Якщо параметр вже встановлений в kw('init', {...}), значення з embed_state може бути перезаписане
Рекомендується використовувати унікальні назви для глобальних функцій (з префіксом)