Webchat

La Webchat di Heres può essere inserita sulle proprietà web del cliente, ed utilizzata da applicazioni mobile tramite una webview.

Di seguito una guida su come integrare il widget Heres in una qualsiasi web page.

(function (H, e, r, es, B, o, t) {
       H["heres-widget"] = es;
       H[es] =H[es] || function () { (H[es].q = H[es].q || []).push(arguments);};
       (o = e.createElement(r)), (t = e.getElementsByTagName(r)[0]);
       o.id = es;H.heresAgent = B;
       o.src = "https://widgetv2.heres.ai/heres.js";
       o.async = 1;
       t.parentNode.insertBefore(o, t); 
})(window, document, "script", "heres", "NOMEAGENTE");

NOMEAGENTE è il nome dell’agente Heres, viene fornito da Heres al momento della attivazione

Per caricare il widget in versione testing utilizzare o.src= “https://widgetv2.heres.ai/testing/heres.js”

Lo script carica in modo asincrono lo script e predispone nel namespace globale la funzione heres, che diventa quindi accessibile tramite heres() o window.heres()

Questa funzione dà accesso alle API del widget, nello specifico:

Configurazione iniziale (oggetto configObject)

Tramite l’oggetto configObject è possibile passare parametri al bot:

initialStep: step iniziale (da concordare con i conversational designer)

externalId: id dell’utente

startOpen: se la chat si deve aprire da sola appena disponibile

heresIsMobileApp: se la chat è utilizzata da una mobile app, quindi si deve aprire in automatico e non deve essere possibile chiuderla.

… altri dati concordati con i conversational designer

Integrity:

È un campo di integrità, necessario per evitare attacchi di tipo Client Side Tampering, dove l’utente malintenzionato potrebbe modificare i dati in pagina per ottenere accesso a informazioni non disponibili. Prevede un controllo coordinato lato server di Heres, che consente la validazione delle informazioni, attraverso una chiave condivisa (PEPPER).

Viene calcolato in questo modo:

1. Viene preso l’oggetto configObject 
2. Vengono rimosse le chiavi botId, startOpen e integrity, oltre a tutte quelle il cui nome inizia per heres (es. heresIsMobileApp); i loro valori non devono essere conteggiati per il calcolo della integrity.
3. Vengono ordinate le chiavi in ordine alfabetico
4. Vengono estratti i valori, e concatenati con “|”
5. Viene calcolato SHA1 della stringa PEPPER + “|” + valori concatenati con “|” in formato hex
6. Vengono presi i primi 16 caratteri
7. Viene aggiunto il parametro integrity all’oggetto configObject.

Ad esempio, se il pepper condiviso è: Pb78432!ds

heres("init", {
    externalId: "matteo.ligabue@heres.ai",
    integrity: "d784db65429fb7f8"
})

Allora l’integrity verrà calcolata come:

integrity = sha1("Pb78432!ds|matteo.ligabue@heres.ai").substring(0,16)

// oppure usando il modulo built-in di node cryto
integrity = require("crypto")
  .createHash('sha1')
  .update("Pb78432!ds|matteo.ligabue@heres.ai")
  .digest('hex')
  .substring(0,16)

Mentre in questo altro esempio:

heres("init", {
    externalId: "rebecca.barbanti@heres.ai",
    integrity: "795c290f5285bba2"
})

avremo:

integrity = sha1("Pb78432!ds|rebecca.barbanti@heres.ai").substring(0,16)

// oppure usando il modulo built-in di node cryto
integrity = require("crypto")
  .createHash('sha1')
  .update("Pb78432!ds|rebecca.barbanti@heres.ai")
  .digest('hex')
  .substring(0,16)

Nota bene: la integrity è funzione solo del pepper e dei valori passati, non del tempo, quindi è possibile conservare in una cache i valori calcolati; se lo script viene invocato con gli stessi parametri extra, il valore della integrity sarà sempre lo stesso.

Caching dei dati

Normalmente i parametri passati al chatbot Heres tramite la funzione heres(‘init’, {}) vengono utilizzati per chiamate API server to server, quindi è fondamentale che tali informazioni (ad esempio la email) vengano passate allo script solo in casi legittimi; invitiamo a prestare particolare attenzione al caching di tali informazioni, per evitare disclosure di informazioni riservate tra utenti non collegati fra loro.

Messaggi provenienti dalla chat (ex dispatchEvent)

La chat può inviare alla pagina degli eventi, che vengono concordati insieme al reparto Conversational Design di Heres.

Tali eventi sono costituiti da un nome e da un payload (un oggetto Javascript) e sono inviati direttamente all’oggetto window del browser.

window.addEventListener('message', function (message) {});

Tali eventi possono essere catturati dalla pagina con codice tipo questo:

window.addEventListener('message', function (message) {
  if(message.data.type == "heres" ){
      // message.data.message contiene il nome del messaggio
      // message.data.payload contiene il payload del messaggio
  }
});

Per chi avesse implementato la vecchia logica di Heres, è sufficiente richiamare la funzione utilizzata nella precedente implementazione dentro al nuovo listener.

Ad esempio, se la funzione usata nella vecchia implementazione fosse stata chiamata dispatchHeres(eventName, eventPayload) allora basterebbe aggiungere questo snippet per avere retro compatibilità su questi eventi:

window.addEventListener('message', function (message) {
  if(message.data.type == "heres" ){
      dispatchHeres(message.data.message, message.data.payload)
  }
});

Nuova feature: Nascondi widget

Tramite la console di Heres, oltre a poter disabilitare il bot, è possibile anche nascondere completamente il widget dal sito.

Quando tale opzione è attiva, lo script non fa niente (non inietta niente nel DOM della pagina, non attiva nessun listener, ecc…) In pratica le chiamate alla funzione heres() non sortiscono nessun risultato.

Integrazione in mobile app

Per integrare la chat in una mobile app, la strategia è quella di utilizzare una webview.

La webview deve contenere lo script di inizializzazione e la chiamata alla funzione init.

E’ possibile passare alla funzione init il flag heresIsMobileApp valorizzato a true, questo flag fa si che la chat inizi aperta (come quando viene passato il flag startOpen) e alcuni elementi di interfaccia sono differenti (principalmente non compare la X di chiusura della chat e la voce di menu ‘Chiudi chat’

Se si vuole utilizzare la chat a tutto schermo, cioè nascondendo l’header di Heres (magari perchè la app già comprende header o strumenti di navigazione al di fuori della webview) è possibile inserire nel codice html della webview il seguente snippet, che interviene direttamente sullo stile del widget per massimizzare l’area della chat.

<style>
.heres_chat_panel .heres_iframe {
    position: absolute;
    width: 100% !important;
    height: 100% !important;
    top: 0px !important;
    left: 0px !important;
    z-index: 1000 !important;
}
.heres_home_btn {
    z-index: 1020 !important;
}
.heres_composer_shield {
    z-index: 1010 !important;
}
</style>