JavaScript API: ovládání widgetu z vaší stránky

Widget poskytuje jediný globální objekt: window.ReactiveChat. Všechny příkazy voláte ve tvaru funkce:

ReactiveChat('command', argument1, argument2);

Názvy základních příkazů odpovídají běžným chatovacím widgetům (boot, shutdown, open, identify, update, track …), aby přechod vyžadoval málo práce.

Fronta před načtením

Načítací skript nejprve vytvoří ReactiveChat. Dokud se nenačte jádro, tato verze zaznamenává každé volání do ReactiveChat.q; jádro pak seznam zpracuje v pořadí. Žádné volání se neztratí.

Pokud se váš kód může spustit před značkou načítacího skriptu, přidejte před něj tento řádek:

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

Z toho vyplývají dvě věci:

• Před načtením je každá návratová hodnota undefined. Příkazy s návratovou hodnotou (getSession, isOpen, tour …) proto používejte po události ready (viz Události).
• Příkaz spouští načítání. Každý příkaz kromě boot, update, track a identify okamžitě načte jádro (spouštěč command). Včasné volání identify tedy nic nestojí.

Příkazy nikdy nevyhazují výjimky: chyba v příkazu vrátí undefined, neznámý příkaz se ignoruje (s data-rc-debug="true" se zobrazí v konzoli).

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

Spuštění a vypnutí

• boot (cfg?: object) – první volání nastaví konfiguraci se stejnými poli jako atributy značky script (camelCase, např. { siteKey, locale, theme, position, brand }) a spustí widget. Každé další volání převezme pouze locale, theme, dnd, autoOpen, strings a position. Pokud boot ve frontě chybí, jádro ho zavolá samo.
• shutdown () – odstraní widget z této stránky (okno, spojení, pozorovatele) a vrátí ReactiveChat na prostou frontu. Opětovné spuštění bez nového načtení stránky není zamýšlené.

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

Okno

• open (opts?) – otevře okno. opts je buď prvek (okno se zobrazí vedle něj), nebo objekt:
• anchor (prvek, volitelné) – otevřít vedle tohoto prvku; bez něj: běžná poloha.
• message (řetězec, volitelné) – vložit text do vstupního pole, nikoli ho odeslat (nejvýše 200 znaků).
• tab (msg | home | help, volitelné) – vybrat kartu. Pokud anchor sám obsahuje data-rc-message nebo data-rc-tab, použijí se; výslovné hodnoty ve volání mají přednost. Před načtením se požadavek zapamatuje.
• close () – zavře okno.
• toggle () – přepne stav okna.
• isOpen () → boolean.

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

Zprávy a konverzace

• sendMessage (text: string) – odešle zprávu jménem návštěvníka, jako by ji napsal sám (platí stejné limity, viz Limity). Používejte pouze po akci návštěvníka, nikdy bez vyžádání.
• newConversation () – zahájí novou konverzaci.
• leaveMessage () – otevře formulář pro zanechání zprávy, když nikdo není k dispozici.
• startConversation (text: string, suche?: string) – zahájí novou konverzaci a odešle text, jakmile je připravená. Používá Smart Answer k pokračování vyhledávací otázky v chatu.
• continueConversation (id: string, text: string) – pokračuje v existující konverzaci s text (id odpovídající [0-9A-Za-z_-]{1,64}, jinak se zahájí nová). Používá se také pro předání ze Smart Answer.

Návštěvníci a kontext

• identify ({ userId, email, name, userHash, exp }) – oznámí přihlášeného uživatele. Ostatní pole se zahodí. Bez platného userHash vypočítaného na vašem serveru se uživatel považuje za nepotvrzeného: jméno a e-mail se zobrazí v pultu, ale nic z toho neumožňuje přístup k zákaznickým datům ani k historii konverzací jiných lidí. Vše o podpisu je v části Identifikace návštěvníků.
• update (attrs: object) – předá atributy propojení s MousePlayer (relevantní pouze při používání MousePlayer).
• track (name: string, meta?: object) – oznámí milník. Pole v meta uvedená na seznamu kontextu (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock a další) jdou k asistentovi a operátorům jako kontext stránky. Ostatní pole se zahodí. Viz Identifikace návštěvníků a předávání kontextu.
• getSession () → { sessionId, visitorId, tabId } nebo null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – odkud widget získává spojení; pro vaše vlastní skripty, které potřebují stejnou adresu.
• portal (basis?: string) → boolean – otevře zákaznický portál na nové kartě a předá potvrzenou identitu. false, pokud není potvrzený uživatel. basis je volitelný vlastní https:// origin.

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

Jazyk, motiv

• setLocale (locale: 'de' | 'en' | 'pl') – přepne jazyk; volba se zapamatuje v prohlížeči.
• setTheme ('light' | 'dark' | 'auto').

Tooltipová bublina, reklamní karta, prohlídky

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – zobrazí malou bublinu u tlačítka chatu. quickReplies nejvýše 3, ttlMs 0–120000 (výchozí 15000). Nezobrazí se (false), pokud je okno otevřené, tlačítko chatu skryté, platí „Nerušit“, probíhá konverzace nebo platí omezení četnosti.
• show (text | object) → boolean – zkrácený tvar: ReactiveChat('show', 'Questions about shipping?').
• hideTeaser / hide () – skryje bublinu.
• promo (false | true | object) – skryje reklamní kartu na této stránce, znovu ji zobrazí nebo přepíše vlastními poli (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean – spustí prohlídku produktu vytvořenou v účtu; false pro neznámé ID. Prohlídky nastavíte v části Přizpůsobení.
• tourStop () – ukončí probíhající prohlídku.

A/B testy

• abVariant () → { test, variant, qa } nebo null – varianta, kterou tento návštěvník vidí.
• abGoal () – oznámí dosažení cíle probíhajícího testu (například na děkovací stránce).

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

Design za běhu

• setBrand (marke: object) – přepíše barvy a tvar bez nového sestavení; null hodnotu opět odstraní.
• brandCheck () → seznam naměřených kontrastů { paar, ist, soll }.
• brandTokens () → výsledné hodnoty designu.
• setStart (startseite: object) – nastaví úvodní obrazovku za běhu (pro náhledy).

Pole těchto objektů popisuje část Přizpůsobení.

Události

• on (name, callback) / off (name, callback) – přihlášení a odhlášení odběru událostí. Seznam a data: Události.

Přímo na objektu

Po načtení jsou některé příkazy dostupné i jako metody: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). Navíc ReactiveChat.version (verze jádra). Tyto metody před načtením neexistují – bezpečnou cestou je tvar funkce.

Co neexistuje

Aby nikdo nehledal: příkazy destroy, reset, setUser, send, setConsent, trackPage ani navigate neexistují. Souhlas řídíte přes svou platformu pro správu souhlasu nebo data-rc-consent (Integrace ochrany soukromí), změny stránek widget rozpoznává sám (SPA) a odhlášení popisuje Identifikace návštěvníků.

Dále: Události