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) — первый вызов задаёт конфигурацию теми же полями, что атрибуты тега скрипта (camelCase, например { 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 (только если вы используете 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), о выходе — Идентификация посетителей.

Далее: События