JavaScript API: керування віджетом зі сторінки

Віджет надає один глобальний об’єкт: window.ReactiveChat. Усі команди викликаються як функція:

ReactiveChat('command', argument1, argument2);

Назви основних команд відповідають поширеним віджетам чату (boot, shutdown, open, identify, update, track …), щоб перехід потребував небагато роботи.

Черга до завантаження

Спочатку завантажувач створює ReactiveChat. До завантаження ядра ця версія записує кожен виклик у ReactiveChat.q; потім ядро опрацьовує список за порядком. Жоден виклик не губиться.

Якщо код може виконатися до тегу завантажувача, додайте перед ним:

window.ReactiveChat = window.ReactiveChat || function () {
  (window.ReactiveChat.q = window.ReactiveChat.q || []).push(arguments);
};

Звідси дві речі:

• До завантаження кожне значення повернення — undefined. Тому команди зі значенням повернення (getSession, isOpen, tour …) використовуйте після події ready (див. Події).
• Команда запускає завантаження. Кожна команда, крім boot, update, track та identify, одразу завантажує ядро (тригер command). Тому ранній identify нічого не коштує.

Команди ніколи не кидають винятків: помилка повертає undefined, невідома команда ігнорується (із data-rc-debug="true" з’являється в консолі).

ReactiveChat('on', 'ready', function () {
  var s = ReactiveChat('getSession');
  console.log('Visitor', s && s.visitorId);
});

Запуск і завершення

• boot (cfg?: object) — перший виклик задає конфігурацію з тими самими полями, що й атрибути тегу скрипту (camel case, наприклад { siteKey, locale, theme, position, brand }), та запускає. Кожен наступний приймає лише locale, theme, dnd, autoOpen, strings і position. Якщо boot немає в черзі, ядро викликає його саме.
• shutdown () — видаляє віджет із цієї сторінки (вікно, з’єднання, спостерігачі) і повертає ReactiveChat до звичайної черги. Повторний запуск без перезавантаження не передбачено.

ReactiveChat('boot', { locale: 'en', theme: 'dark' });

Вікно

• open (opts?) — відкриває вікно. opts — елемент (вікно поруч) або об’єкт:
• anchor (елемент, необов’язковий) — відкрити поруч; без нього — звичайна позиція.
• message (рядок, необов’язковий) — вписати текст у поле, не надсилати (до 200 символів).
• tab (msg | home | help, необов’язковий) — вибрати вкладку. Якщо сам anchor містить data-rc-message або data-rc-tab, вони діють; явні значення виклику мають пріоритет. До завантаження запит запам’ятовується.
• close () — закриває вікно.
• toggle () — перемикає його.
• isOpen () → boolean.

document.querySelector('#hilfe').addEventListener('click', function (ev) {
  ReactiveChat('open', { anchor: ev.currentTarget, message: 'Question about my order', tab: 'msg' });
});

Повідомлення й розмови

• sendMessage (text: string) — надсилає від імені відвідувача, ніби він сам написав (ті самі ліміти, див. Ліміти). Лише після дії відвідувача, ніколи без неї.
• newConversation () — починає нову розмову.
• leaveMessage () — відкриває форму повідомлення, коли нікого немає.
• startConversation (text: string, suche?: string) — починає нову розмову й надсилає text після готовності. Використовується Smart Answer для продовження пошукового запитання в чаті.
• continueConversation (id: string, text: string) — продовжує наявну розмову з text (id за шаблоном [0-9A-Za-z_-]{1,64}, інакше починає нову). Також для передачі зі Smart Answer.

Відвідувачі й контекст

• identify ({ userId, email, name, userHash, exp }) — повідомляє користувача, що ввійшов. Інші поля відкидаються. Без дійсного userHash, обчисленого на сервері, користувач непідтверджений: ім’я й пошта з’являються в панелі, але нічого з цього не дає доступу до даних клієнтів чи чужої історії. Усе про підпис — Ідентифікація відвідувачів.
• update (attrs: object) — передає атрибути підключенню MousePlayer (лише якщо ви його використовуєте).
• track (name: string, meta?: object) — повідомляє етап. Поля meta зі списку контексту (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock та інші) йдуть асистенту й операторам як контекст сторінки. Решта відкидається. Див. Ідентифікація відвідувачів і передавання контексту.
• getSession () → { sessionId, visitorId, tabId } або null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } — звідки віджет підключається; для скриптів, яким потрібна та сама адреса.
• portal (basis?: string) → boolean — відкриває клієнтський портал у новій вкладці й передає підтверджену ідентифікацію. false, якщо підтвердженого користувача немає. basis — необов’язкове власне джерело з https:// в адресі.

ReactiveChat('track', 'produkt_angesehen', {
  page_type: 'product', product_id: 'SKU-4711', price: 49.9, currency: 'EUR', in_stock: true
});

Мова, тема

• setLocale (locale: 'de' | 'en' | 'pl') — перемикає мову; вибір запам’ятовується в браузері.
• setTheme ('light' | 'dark' | 'auto').

Підказка, промокартка, тури

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean — показує невелику хмаринку біля кнопки. quickReplies до 3, ttlMs 0–120000 (стандартно 15000). Не показується (false), якщо вікно відкрите, кнопку приховано, діє «Не турбувати», триває розмова або обмеження частоти.
• show (text | object) → boolean — коротка форма: ReactiveChat('show', 'Questions about shipping?').
• hideTeaser / hide () — приховує хмаринку.
• promo (false | true | object) — приховати промокартку на сторінці, показати знову або перевизначити власними полями (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean — запускає створений в обліковому записі тур; false для невідомого ID. Налаштування турів — Налаштування.
• tourStop () — завершує поточний тур.

A/B-тести

• abVariant () → { test, variant, qa } або null — варіант цього відвідувача.
• abGoal () — повідомляє досягнення цілі поточного тесту (наприклад на сторінці подяки).

ReactiveChat('on', 'ready', function () { ReactiveChat('abGoal'); });

Оформлення під час роботи

• setBrand (marke: object) — перевизначає кольори й форму без повторної побудови; null прибирає значення.
• brandCheck () → список виміряних контрастів { paar, ist, soll }.
• brandTokens () → визначені значення оформлення.
• setStart (startseite: object) — задає головний екран під час роботи (для попереднього перегляду).

Поля цих об’єктів описано в розділі Налаштування.

Події

• on (name, callback) / off (name, callback) — підписатися й відписатися від подій. Список і дані: Події.

Безпосередньо на об’єкті

Після завантаження деякі команди доступні як методи: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). Також ReactiveChat.version (версія ядра). До завантаження методів немає — функціональна форма безпечна.

Чого немає

Щоб ніхто не шукав даремно: команд destroy, reset, setUser, send, setConsent, trackPage або navigate немає. Згода керується платформою згоди або data-rc-consent (Інтеграція конфіденційності), переходи сторінками віджет визначає сам (SPA), вихід описано в Ідентифікації відвідувачів.

Далі: Події