API JavaScript: controllare il widget dalla Sua pagina

Il widget fornisce un unico oggetto globale: window.ReactiveChat. Chiami tutti i comandi nella forma di funzione:

ReactiveChat('command', argument1, argument2);

I nomi dei comandi di base seguono quelli dei comuni widget di chat (boot, shutdown, open, identify, update, track …), così il passaggio richiede poco lavoro.

La coda prima del caricamento

Il caricatore crea prima ReactiveChat. Finché il nucleo non è caricato, questa versione registra ogni chiamata in ReactiveChat.q; il nucleo elabora poi l’elenco in ordine. Nessuna chiamata va persa.

Se il Suo codice può essere eseguito prima del tag del caricatore, anteponga questa riga:

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

Ne derivano due conseguenze:

• Prima del caricamento, ogni valore restituito è undefined. Usi quindi i comandi con valore di ritorno (getSession, isOpen, tour …) dopo l’evento ready (veda Eventi).
• Un comando attiva il caricamento. Ogni comando tranne boot, update, track e identify carica subito il nucleo (attivatore command). Chiamare identify in anticipo non costa quindi nulla.

I comandi non generano mai eccezioni: un errore in un comando produce undefined, un comando sconosciuto viene ignorato (con data-rc-debug="true" compare nella console).

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

Avvio e arresto

• boot (cfg?: object) – la prima chiamata imposta la configurazione con gli stessi campi degli attributi del tag script (camel case, ad esempio { siteKey, locale, theme, position, brand }) e avvia. Ogni chiamata successiva acquisisce solo locale, theme, dnd, autoOpen, strings e position. Se boot manca nella coda, il nucleo lo chiama autonomamente.
• shutdown () – rimuove il widget da questa pagina (finestra, connessione, osservatori) e reimposta ReactiveChat come semplice coda. Non è previsto riavviarlo senza ricaricare la pagina.

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

Finestra

• open (opts?) – apre la finestra. opts è un elemento (la finestra compare accanto a esso) oppure un oggetto:
• anchor (elemento, facoltativo) – apre accanto a questo elemento; senza: posizione normale.
• message (stringa, facoltativo) – inserisce testo nel campo di input, non lo invia (massimo 200 caratteri).
• tab (msg | home | help, facoltativo) – sceglie la scheda. Se anchor contiene data-rc-message o data-rc-tab, questi si applicano; i valori espliciti nella chiamata hanno la precedenza. Prima del caricamento la richiesta viene ricordata.
• close () – chiude la finestra.
• toggle () – ne alterna apertura e chiusura.
• isOpen () → boolean.

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

Messaggi e conversazioni

• sendMessage (text: string) – invia un messaggio a nome del visitatore, come se l’avesse digitato (valgono gli stessi limiti, veda Limiti). Lo usi solo dopo un’azione del visitatore, mai senza una sua iniziativa.
• newConversation () – avvia una nuova conversazione.
• leaveMessage () – apre il modulo per lasciare un messaggio quando nessuno è disponibile.
• startConversation (text: string, suche?: string) – avvia una nuova conversazione e invia text non appena è pronta. Usato da Smart Answer per proseguire una domanda di ricerca nella chat.
• continueConversation (id: string, text: string) – prosegue una conversazione esistente con text (id corrispondente a [0-9A-Za-z_-]{1,64}, altrimenti ne viene avviata una nuova). Usato anche per il passaggio da Smart Answer.

Visitatori e contesto

• identify ({ userId, email, name, userHash, exp }) – comunica un utente autenticato. Gli altri campi vengono scartati. Senza un userHash valido calcolato sul Suo server, l’utente è considerato non confermato: nome ed e-mail compaiono nel pannello, ma non concedono accesso ai dati dei clienti o alle cronologie di altre persone. Tutti i dettagli sulla firma sono in Identificare i visitatori.
• update (attrs: object) – passa attributi al collegamento MousePlayer (rilevante solo se usa MousePlayer).
• track (name: string, meta?: object) – segnala un evento rilevante. I campi di meta presenti nell’elenco del contesto (url, path, title, page_type, product_id, variant_id, category, price, currency, cart_value, cart_items, in_stock e altri) arrivano all’assistente e agli operatori come contesto della pagina. Gli altri vengono scartati. Veda Identificare i visitatori e trasmettere il contesto.
• getSession () → { sessionId, visitorId, tabId } o null.
• getEndpoint () → { siteKey, wsUrl, apiBase, locale, visitorId } – da dove il widget ricava la connessione; per i Suoi script che richiedono lo stesso indirizzo.
• portal (basis?: string) → boolean – apre il portale clienti in una nuova scheda e trasmette l’identità confermata. false se non c’è un utente confermato. basis è una Sua origine https:// facoltativa.

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

Lingua, tema

• setLocale (locale: 'de' | 'en' | 'pl') – cambia la lingua; la scelta viene ricordata nel browser.
• setTheme ('light' | 'dark' | 'auto').

Fumetto di invito, scheda promozionale, tour

• showTeaser ({ text, quickReplies?, replyRoles?, avatar?, ttlMs?, ruleId? }) → boolean – mostra un piccolo fumetto accanto al pulsante della chat. quickReplies massimo 3, ttlMs 0–120000 (predefinito 15000). Non viene mostrato (false) se la finestra è aperta, il pulsante della chat è nascosto, vale «Non disturbare», è in corso una conversazione o si applica una limitazione della frequenza.
• show (text | object) → boolean – forma breve: ReactiveChat('show', 'Questions about shipping?').
• hideTeaser / hide () – nasconde il fumetto.
• promo (false | true | object) – nasconde la scheda promozionale su questa pagina, la mostra di nuovo o la sostituisce con i Suoi campi (titel, text, bild, knopf, ziel, link_text, link_ziel, farbe, orte, zielgruppe).
• tour (id: string) → boolean – avvia un tour del prodotto creato nell’account; false per un ID sconosciuto. I tour si configurano in Personalizzazione.
• tourStop () – termina il tour in corso.

Test A/B

• abVariant () → { test, variant, qa } o null – la variante vista dal visitatore.
• abGoal () – segnala che è stato raggiunto l’obiettivo del test in corso (ad esempio sulla pagina di ringraziamento).

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

Aspetto durante l’esecuzione

• setBrand (marke: object) – sostituisce colori e forma senza ricompilare; null rimuove nuovamente un valore.
• brandCheck () → elenco dei contrasti misurati { paar, ist, soll }.
• brandTokens () → i valori di aspetto risolti.
• setStart (startseite: object) – imposta la schermata iniziale durante l’esecuzione (per le anteprime).

I campi di questi oggetti sono descritti in Personalizzazione.

Eventi

• on (name, callback) / off (name, callback) – si iscrive agli eventi e annulla l’iscrizione. Elenco e dati: Eventi.

Direttamente sull’oggetto

Dopo il caricamento, alcuni comandi sono disponibili anche come metodi: ReactiveChat.getSession(), ReactiveChat.isOpen(), ReactiveChat.getEndpoint(), ReactiveChat.startConversation(), ReactiveChat.continueConversation(). Inoltre, ReactiveChat.version (versione del nucleo). Questi metodi non esistono prima del caricamento: la forma di funzione è il modo sicuro.

Che cosa non esiste

Per evitare ricerche inutili: non esistono i comandi destroy, reset, setUser, send, setConsent, trackPage o navigate. Controlli il consenso tramite la piattaforma di consenso o data-rc-consent (Integrazione della protezione dei dati), il widget rileva autonomamente i cambi di pagina (SPA) e per uscire veda Identificare i visitatori.

Prosegua: Eventi