API JavaScript: sterowanie widżetem z twojej strony

Widżet udostępnia jeden globalny obiekt: window.ReactiveChat. Wszystkie polecenia wywołujesz w formie funkcji:

ReactiveChat('polecenie', argument1, argument2);

Nazwy podstawowych poleceń nawiązują do popularnych widżetów czatu (boot, shutdown, open, identify, update, track …), żeby przesiadka wymagała mało pracy.

Kolejka przed załadowaniem

Loader tworzy ReactiveChat jako pierwszy. Dopóki rdzeń nie zostanie załadowany, ta wersja zapamiętuje każde wywołanie w ReactiveChat.q; rdzeń wykonuje potem tę listę po kolei. Żadne wywołanie nie przepada.

Jeśli twój kod może się wykonać przed tagiem loadera, wstaw przed nim tę linię:

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

Wynikają z tego dwie rzeczy:

• Przed załadowaniem każda wartość zwracana to undefined. Polecenia, które coś zwracają (getSession, isOpen, tour …), wywołuj więc po zdarzeniu ready (zobacz Zdarzenia).
• Polecenie wyzwala ładowanie. Każde polecenie poza boot, update, track i identify od razu ładuje rdzeń (wyzwalacz command). Wcześniejsze identify nic więc nie kosztuje.

Polecenia nigdy nie rzucają wyjątków: błąd w poleceniu daje undefined, nieznane polecenie jest ignorowane (z data-rc-debug="true" pojawia się w konsoli).

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

Start i zamknięcie

• boot (cfg?: object) – pierwsze wywołanie ustawia konfigurację z tymi samymi polami co atrybuty tagu script (camelCase, np. { siteKey, locale, theme, position, brand }) i uruchamia widżet. Każde kolejne wywołanie przejmuje już tylko locale, theme, dnd, autoOpen, strings i position. Jeśli w kolejce nie ma boot, rdzeń wywołuje je sam.
• shutdown () – usuwa widżet z tej strony (okno, połączenie, obserwatory) i przywraca ReactiveChat do postaci samej kolejki. Ponowne uruchomienie bez przeładowania strony nie jest przewidziane.

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

Okno

• open (opts?) – otwiera okno. opts to albo element (okno pojawia się obok niego), albo obiekt:
• anchor (element, opcjonalny) – otwórz obok tego elementu; bez niego: zwykła pozycja.
• message (String, opcjonalny) – wpisz tekst w pole wiadomości, nie wysyłaj (najwyżej 200 znaków).
• tab (msg | home | help, opcjonalny) – wybierz zakładkę. Jeśli sam anchor ma data-rc-message albo data-rc-tab, obowiązują one; wyraźne wartości w wywołaniu mają pierwszeństwo. Przed załadowaniem życzenie jest zapamiętywane.
• close () – zamyka okno.
• toggle () – przełącza.
• isOpen () → boolean.

document.querySelector('#hilfe').addEventListener('click', function (ev) {
  ReactiveChat('open', { anchor: ev.currentTarget, message: 'Pytanie o moje zamówienie', tab: 'msg' });
});

Wiadomości i rozmowy

• sendMessage (text: string) – wysyła wiadomość w imieniu odwiedzającego, tak jakby ją wpisał (obowiązują te same limity, zobacz Limity). Używaj tego tylko po działaniu odwiedzającego, nigdy bez pytania.
• newConversation () – zaczyna nową rozmowę.
• leaveMessage () – otwiera formularz wiadomości, gdy nikt nie jest dostępny.
• startConversation (text: string, suche?: string) – zaczyna nową rozmowę i wysyła text, gdy tylko jest gotowa. Używane przez Smart Answer, aby kontynuować pytanie z wyszukiwarki w czacie.
• continueConversation (id: string, text: string) – kontynuuje istniejącą rozmowę z text (id według [0-9A-Za-z_-]{1,64}, w przeciwnym razie zaczynana jest nowa). Również do przekazania ze Smart Answer.

Odwiedzający i kontekst

• identify ({ userId, email, name, userHash, exp }) – zgłasza zalogowanego użytkownika. Inne pola są odrzucane. Bez prawidłowego userHash, obliczonego na twoim serwerze, użytkownik uchodzi za niepotwierdzonego: imię i e-mail pojawiają się w panelu, ale nic z tego nie daje dostępu do danych klientów ani cudzych historii rozmów. Wszystko o podpisie w Identyfikacji odwiedzających.
• update (attrs: object) – przekazuje atrybuty do integracji z MousePlayerem (ma znaczenie tylko, jeśli używasz MousePlayera).
• track (name: string, meta?: object) – zgłasza kamień milowy. Pola w meta, które są na liście kontekstu (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock i in.), trafiają jako kontekst strony do asystenta i agentów. Inne pola są odrzucane. Zobacz Identyfikacja odwiedzających i przekazywanie kontekstu.
• getSession () → { sessionId, visitorId, tabId } albo null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – skąd widżet bierze swoje połączenie; dla własnych skryptów, które potrzebują tego samego adresu.
• portal (basis?: string) → boolean – otwiera portal klienta w nowej karcie i przekazuje przy tym potwierdzoną tożsamość. false, jeśli nie ma potwierdzonego użytkownika. basis to opcjonalnie własne pochodzenie https://.

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

Język, motyw

• setLocale (locale: 'de' | 'en' | 'pl') – zmienia język; wybór jest zapamiętywany w przeglądarce.
• setTheme ('light' | 'dark' | 'auto').

Teaser, karta promocyjna, przewodniki

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – pokazuje mały dymek przy launcherze. quickReplies najwyżej 3, ttlMs 0–120000 (domyślnie 15000). Nie jest pokazywany (false), gdy okno jest otwarte, launcher jest ukryty, obowiązuje „Nie przeszkadzać”, trwa rozmowa albo działa ograniczenie częstotliwości.
• show (text | objekt) → boolean – forma skrócona: ReactiveChat('show', 'Pytania o wysyłkę?').
• hideTeaser / hide () – ukrywa dymek.
• promo (false | true | objekt) – ukrywa lub ponownie pokazuje kartę promocyjną na tej stronie albo nadpisuje ją własnymi polami (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean – uruchamia przewodnik po produkcie utworzony w koncie; false przy nieznanym identyfikatorze. Przewodniki konfigurujesz w Dostosowaniu.
• tourStop () – kończy trwający przewodnik.

Testy A/B

• abVariant () → { test, variant, qa } albo null – wariant, który widzi ten odwiedzający.
• abGoal () – zgłasza, że cel trwającego testu został osiągnięty (np. na stronie z podziękowaniem).

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

Wygląd w czasie działania

• setBrand (marke: object) – nadpisuje kolory i kształt bez ponownego budowania; null usuwa wartość.
• brandCheck () → lista zmierzonych kontrastów { paar, ist, soll }.
• brandTokens () → rozwiązane wartości wyglądu.
• setStart (startseite: object) – ustawia stronę startową w czasie działania (do podglądów).

Pola tych obiektów opisuje Dostosowanie.

Zdarzenia

• on (name, callback) / off (name, callback) – subskrybowanie i anulowanie subskrypcji zdarzeń. Lista i dane: Zdarzenia.

Bezpośrednio na obiekcie

Po załadowaniu niektóre polecenia są dostępne także jako metody: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). Do tego ReactiveChat.version (wersja rdzenia). Przed załadowaniem tych metod nie ma – forma funkcji jest bezpieczną drogą.

Czego nie ma

Żeby nikt tego nie szukał: nie ma poleceń destroy, reset, setUser, send, setConsent, trackPage ani navigate. Zgodą sterujesz przez swoją platformę zgód albo data-rc-consent (Ochrona danych), zmiany stron widżet rozpoznaje sam (SPA), wylogowanie opisuje Identyfikacja odwiedzających.

Dalej: Zdarzenia