Як передати параметри з сайту до сценарію

Віджет ConnectiveOne дозволяє передавати параметри з вашого сайту до сценарію бота. Це корисно для передачі UTM-міток, ID користувача, даних про товар та іншого контексту.

Як працює передача параметрів?

1. Ви передаєте параметри через params_from_site при ініціалізації віджету
2. Параметри автоматично додаються до кожного повідомлення
3. Параметри доступні в сценарії через {{param_name}}

Передача параметрів при ініціалізації

Передайте параметри через params_from_site при ініціалізації віджету:

kw('init', {
  bot_id: 1,
  language_code: "uk",
  params_from_site: {
    utm_source: "widget",
    utm_campaign: "summer_sale",
    company_name: "TV123",
    user_id: "12345"
  }
});

У сценарії параметри доступні через плейсхолдери:

• {{utm_source}} → "widget"
• {{utm_campaign}} → "summer_sale"
• {{company_name}} → "TV123"
• {{user_id}} → "12345"

Зміна параметрів під час роботи

Ви можете змінити параметри під час роботи віджету:

kw_event('kwsetparamsfromsite', {
  params_from_site: {
    company_name: 'TV123123',
    page_url: window.location.href
  }
});

Важливо: Якщо передати порожній об'єкт params_from_site: {}, всі параметри будуть очищені.

Передача динамічних параметрів

Ви можете передавати параметри на основі поточної сторінки або дій користувача:

// Передача URL поточної сторінки
kw('init', {
  bot_id: 1,
  params_from_site: {
    page_url: window.location.href,
    page_title: document.title,
    referrer: document.referrer
  }
});

// Передача параметрів при кліку на кнопку
document.getElementById('product-btn').addEventListener('click', function() {
  kw_event('kwsetparamsfromsite', {
    params_from_site: {
      product_id: '12345',
      product_name: 'iPhone 15',
      action: 'product_inquiry'
    }
  });
  kw_event('openchat', 1); // Відкрити чат
});

Автоматичне додавання метаданих

За замовчуванням (recognize_user_meta увімкнено) до params_from_site додаються:

• user_agent — інформація про браузер
• ip_address — IP-адреса користувача (якщо вдалося отримати з сервісу; при помилці мережі інші поля все одно передаються)
• source_platform — тип середовища запуску чату: Web (браузер), Mobile App iOS або Mobile App Android (типовий WebView у застосунку). Якщо ви вже задали source_platform у params_from_site, автоматичне значення не перезаписує ваше.
• source_hostname — домен сторінки, де відкрито віджет (наприклад, shop.example.com). Визначається автоматично за адресою вбудовування; якщо ви вже задали source_hostname у params_from_site, автоматичне значення не перезаписує ваше.

Щоб вимкнути збір метаданих, встановіть recognize_user_meta: false.

Приклад (типовий випадок — додаткових параметрів не потрібно):

kw('init', {
  bot_id: 1,
  params_from_site: {
    utm_source: "widget"
  }
});

Під час відправки /start до params_from_site додадуться user_agent, ip_address, source_platform та source_hostname (за умови увімкненого recognize_user_meta). Ці дані доступні в операторській панелі; source_platform і source_hostname також потрапляють у статистику по діалогах каналу віджета — зручно, коли один бот встановлено на кількох сайтах.

Використання в сценарії

Після передачі параметрів вони доступні в сценарії через плейсхолдери:

Приклад блоку повідомлення:

Привіт! Ви зайшли з {{utm_source}}.
Ваша компанія: {{company_name}}

Приклад умови:

{
  "if": {
    "{{utm_source}}": {
      "widget": "process_widget_user",
      "facebook": "process_facebook_user",
      "default": "process_default_user"
    }
  }
}

Обмеження

• Параметри передаються в кожному повідомленні через поле constants як JSON string
• Якщо параметри не передані, params_from_site буде порожнім об'єктом
• Максимальний розмір параметрів обмежений налаштуваннями системи

Пов'язані статті

• Метрики статистики — довідник — поля source_platform та source_hostname у звітах
• Що таке віджет
• JavaScript API для керування віджетом
• Керування віджетом з сайту
• Обмін даними з виджетом