Funzioni

Di seguito sono riportate le funzioni che è possibile configurare in Oracle Web SDK.

Indicatori temporali assoluti e relativi

Flag funzione: timestampMode: 'relative' | 'absolute' (impostazione predefinita: 'relative')
Configurazione funzioni: timestampMode

È possibile abilitare indicatori orari assoluti o relativi per i messaggi di chat. Gli indicatori orari assoluti visualizzano l'ora esatta per ogni messaggio. Gli indicatori orari relativi vengono visualizzati solo nel messaggio più recente ed esprimono l'ora in termini di secondi, giorni, ore, mesi o anni fa rispetto al messaggio precedente.
Descrizione di relative-v-absolute-timestamps.png segue
Descrizione dell'immagine relative-v-absolute-timestamps.png
La precisione I timestamp assoluti li rendono ideali per le attività di archiviazione, ma all'interno del contesto limitato di una sessione di chat, questa precisione riduce l'esperienza utente perché gli utenti devono confrontare i timestamp per scoprire il passaggio del tempo tra i messaggi. Gli indicatori orari relativi consentono agli utenti di tenere traccia facilmente della conversazione utilizzando termini quali Just Now e Pochi istanti fa che possono essere compresi immediatamente. Gli indicatori orari relativi migliorano l'esperienza dell'utente in un altro modo, semplificando allo stesso tempo le attività di sviluppo: poiché gli indicatori orari relativi contrassegnano i messaggi in termini di secondi, giorni, ore, mesi o anni fa, non è necessario convertirli per i fusi orari.

Come si comportano gli indicatori orari relativi

Come accennato in precedenza, un indicatore orario relativo viene visualizzato solo sull'ultimo messaggio. Ecco questo comportamento in un po' più di dettaglio. Quando si configura l'indicatore orario (timestampMode: 'relative' o timestampMode: 'default'), come intestazione viene visualizzato un indicatore orario assoluto prima del primo messaggio del giorno. Questa intestazione viene visualizzata quando la conversazione non è stata cancellata e i messaggi meno recenti sono ancora disponibili nella cronologia.

Segue la descrizione del first-message-day.png

Descrizione dell'illustrazione first-message-day.png

In ogni nuovo messaggio viene quindi visualizzato un indicatore orario relativo.
Segue la descrizione dell'ultimo messaggio timestamp.png

Descrizione dell'immagine most-recent-message-timestamp.png
Questo indicatore orario viene aggiornato a intervalli regolari (secondi, minuti e così via) successivi alla ricezione di un nuovo messaggio.

Per i primi 10 anni
Tra 10 e 60 anni
Ogni minuto tra 1m-60m
Ogni ora tra 1hr-24hr
Ogni giorno tra 1d-30d
Ogni mese tra 1m-12m
Ogni anno dopo il primo anno

Quando un nuovo messaggio viene caricato nella chat, l'indicatore orario relativo del messaggio precedente viene rimosso e sul nuovo messaggio viene visualizzato un nuovo indicatore orario che visualizza l'ora relativa al messaggio precedente. A quel punto, l'indicatore orario relativo viene aggiornato fino all'arrivo dei messaggi successivi.

Aggiungi un indicatore orario relativo

Per aggiungere un indicatore orario relativo, procedere come segue.

Abilita indicatori orari relativi - timestampMode: 'relative'

Passi facoltativi:

Impostare il colore per l'indicatore orario relativo - timestamp: '<a hexadecimal color value>'

Per le competenze multilingue, localizzare il testo dell'indicatore orario utilizzando i seguenti tasti:

Chiave	Testo predefinito	descrizione;
`relTimeNow`	`Now`	L'indicatore orario iniziale, visualizzato per i primi 9 secondi. Questo indicatore orario viene visualizzato anche quando la conversazione viene reimpostata.
`relTimeMoment`	`a few moments ago`	Viene visualizzata per 10-60 secondi.
`relTimeMin`	`{0}min ago`	Aggiornamenti ogni minuto
`relTimeHr`	`{0}hr ago`	Aggiornamenti ogni ora
`relTimeDay`	`{0}d ago`	Aggiornamenti ogni giorno per il primo mese.
`relTimeMon`	`{0}mth ago`	Aggiornamenti ogni mese per i primi dodici mesi.
`relTimeYr`	`{0}yr ago`	Aggiornamenti ogni anno.

Utilizzare le impostazioni timeStampFormat per modificare il formato dell'indicatore orario assoluto visualizzato prima del primo messaggio di ogni giorno.

Completamento automatico

Flag funzione: enableAutocomplete: true (impostazione predefinita: false)
Abilita inserimento nella cache lato client: enableAutocompleteClientCache

Il completamento automatico riduce al minimo l'errore dell'utente fornendo frasi efficaci che possono essere utilizzate sia come input diretto che come suggerimenti. Per abilitare questa funzione, aggiornare le impostazioni del widget con enableAutocomplete: true e aggiungere un set di messaggi utente ottimizzati alla pagina Crea intento. Una volta abilitato, un popup visualizza questi messaggi dopo che gli utenti hanno immesso tre o più caratteri. Le parole nei messaggi suggeriti che corrispondono all'input dell'utente vengono disattivate in grassetto. Da lì, gli utenti possono inserire il proprio input o optare per uno dei messaggi di completamento automatico.

Nota

Questa funzione è disponibile solo in WebSocket.

Descrizione di autocomplete-phrase-list.png:

Descrizione dell'immagine autocomplete-phrase-list.png

Quando un assistente digitale è associato al canale Web Oracle, tutte le espressioni di esempio configurate per le competenze registrate in tale assistente digitale possono essere utilizzate come suggerimenti di completamento automatico.

Sottomissione automatica di un campo

Quando la proprietà autoSubmit di un campo è impostata su true, il client invia un valore FormSubmissionMessagePayload con la mappa submittedField contenente i valori di campo validi immessi finora. I campi non ancora impostati (indipendentemente dal fatto che siano obbligatori) o che violino una convalida lato client non sono inclusi nella mappa submittedField. Se il campo inviato automaticamente contiene valori non validi, il messaggio di invio non viene inviato e viene visualizzato il messaggio di errore del client per quel particolare campo. Quando una sottomissione automatica riesce, partialSubmitField nel messaggio di invio del modulo verrà impostato su id nel campo autoSubmit.

Sostituzione di un form di input precedente

Quando l'utente finale invia il modulo, poiché autosubmit di un campo è impostato su true, la competenza può inviare un nuovo EditFormMessagePayload. Questo messaggio deve sostituire il precedente messaggio del modulo di input. Impostando la proprietà di estensione del canale replaceMessage su true, si abilita l'SDK a sostituire il messaggio del form di input precedente con il messaggio del form di input corrente.

Layout RTL automatico

Quando la direzione di base della pagina host è impostata su <html dir="rtl"> per ospitare le lingue da destra a sinistra (RTL), il widget chat viene visualizzato automaticamente sul lato sinistro. Poiché il widget è allineato a sinistra per le langaugine RTL, anche le relative icone ed elementi di testo vengono riposizionati. Le icone si trovano nelle posizioni opposte da dove si troverebbero in un rendering da sinistra a destra (LTR). Ad esempio, le icone di invio, microfono e allegato vengono capovolte in modo che il microfono e le icone di invio occupino il lato sinistro del campo di input (con l'icona di invio direzionale che punta a sinistra) mentre l'icona dell'allegato si trova sul lato destro del campo di input. L'allineamento degli elementi di testo, ad esempio inputPlaceholder e chatTitle, si basa sul fatto che la lingua del testo sia LTR o RTL. Per le lingue RTL, il testo inputPlaceHolder e chatTitle vengono visualizzati sul lato destro del campo di input.

Avatar

Per impostazione predefinita, nessuno dei messaggi nella chat è accompagnato da avatar. Utilizzando i seguenti parametri, tuttavia, è possibile configurare gli avatar per lo skill, l'utente e un avatar agente quando lo skill è integrato con il supporto dell'agente reale.

avatarBot: l'URL dell'origine dell'immagine o la stringa di origine dell'immagine SVG visualizzata accanto ai messaggi di skill.
avatarUser: l'URL dell'origine dell'immagine o la stringa di origine dell'immagine SVG visualizzata accanto ai messaggi utente. Inoltre, se lo skill dispone di un'integrazione agente reale, l'SDK può essere configurato per mostrare un'icona diversa per i messaggi agente.
avatarAgent: l'URL dell'origine dell'immagine o la stringa di origine dell'immagine SVG visualizzata accanto ai messaggi dell'agente. Se questo valore non viene fornito, ma è impostato avatarBot, viene utilizzata l'icona avatarBot.

Nota

Queste impostazioni possono essere passate solo nelle impostazioni di inizializzazione. Non possono essere modificati dinamicamente.

new WebSDK({
URI: '<URI>',
//...,
icons: {
    avatarBot: '../assets/images/avatar-bot.png',
    avatarUser: '../assets/images/avatar-user.jpg',
    avatarAgent: '<svg xmlns="http://www.w3.org/2000/svg" height="24" width="24"><path d="M12 6c1.1 0 2 .9 2 2s-.9 2-2 2-2-.9-2-2 .9-2 2-2m0 9c2.7 0 5.8 1.29 6 2v1H6v-.99c.2-.72 3.3-2.01 6-2.01m0-11C9.79 4 8 5.79 8 8s1.79 4 4 4 4-1.79 4-4-1.79-4-4-4zm0 9c-2.67 0-8 1.34-8 4v3h16v-3c0-2.66-5.33-4-8-4z"/></svg>'
}
})

Sincronizzazione conversazione tra schede

Flag funzione: enableTabsSync: true (impostazione predefinita: true)

Gli utenti potrebbero dover aprire il sito Web in più schede per vari motivi. Con enableTabsSync: true è possibile sincronizzare e continuare la conversazione dell'utente da qualsiasi scheda, purché i parametri delle connessioni (URI, channelId e userId) siano uguali in tutte le schede. Questa funzione garantisce che gli utenti possano visualizzare i messaggi dello skill in qualsiasi scheda e rispondere dalla stessa scheda o da qualsiasi altra scheda. Inoltre, se l'utente cancella la cronologia delle conversazioni in una scheda, viene eliminata anche dalle altre schede. Se l'utente aggiorna la lingua della chat in una scheda, la lingua della chat viene sincronizzata con le altre schede.

Esistono alcune limitazioni:

Una nuova scheda viene sincronizzata con le schede esistenti per i nuovi messaggi tra l'utente e lo skill all'apertura. Se l'SDK non è stato configurato per visualizzare i messaggi della cronologia delle conversazioni, il widget chat iniziale nella nuova scheda verrà visualizzato vuoto all'apertura.
Se l'SDK è stato configurato per visualizzare la cronologia delle conversazioni, i messaggi della chat corrente nelle schede esistenti verranno visualizzati come parte della cronologia delle conversazioni in una nuova scheda. L'impostazione di disablePastActions su all o postback può impedire l'interazione con le azioni per i messaggi nella nuova scheda.
Il browser Safari attualmente non supporta questa funzione.

Visualizzazione dei messaggi personalizzata

Flag funzione: delegate.render: (message) => boolean (default: undefined)

Utilizzare questa funzione per eseguire l'override del rendering predefinito dei messaggi con un modello di messaggio personalizzato. Per utilizzare questa funzione, è necessario implementare la funzione renderdelegate che accetta il modello di messaggio come input e restituisce un flag booleano come output. Deve restituire true per sostituire il rendering predefinito con il rendering personalizzato per un determinato tipo di messaggio. Se viene restituito false, viene invece visualizzato il messaggio predefinito.

Nota

Per il rendering personalizzato, tutta la gestione dei clic sulle azioni e la disabilitazione o l'abilitazione delle azioni devono essere gestite in modo esplicito.

È possibile utilizzare qualsiasi componente del framework esterno per il rendering dei messaggi. Fare riferimento agli esempi di integrazione inclusi nella directory samples dell'SDK per verificare come utilizzare questa funzione con framework quali React, Angular e Oracle JavaScript Extension Toolkit (JET).

Risposte client predefinite

Flag funzione: enableDefaultClientResponse: true (impostazione predefinita: false)

Utilizzare questo flag per fornire risposte predefinite sul lato client insieme a un indicatore di digitazione quando la risposta dello skill è stata ritardata o quando non vi è alcuna risposta dello skill. Se l'utente invia il primo messaggio o la prima query, ma lo skill non risponde entro il numero di secondi impostato dal flag defaultGreetingTimeout, lo skill può visualizzare un messaggio di saluto configurato mediante la stringa di traduzione defaultGreetingMessage. Successivamente, il client verifica nuovamente la risposta dello skill. Il client visualizza la risposta dello skill se è stata ricevuta, ma in caso contrario, visualizza un messaggio di attesa (configurato con la stringa di traduzione defaultWaitMessage) a intervalli impostati da defaultWaitMessageInterval. Quando l'attesa della risposta dello skill supera la soglia impostata dal flag typingIndicatorTimeout, il client visualizza una risposta spiacevole all'utente e interrompe l'indicatore di digitazione. È possibile configurare la risposta Sorry utilizzando la stringa di traduzione defaultSorryMessage.

Delega

Configurazione funzioni: delegate

La funzione di delega imposta un delegato per la ricezione di callback prima di determinati eventi nella conversazione. Per impostare un delegato, passare il parametro delegate o utilizzare il metodo setDelegate. L'oggetto delegato può facoltativamente contenere le funzioni delegate beforeDisplay, beforeSend, beforePostbackSend, beforeEndConversation e render.

var delegate = {
    beforeDisplay: function(message) {
        return message;
    },
    beforeSend: function(message) {
        return message;
    },
    beforePostbackSend: function(postback) {
        return postback;
    },
    beforeEndConversation: function(message) {
        return new Promise((resolve, reject) => {
            setTimeout(() => {
                resolve(message);
            }, 2000);
        });
    },
    render: function(message) {
        if (message.messagePayload.type === 'card') {
            // Perform custom rendering for card using msgId
            return true;
        }
        return false;
    }
}

beforeDisplay

Il delegato beforeDisplay consente di modificare il messaggio di uno skill prima che venga visualizzato nella conversazione. Il messaggio restituito dal delegato viene visualizzato al posto del messaggio originale. Il messaggio restituito non viene visualizzato se il delegato restituisce un valore falso come null, undefined o false. Se il delegato ha commesso errori, verrà visualizzato il messaggio originale al posto del messaggio restituito dal delegato. Utilizzare il delegato beforeDisplay per applicare in modo selettivo il comportamento di collegamento WebView nel widget.

beforeSend

Il delegato beforeSend consente di modificare un messaggio utente prima che venga inviato al server di chat nell'ambito di sendMessage. Il messaggio restituito dal delegato viene inviato allo skill anziché al messaggio originale. Il messaggio restituito dal delegato non viene impostato se il delegato restituisce un valore falso come null, undefined o false, quindi il messaggio non viene inviato. In caso di errore, il messaggio originale verrà inviato al posto del messaggio restituito dal delegato.

beforePostbackSend

Il delegato beforePostbackSend è simile a beforeSend, applicato solo ai messaggi di postback dell'utente. Il postback restituito dal delegato viene inviato allo skill. Se restituisce un valore falso, ad esempio null, undefined o false, non viene inviato alcun messaggio.

beforeEndConversation

Il delegato beforeEndConversation consente un'intercettazione alla fine di un flusso di conversazione se è necessario eseguire un'attività di pre-uscita. function riceve il messaggio di uscita come parametro di input e deve restituire un valore Promise. Se il valore Promise viene risolto con il messaggio di uscita, il messaggio di uscita CloseSession viene inviato al server chat. In caso contrario, verrà impedito l'invio del messaggio di uscita.

...

 beforeEndConversation: function(message) {
        return new Promise((resolve, reject) => {
            setTimeout(() => {
                resolve(message);
            }, 2000);
        });
    }

render

Il delegato render consente di eseguire l'override del rendering predefinito dei messaggi. Se la funzione di delega render restituisce true per un determinato tipo di messaggio, WebSDK crea uno slot segnaposto anziché il rendering predefinito del messaggio. Per identificare il segnaposto, aggiungere il msgId del messaggio come id dell'elemento. Nella funzione di delega render è possibile utilizzare questo identificativo per ottenere il riferimento per il segnaposto e visualizzare il modello di messaggio personalizzato. Vedere Rendering dei messaggi personalizzati.

Pulsante e widget di avvio trascinabili

Flag funzione: enableDraggableButton: true (impostazione predefinita: false)

A volte, in particolare sui dispositivi mobili in cui le dimensioni dello schermo sono limitate, il widget di chat o il pulsante di avvio possono bloccare il contenuto in una pagina Web. Impostando enableDraggableButton: true, è possibile consentire agli utenti di trascinare il widget o il pulsante di avvio quando la vista viene bloccata. Questo flag influisce solo sulla posizione del pulsante di avvio, non sul widget chat: il widget verrà comunque aperto dalla posizione originale.

Indicatore digitazione dinamica

Flag funzione: showTypingIndicator: 'true'

Un indicatore di digitazione indica agli utenti di sospendere l'invio di un messaggio perché lo skill sta preparando una risposta. Per impostazione predefinita, gli skill visualizzano l'indicatore di digitazione solo per la prima risposta quando si inizializza l'SDK con showTypingIndicator: 'true'. Per un'esperienza utente ottimale, lo skill deve avere un indicatore di digitazione dinamico, ovvero un indicatore di digitazione che viene visualizzato dopo ogni risposta dello skill. Oltre a rendere gli utenti consapevoli che l'abilità non è scaduta, ma sta ancora lavorando attivamente a una risposta, la visualizzazione dell'indicatore di digitazione dopo ogni risposta dell'abilità garantisce che gli utenti non tentino per inviare messaggi prematuramente, come potrebbe essere il caso in cui la proprietà keepTurn indirizzi la capacità di rispondere con una serie di messaggi separati che non consentono all'utente di inserire una risposta.

Per abilitare un indicatore di digitazione dopo ogni risposta skill:

Inizializzare l'SDK con showTypingIndicator impostato su true.
Chiamare l'API showTypingIndicator

showTypingIndicator può abilitare la visualizzazione dell'indicatore di digitazione dinamica solo quando:

Il widget è connesso al server di chat Oracle. L'indicatore di digitazione dinamica non viene visualizzato quando la connessione viene chiusa.
L'SDK è stato inizializzato con showTypingIndicator impostato su true.
Nota

Questa API non può funzionare quando l'SDK viene utilizzato in modalità headless.

L'indicatore di digitazione viene visualizzato per la durata impostata dalla proprietà facoltativa, typingIndicatorTimeout, con l'impostazione predefinita di 20 secondi. Se l'API viene richiamata mentre è già visualizzato un indicatore di digitazione, il timer viene reimpostato e l'indicatore viene nascosto.

L'indicatore di digitazione scompare non appena l'utente riceve i messaggi dello skill. L'indicatore di digitazione viene spostato nella parte inferiore della finestra di chat se un utente immette un messaggio, carica un allegato o invia una posizione durante la visualizzazione.

Comportamento collegamento incorporato controllo

Gestione personalizzata: linkHandler: { onclick: <function>, target: '<string>' }
Nella webview In-widget: linkHandler: { target: 'oda-chat-webview' }
In una nuova finestra: openLinksInNewWindow: 'true'

Oltre ad aprire i collegamenti all'interno di una nuova finestra impostando openLinksInNewWindow: true o il comportamento predefinito di apertura dei collegamenti in una nuova scheda, è anche possibile aprire collegamenti che sovrappongono la pagina Web del widget. Per abilitare questa e altre sostituzioni al funzionamento del collegamento, inizializzare il kit SDK con

linkHandler: {
    target: '_blank',   // open link in a new page
    onclick: (event) => { // some operation }
}

Utilizzare linkHander per:

Controllare la navigazione iframe in modo che possa continuare a sovrapporre la pagina senza dover includere il widget in ogni pagina, riaprirlo durante la navigazione e mantenere lo stesso ID utente.

Descrizione dell'immagine open-iframe.png
Apri alcuni link in una nuova finestra e altri nella stessa scheda.
Esecuzione di un'azione quando si fa clic su un collegamento.
Impedire l'apertura di un collegamento.
Apertura di un collegamento in una webview.

Per eseguire l'override del comportamento di collegamento impostato dall'impostazione openLinksInNewWindow, è necessario definire uno o entrambi i seguenti attributi:

self - Il contesto di navigazione corrente
target: assegna un nome al contesto della posizione di navigazione, ad esempio una scheda, una finestra o un iFrame. Definire la posizione iFrame come attributo target di un elemento di ancoraggio (<a>). È possibile definire gli attributi _self, _blank, _parent e _top della destinazione.
onclick: accetta una funzione di callback richiamata quando si fa clic sul collegamento. Il callback viene passato al MouseEvent ricevuto al clic e può essere utilizzato per eseguire un'azione o addirittura impedire l'apertura del collegamento.

Modalità incorporata

Flag funzione: embedded: true (impostazione predefinita: false)
Passare l'ID dell'elemento contenitore di destinazione: targetElement

Oltre alle altre impostazioni che personalizzano l'aspetto del widget che esegue la chat, è possibile incorporare il widget stesso nella pagina Web tramite:

Aggiunta di embedded: true.
Definizione della proprietà targetElement con l'ID dell'elemento DOM (un componente HTML) utilizzato come contenitore del widget (ad esempio 'container-div' nello snippet seguente).

<head>
    <meta charset="utf-8">
    <title>Oracle Web SDK Sample</title>
    <script src="scripts/settings.js"></script>
     <script>
        var chatWidgetSettings = {
            URI: YOUR_URI,
            channelId: YOUR_CHANNELID,
            embedded: true,
            targetElement: 'container-div'
...

    </script> 
</head>
<body>
    <h3 align="center">The Widget Is Embedded Here!</h3>
</body>
           <div id="container-div" 
                style="height: 600px; width: 380px; padding: 0; text-align: initial">
            </div>

Nota

Il widget occupa l'intera larghezza e l'altezza del contenitore. Se non può essere inserito dal contenitore, il widget non verrà visualizzato nella pagina.

Termina la sessione di conversazione

Flag funzione: enableEndConversation: true (impostazione predefinita: true)

A partire dalla versione 21.12, l'SDK aggiunge un pulsante di chiusura all'intestazione del widget chat per impostazione predefinita (enableEndConversation: true) che consente agli utenti di terminare la sessione corrente.

Dopo che gli utenti hanno fatto clic su questo pulsante, l'SDK presenta loro un prompt di conferma il cui testo ("Si è certi di voler terminare la conversazione? Questo cancellerà anche la cronologia delle conversazioni.") è possibile personalizzare con i tasti endConversationConfirmMessage e endConversationDescription. Quando un utente chiude il prompt facendo clic su Sì, l'SDK invia allo skill un messaggio di evento che contrassegna la sessione di conversazione corrente come terminata. L'istanza si disconnette quindi dallo skill, comprime il widget chat e cancella la cronologia delle conversazioni dell'utente corrente. Inoltre, genera un evento chatend per il quale è possibile registrarsi:

Bots.on('chatend', function() {
    console.log('The conversation is ended.');
});

L'apertura del widget chat determina l'avvio di una nuova sessione di conversazione.

Nota

È inoltre possibile terminare una sessione chiamando il metodo Bots.endChat() (descritto nel riferimento che accompagna l'Oracle Web SDK disponibile nella pagina Download). La chiamata a questo metodo può essere utile quando l'SDK viene inizializzato in modalità headless.

Focus sulla prima azione in un messaggio

Flag funzione: focusOnNewMessage: 'action' (impostazione predefinita: 'input')

Per gli utenti che preferiscono la navigazione basata su tastiera (che include gli utenti avanzati), è possibile spostare lo stato attivo dal campo di input utente al primo (o più a sinistra), pulsante di azione in un messaggio. Per impostazione predefinita, il widget chat imposta di nuovo lo stato attivo sul campo di input utente con ogni nuovo messaggio (focusOnNewMessage: 'input'). Questo funziona bene per i flussi di finestre di dialogo che prevedono un sacco di input testuali da parte dell'utente, ma quando il flusso di finestre di dialogo contiene un certo numero di messaggi con azioni, gli utenti possono selezionare queste azioni solo tramite il mousing o la navigazione inversa delle schede. Per questo caso d'uso, è possibile impostare lo stato attivo sul primo pulsante di azione del messaggio di skill ricevuto impostando focusOnNewMessage: 'action'. Se il messaggio non contiene azioni, il focus viene impostato sul campo di input dell'utente.

Collegamenti da tastiera e tasti di scelta rapida

Definendo l'oggetto hotkeys, è possibile creare collegamenti combinazione di tasti Alt che attivano o spostano lo stato attivo sugli elementi dell'interfaccia utente nel widget chat. Gli utenti possono eseguire questi collegamenti invece di utilizzare il mouse o i gesti touch. Ad esempio, gli utenti possono immettere Alt + L per avviare il widget di chat e Alt + C per comprimerlo. I tasti della tastiera vengono assegnati agli elementi utilizzando le coppie chiave-valore dell'oggetto hotkeys. Ad esempio:

var settings = {
    // ...,
    hotkeys: {
        collapse: 'c',  // Usage: press Alt + C to collapse the chat widget when chat widget is expanded
        launch: 'l'     // Usage: press Alt + L to launch the chat widget when chat widget is collapsed
    }
};

Quando si creano queste coppie chiave-valore:

Per una chiave è possibile passare solo una lettera o una cifra.
È possibile utilizzare come valori solo i tasti a-z e 0-9.

È possibile passare l'attributo dei tasti di scelta rapida definendo le chiavi seguenti.

Nota

Per l'attributo non viene fatta distinzione tra maiuscole e minuscole.

Chiave	Elemento
`clearHistory`	Il pulsante che cancella la cronologia delle conversazioni.
`close`	Pulsante che chiude il widget chat e termina la conversazione.
`collapse`	Pulsante che comprime il widget chat espanso.
`input`	Campo di input di testo nel piè di pagina della chat
`keyboard`	Pulsante che cambia la modalità di input da voce a testo.
`language`	Menu di selezione che mostra l'elenco di selezione della lingua.
`launch`	Pulsante di avvio del widget chat
`mic`	Pulsante che cambia la modalità di input da testo a voce.
`send`	Pulsante che invia il testo di input allo skill.
`shareMenu`	Pulsante del menu Condividi nel piè di pagina della chat
`shareMenuAudio`	La voce di menu nella finestra popup del menu di condivisione che seleziona un file audio da condividere.
`shareMenuFile`	La voce di menu nella finestra popup del menu di condivisione che seleziona un file generico da condividere
`shareMenuLocation`	Voce di menu nella finestra popup del menu di condivisione che seleziona la posizione utente per la condivisione.
`shareMenuVisual`	La voce di menu nella finestra popup del menu di condivisione che seleziona un'immagine o un file video da condividere.

SDK headless

Flag funzione: enableHeadless: true (impostazione predefinita: false)

Analogamente ai browser headless, l'SDK può essere utilizzato anche senza la relativa interfaccia utente. L'SDK mantiene la connessione al server e fornisce API per inviare messaggi, ricevere messaggi e ottenere aggiornamenti sullo stato della rete. È possibile utilizzare queste interfacce API per interagire con l'SDK e per aggiornare l'interfaccia utente. Per abilitare questa funzione, passare enableHeadless: true nelle impostazioni iniziali. La comunicazione può essere attuata come segue:

Invio di messaggi: chiama Bots.sendMessage(message) per passare qualsiasi payload al server.
Ricezione messaggi: le risposte possono essere ascoltate per l'utilizzo di Bots.on('message:received', <messageReceivedCallbackFunction>).
Recupera aggiornamento stato connessione: ascolta gli aggiornamenti sullo stato della connessione utilizzando Bots.on('networkstatuschange', <networkStatusCallbackFunction>). Il callback dispone di un parametro di stato aggiornato con valori compresi tra 0 e 3, ognuno dei quali è mappato agli stati WebSocket:
- 0 : WebSocket.CONNECTING
- 1: WebSocket.OPEN
- 2: WebSocket.CLOSING
- 3: WebSocket.CLOSED
- Restituisci suggerimenti per una query: restituisce una promessa che restituisce i suggerimenti per la stringa di query specificata. La promessa viene rifiutata se richiede troppo tempo (circa 10 secondi) per recuperare il suggerimento.
```
Bots.getSuggestions(utterance)
    .then((suggestions) => {
        const suggestionString = suggestions.toString();
        console.log('The suggestions are: ', suggestionString);
    })
    .catch((reason) => {
        console.log('Suggestion request failed', reason);
    });
```
Nota

Per utilizzare questa interfaccia API, è necessario abilitare autocomplete (
```
enableAutocomplete: true
```
) e configura il completamento automatico per gli intenti.

Chat multilingue

Il supporto del linguaggio nativo dell'SDK Web consente al widget chat di rilevare la lingua di un utente o di consentire agli utenti di selezionare la lingua della conversazione. Gli utenti possono passare da una lingua all'altra, ma solo tra le conversazioni, non durante una conversazione perché la conversazione viene reimpostata ogni volta che un utente seleziona una nuova lingua.

Abilita il menu Lingua

È possibile abilitare un menu che consente agli utenti di selezionare una lingua preferita da un menu a discesa definendo la proprietà multiLangChat con un oggetto contenente l'array supportedLangs, composto da tag di lingua (lang) ed etichette di visualizzazione facoltative (label). Al di fuori di questo array, è possibile impostare la lingua predefinita con la chiave primary (primary: 'en' nel seguente snippet).

multiLangChat: {
    supportedLangs: [{
        lang: 'en'
    }, {
        lang: 'es',
        label: 'Español'
    }, {
        lang: 'fr',
        label: 'Français'
    }, {
        lang: 'hi',
        label: 'हिंदी'
    }],
    primary: 'en'
}

Il widget chat visualizza le lingue supportate passate in un menu a discesa situato nell'intestazione. Oltre alle lingue disponibili, il menu include anche un'opzione Detect Language. Quando un utente seleziona una lingua da questo menu, la conversazione corrente viene reimpostata e viene avviata una nuova conversazione con la lingua selezionata. La lingua selezionata dall'utente persiste nelle varie sessioni dello stesso browser, pertanto la lingua precedente dell'utente viene selezionata automaticamente quando l'utente rivede la competenza nella pagina contenente il widget chat.

Suggerimento

È possibile aggiungere un listener di eventi per l'evento chatlanguagechange (descritto nel riferimento che accompagna Oracle Web SDK disponibile nella pagina Download), che viene attivato quando è stata selezionata una lingua di chat dal menu a discesa o è stata modificata.

Bots.on('chatlanguagechange', function(language) {
    console.log('The selected chat language is', language);
});

Di seguito sono riportate alcune cose da tenere a mente quando si configura il menu a discesa della lingua:

È necessario definire almeno due lingue per consentire la visualizzazione del menu a discesa.
Il tasto label è facoltativo per le lingue supportate in modo nativo: fr viene visualizzato come francese nel menu, es viene visualizzato come spagnolo e così via.
Le etichette per le lingue possono essere impostate in modo dinamico passando le etichette con l'impostazione i18n. È possibile impostare l'etichetta per qualsiasi lingua passandola alla relativa chiave language_<languageTag>. Questo pattern consente di impostare etichette per qualsiasi lingua, supportata o non supportata, nonché di tradurre l'etichetta stessa in impostazioni nazionali diverse. Ad esempio:
```
i18n: {
    en: {
        langauge_de: 'German',
        language_en: 'English',
        language_sw: 'Swahili',
        language_tr: 'Turkish'
    },
    de: {
        langauge_de: 'Deutsche',
        language_en: 'Englisch',
        language_sw: 'Swahili',
        language_tr: 'Türkisch'
    }
}
```
Se la proprietà i18n include stringhe di traduzione per la lingua selezionata, il testo per campi quali il segnaposto di input, il titolo della chat, il testo al passaggio del mouse per i pulsanti e i titoli della descrizione comandi passerà automaticamente alla lingua selezionata. Il testo del campo può essere cambiato solo in una lingua diversa quando sono presenti stringhe di traduzione per la lingua selezionata. Se non esistono stringhe di questo tipo, la lingua del testo del campo rimane invariata.
Il widget rileva automaticamente la lingua nel profilo utente e attiva l'opzione Detect Language se si omette il tasto primary.
Anche se label è facoltativo, se è stata aggiunta una lingua che non è una delle lingue supportate in modo nativo, è necessario aggiungere un'etichetta per identificare la tag, soprattutto quando non è presente una stringa i18n per la lingua. Ad esempio, se non si definisce label: 'हिंदी', per lang: hi, nell'elenco a discesa viene visualizzato hi, contribuendo a creare un'esperienza utente non ottimale.

Disabilita menu lingua

A partire dalla versione 21.12, è inoltre possibile configurare e aggiornare la lingua della chat senza dover configurare il menu a discesa di selezione della lingua passando multiLangChat.primary nella configurazione iniziale senza passare anche un array multiLangChat.supportedLangs. Il valore passato nella variabile primary viene impostato come lingua della chat per la conversazione.

Rilevamento della lingua

Oltre alle lingue passate, nel widget chat viene visualizzata l'opzione Detect Language nell'elenco a discesa. La selezione di questa opzione indica alla competenza di rilevare automaticamente la lingua della conversazione dal messaggio dell'utente e, quando possibile, di rispondere nella stessa lingua.

Nota

Se si omette il tasto primary, il widget rileva automaticamente la lingua nel profilo utente e attiva l'opzione Detect Language nel menu.

È possibile aggiornare dinamicamente la lingua selezionata richiamando l'API setPrimaryChatLanguage(lang). Se il valore lang passato corrisponde a una delle lingue supportate, viene selezionata tale lingua. Quando non è possibile trovare alcuna corrispondenza, viene attivata l'opzione Detect Language. È inoltre possibile attivare l'opzione Lingua rilevata richiamando l'API setPrimaryChatLanguage('und'), dove 'und' indica un valore non determinato o passando multiLangChat: {primary: null} o multiLangChat: {primary: 'und'}.

È possibile aggiornare la lingua della chat in modo dinamico utilizzando l'API setPrimaryChatLanguage(lang) anche quando il menu a discesa non è stato configurato. Ad esempio:

Bots.setPrimaryChatLanguage('fr')

È possibile aggiornare dinamicamente la lingua indipendentemente dal fatto che la lingua della chat sia stata inizialmente configurata o meno.

Nota

Il riconoscimento vocale, se configurato, è disponibile quando gli utenti selezionano una lingua supportata. Non è disponibile quando è impostata l'opzione Detect Language. La selezione di una lingua non supportata dal riconoscimento vocale disabilita la funzionalità di riconoscimento finché non viene selezionata una lingua supportata.

Guida di riferimento rapido per la chat multilingue

Questa operazione...	... Operazioni da eseguire
Visualizza l'elenco a discesa di selezione della lingua per gli utenti finali.	Passare `multiLangChat.supportedLangs`.
Impostare la lingua della chat senza visualizzare il menu a discesa di selezione della lingua per gli utenti finali.	Passare `multiLangChat.primary`.
Impostare una lingua predefinita.	Passare `multiLangChat.primary` con `multiLangChat.supportedLangs`. Il valore `primary` deve essere una delle lingue supportate che includono l'array.
Abilita rilevamento della lingua.	Passare `primary: null` o `primary: 'und'` con `multiLangChat`.
Aggiorna dinamicamente la lingua della chat.	Chiama l'API `setPrimaryChatLanguage(lang)`.

Webview in-Widget

È possibile configurare il funzionamento dei collegamenti nei messaggi di chat per consentire agli utenti di accedere alle pagine Web dal widget di chat. Invece di dover passare dalla conversazione per visualizzare una pagina in una scheda o in una finestra separata del browser, un utente può rimanere nella chat perché il widget chat apre il collegamento all'interno di una vista Web.

Configurare il funzionamento del collegamento alla vista Web

È possibile applicare la vista Web a tutti i collegamenti, o in un caso d'uso più tipico, per selezionare solo i collegamenti. È inoltre possibile personalizzare la webview stessa.

Per aprire tutti i collegamenti nella vista Web, passare linkHandler: { target: 'oda-chat-webview' } nelle impostazioni. In questo modo la destinazione di tutti i collegamenti viene impostata su oda-chat-webview, ovvero il nome del file iframe nella vista Web.
Per aprire solo determinati collegamenti nella vista Web e assicurarsi che altri collegamenti vengano aperti normalmente in altre schede o finestre, utilizzare il delegato beforeDisplay. Per aprire un'azione URL messaggio specifica nella vista Web, sostituire il valore 'url' del campo action.type con 'webview'. Quando il tipo di azione è 'webview' nella funzione beforeDisplay, il pulsante di azione apre il collegamento nella vista Web quando viene fatto clic.

Apri collegamenti dalla vista Web

I collegamenti incorporati in una pagina che viene visualizzata all'interno di WebView possono essere aperti solo all'interno di WebView quando vengono convertiti in un elemento di ancoraggio (<a>), con un attributo destinazione definito come target="oda-chat-webview".

Personalizzare il file WebView

È possibile personalizzare WebView con l'impostazione webViewConfig che accetta un oggetto. Ad esempio:

{ referrerPolicy: 'no-referrer-when-downgrade', closeButtonType: 'icon', size: 'tall'

I campi all'interno di questo oggetto sono facoltativi.

Nota

La configurazione può essere aggiornata in modo dinamico anche passando un oggetto webViewConfig nel metodo setWebViewConfig. Ogni proprietà nell'oggetto è facoltativa.

Campo	Valore	descrizione;
`accessibilityTitle`	Stringa	Nome dell'elemento frame WebView per Accessibilità Web.
`closeButtonIcon`	Stringa	La stringa URL/SVG dell'immagine utilizzata per visualizzare l'icona del pulsante Chiudi.
`closeButtonLabel`	Stringa	Etichetta di testo/titolo per il pulsante di chiusura.
`closeButtonType`	`'icon'` `'label'` `'iconWithLabel'`	Imposta la modalità di visualizzazione del pulsante Chiudi nel file WebView.
`referrerPolicy`	`ReferrerPolicy`	Indica il referente da inviare durante il recupero della risorsa del frame. Il valore del criterio `referrerPolicy` deve essere una direttiva valida. Il criterio predefinito applicato è `'no-referrer-when-downgrade'`.
`sandbox`	Array di stringhe	Una serie di stringhe di restrizione valide che consentono l'esclusione di determinate azioni all'interno del frame. Le limitazioni che è possibile passare a questo campo sono incluse nella descrizione dell'attributo `sandbox` in MDN Web Docs.
`size`	`'tall'` `'full'`	L'altezza del WebView rispetto all'altezza del widget di chat. Se impostato su `'tall'`, viene impostato come 80% dell'altezza del widget, se impostato su `'full'` equivale all'altezza del widget.
`title`	Stringa	Il titolo visualizzato nell'intestazione del contenitore WebView.

È possibile che non tutti i collegamenti si aprano all'interno di WebView. Di seguito sono riportati alcuni motivi.

Le pagine che forniscono l'intestazione di risposta X-frame-options: deny o X-frame-options: sameorigin potrebbero non essere aperte nel file WebView a causa di limitazioni lato server che impediscono l'apertura della pagina all'interno di iframes. In questi casi, WebView presenta il collegamento all'utente in modo che possa aprirlo in una nuova finestra o scheda.
A causa delle limitazioni lato server, le pagine di autorizzazione non possono essere aperte all'interno del file WebViews, poiché le pagine di autorizzazione restituiscono sempre X-frame-options: deny per impedire un attacco clickjacking.
Collegamenti esterni, che non possono essere aperti correttamente all'interno del WebView. Solo i collegamenti incorporati nei messaggi di conversazione possono essere aperti nel file WebView.
Nota

Poiché i messaggi esterni non sono compatibili con WebView, non impostare come destinazione alcun collegamento esterno da aprire in WebView.

Quando non è possibile aprire un collegamento in WebView, il widget presenta all'utente un testo informativo e un collegamento a WebView, che apre la pagina in una nuova scheda quando si fa clic su di esso. È possibile personalizzare questo testo utilizzando la stringa di traduzione webViewErrorInfoText i18n:

settings = {
    URI: 'instance',
    //...,
    i18n: {
        en: {
            webViewErrorInfoText: 'This link can not be opened here. You can open it in a new page by clicking {0}here{/0}.'
        }
    }
}

Polling lungo

Flag funzione: enableLongPolling: true (impostazione predefinita: false)

L'SDK utilizza WebSockets per connettersi al server e conversare con le competenze. Se per qualche motivo WebSocket è disabilitato sulla rete, le chiamate HTTP tradizionali possono essere utilizzate per chattare con la competenza. Questa funzione è nota come polling lungo perché l'SDK deve chiamare continuamente o eseguire il polling del server per recuperare i messaggi più recenti dall'abilità. Questa funzione di fallback può essere abilitata passando enableLongPolling: true nelle impostazioni iniziali.

Indicatore digitazione per conversazioni utente-agente

Flag funzione: enableSendTypingStatus: booleano (impostazione predefinita: false)

Questa funzione consente agli agenti di verificare se gli utenti sono ancora coinvolti nella conversazione inviando lo stato dell'utente all'agente reale. Quando enableSendTypingStatus è impostato su true, l'SDK invia un evento di stato di digitazione RESPONDING insieme al testo correntemente digitato dall'utente a Oracle B2C Service o Oracle Fusion Service. Questo, a sua volta, visualizza un indicatore di digitazione sulla console dell'agente. Al termine della digitazione, l'SDK invia un evento LISTENING al servizio per nascondere l'indicatore di digitazione sulla console dell'agente.

La configurazione typingStatusInterval, che ha un valore minimo di tre secondi, limita l'aggiornamento dello stato di digitazione.

Per inviare a un agente di Oracle B2C Service sia il testo digitato dall'utente che lo stato di digitazione, è necessario impostare enableAgentSneakPreview (che per impostazione predefinita è false) su true e abilitare l'anteprima in Configurazione della chat di Oracle B2C Service.

Nota

Non è necessario configurare lo stato di digitazione attiva sul lato utente. L'utente può visualizzare lo stato di digitazione dell'agente per impostazione predefinita. Quando l'agente digita, l'SDK riceve un messaggio di stato RESPONDING che comporta la visualizzazione di un indicatore di digitazione nella vista dell'utente. Analogamente, quando l'agente è inattivo, l'SDK riceve un messaggio di stato LISTENING che nasconde l'indicatore di digitazione.

Riconoscimento vocale

Flag funzione: enableSpeech: true (impostazione predefinita: false)

L'impostazione di enableSpeech: true consente di visualizzare il pulsante del microfono al posto del pulsante di invio ogni volta che il campo di input dell'utente è vuoto.

La tua abilità può anche utilizzare il riconoscimento vocale con il metodo startVoiceRecording(onSpeechRecognition, onSpeechNetworkChange) per avviare la registrazione e il metodo stopVoiceRecording per interrompere la registrazione. Questi metodi sono descritti nel Manuale dell'utente incluso nell'SDK.

Utilizzando il flag enableSpeechAutoSend è possibile configurare se inviare o meno il testo riconosciuto dalla voce dell'utente direttamente al server di chat senza alcun input manuale da parte dell'utente. Impostando questa proprietà su true (impostazione predefinita), si consente l'invio automatico al server di chat della risposta vocale dell'utente. Impostandolo su false, si consente all'utente di modificare il messaggio prima che venga inviato al server di chat o di eliminarlo.

Visualizzatore vocale

Configurazione funzioni: enableSpeechAutoSend

Il widget chat visualizza un visualizzatore vocale quando gli utenti fanno clic sull'icona vocale

, il widget chat visualizza un visualizzatore vocale. È un indicatore che indica se il livello audio è sufficientemente alto da consentire all'SDK di acquisire la voce dell'utente. Il messaggio dell'utente, riconosciuto come testo, viene visualizzato sotto il visualizzatore.

Nota

La modalità vocale è indicata quando viene visualizzata l'icona

della tastiera.

Segue la descrizione della voce visualizer.png

Descrizione dell'immagine voice-visualizer.png

Poiché l'impostazione predefinita per enableSpeechAutosend è true (enableSpeechAutoSend: true), i messaggi vengono inviati automaticamente dopo il riconoscimento. L'impostazione di enableSpeechAutoSend: false consente di impostare la modalità di input su testo dopo il riconoscimento del messaggio vocale, consentendo agli utenti di modificare o completare i messaggi utilizzando il testo prima di inviarli manualmente. In alternativa, gli utenti possono completare il messaggio con la voce tramite un successivo clic dell'icona vocale prima di inviarlo manualmente.

Nota

Il visualizzatore vocale viene creato utilizzando AnalyserNode. È possibile implementare il visualizzatore vocale in modalità senza intestazione utilizzando il metodo startVoiceRecording. Per ulteriori informazioni sui livelli di frequenza e AnalyserNode, vedere SDK.

Documentazione di Oracle Cloud Infrastructure