Documentation sur Oracle Cloud Infrastructure

Fonctions

Voici les fonctions que vous pouvez configurer dans la trousse SDK Oracle Web.

Horodatages absolus et relatifs

  • Indicateur de fonction : timestampMode: 'relative' | 'absolute' (par défaut : 'relative')
  • Configuration de fonction : timestampMode

Vous pouvez activer des horodatages absolus ou relatifs pour les messages de clavardage. Les horodatages absolus affichent l'heure exacte de chaque message. L'horodatage relatif s'affiche uniquement sur le dernier message et exprime le temps en secondes, jours, heures, mois ou années par rapport au message précédent.
Description de relatif-v-absolu-timestamps.png :
Description de l'illustration relative-v-absolute-timestamps.png
La précision Grâce aux horodateurs absolus, ils sont idéaux pour les tâches d'archivage, mais dans le contexte limité d'une session de clavardage, cette précision nuit à l'expérience utilisateur car les utilisateurs doivent comparer les horodateurs pour déterminer le temps écoulé entre les messages. Les horodatages relatifs permettent aux utilisateurs de suivre facilement la conversation grâce à des termes comme Just Now (À l'instant) et A few moments ago (Il y a quelques instants) qui peuvent être immédiatement compris. Les horodatages relatifs améliorent l'expérience utilisateur d'une autre manière tout en simplifiant vos tâches de développement : parce que les horodatages relatifs marquent les messages en secondes, jours, heures, mois ou années, vous n'avez pas besoin de les convertir pour les fuseaux horaires.

Comportement des horodatages relatifs

Comme mentionné précédemment, un horodatage relatif n'apparaît que sur le dernier message. Voici une description plus détaillée de ce comportement. Lorsque vous configurez l'horodatage (timestampMode: 'relative' ou timestampMode: 'default'), il s'affiche avant le premier message du jour en tant qu'en-tête. Cet en-tête s'affiche lorsque la conversation n'a pas été effacée et que des messages plus anciens sont toujours disponibles dans l'historique.
Description de first-message-day.png :
Description de l'illustration first-message-day.png

Un horodatage relatif s'affiche ensuite sur chaque nouveau message.
Description de l'illustration most-recent-message-timestamp.png :
Description de l'illustration most-recent-message-timestamp.png
Cet horodatage est mis à jour à intervalles réguliers (secondes, minutes, etc.) jusqu'à ce qu'un nouveau message soit reçu.
  • Pendant les 10 premières secondes
  • Entre 10 et 60 secondes
  • Toutes les minutes entre 1 et 60 minutes
  • Toutes les heures entre 1 et 24 heures
  • Tous les jours entre 1 et 30 jours
  • Tous les mois entre 1 et 12 mois
  • Tous les ans après la première année
Lorsqu'un nouveau message est chargé dans le clavardage, l'horodatage relatif du message précédent est supprimé et un nouvel horodatage apparaît sur le nouveau message affichant le temps écoulé depuis le message précédent. À ce moment-là, l'horodatage relatif se met à jour jusqu'à ce que le message suivant arrive.

Ajouter un horodatage relatif

Pour ajouter un horodatage relatif :
  • Activez les horodatages relatifs – timestampMode: 'relative'
  • Étapes facultatives :
    • Définissez la couleur de l'horodatage relatif – timestamp: '<a hexadecimal color value>'
    • Pour des compétences multilingues, localisez le texte de l'horodatage à l'aide de ces clés :
      Clé Texte par défaut Description
      relTimeNow Now Horodatage initial, qui s'affiche pendant les 9 premières secondes. Cet horodatage s'affiche également lorsque la conversation est réinitialisée.
      relTimeMoment a few moments ago S'affiche pendant 10 à 60 secondes.
      relTimeMin {0}min ago Se met à jour toutes les minutes
      relTimeHr {0}hr ago Se met à jour toutes les heures
      relTimeDay {0}d ago Se met à jour quotidiennement pendant le premier mois.
      relTimeMon {0}mth ago Se met à jour tous les mois pendant les douze premiers mois.
      relTimeYr {0}yr ago Se met à jour chaque année.
    • Utilisez les paramètres timeStampFormat pour modifier le format de l'horodatage absolu qui s'affiche avant le premier message de chaque jour.

Remplir automatiquement

  • Indicateur de fonction : enableAutocomplete: true (par défaut : false)
  • Activer la mise en cache côté client : enableAutocompleteClientCache
Le remplissage automatique permet de limiter les erreurs de l'utilisateur en fournissant des expressions efficaces qui peuvent être utilisées en tant qu'entrées directes et en tant que suggestions. Pour activer cette fonction, mettez à jour les paramètres du widget avec enableAutocomplete: true et ajoutez un jeu de messages d'utilisateur optimisés à la page Create Intent (Créer une intention). Une fois la fonction activée, une fenêtre contextuelle affiche ces messages après que l'utilisateur a entré au moins trois caractères. Les mots des messages suggérés qui correspondent à l'entrée de l'utilisateur sont mis en évidence en gras. À partir de là, les utilisateurs peuvent saisir leur propre entrée ou choisir l'un des messages suggérés.
Note

Cette fonction n'est disponible que sur WebSocket.

Une description de autocomplete-phrase-list.png suit
Description de l'illustration autocomplete-phrase-list.png

Lorsqu'un assistant numérique est associé au canal Oracle Web, tous les exemples d'énoncés configurés pour les compétences enregistrées auprès de cet assistant numérique peuvent être utilisés comme suggestions de remplissage automatique.

Soumission automatique d'un champ

Lorsqu'un champ a la propriété autoSubmit réglée à true, le client envoie un FormSubmissionMessagePayload avec le mappage submittedField contenant les valeurs de champ valides qui ont été entrées jusqu'à présent. Tous les champs qui ne sont pas encore définis (qu'ils soient obligatoires ou non) ou les champs qui violent une validation côté client ne sont pas inclus dans le mappage submittedField. Si le champ auto-soumis contient lui-même une valeur qui n'est pas valide, le message de soumission n'est pas envoyé et le message d'erreur du client s'affiche pour ce champ particulier. Lorsqu'une soumission automatique réussit, partialSubmitField dans le message de soumission de formulaire est réglé à id du champ autoSubmit.

Remplacement d'un formulaire d'entrée précédent

Lorsque l'utilisateur final soumet le formulaire, soit parce que autosubmit est réglé à true pour un champ, la compétence peut envoyer un nouveau EditFormMessagePayload. Ce message doit remplacer le message du formulaire d'entrée précédent. En réglant la propriété d'extension de canal replaceMessage à true, vous activez la trousse SDK pour remplacer le message de formulaire d'entrée précédent par le message de formulaire d'entrée courant.

Disposition automatique RTL

Lorsque la direction de base de la page hôte est réglée à <html dir="rtl"> pour la prise en charge des langues qui se lisent de droite à gauche (RTL), le widget de clavardage est automatiquement placé sur le côté gauche. Comme le widget est aligné à gauche pour les langues RTL, ses icônes et éléments de texte sont également repositionnés. Les icônes sont dans les positions opposées à celles qu'elles occuperaient dans un rendu de gauche à droite (LTR). Par exemple, les icônes d'envoi, de micro et de pièce jointe sont retournées de sorte que les icônes de micro et d'envoi occupent le côté gauche du champ d'entrée (avec l'icône directionnelle d'envoi pointant vers la gauche) tandis que l'icône de pièce jointe est à droite du champ d'entrée. L'alignement des éléments de texte, tels que inputPlaceholder et chatTitle, est différent selon que la langue de texte est LTR ou RTL. Pour les langues RTL, le texte inputPlaceHolder et chatTitle apparaît du côté droit du champ d'entrée.

Avatars

Par défaut, aucun message du clavardage n'est accompagné d'avatars. Toutefois, en utilisant les paramètres suivants, vous pouvez configurer des avatars pour la compétence, l'utilisateur et un avatar d'agent si la compétence intègre la prise en charge d'agent humain.
  • avatarBot - URL de la source d'image ou chaîne source de l'image SVG affichée à côté des messages de compétence.
  • avatarUser - URL de la source d'image ou chaîne source de l'image SVG affichée à côté des messages d'utilisateur. En outre, si la compétence comporte une intégration d'agent humain, la trousse SDK peut être configurée pour afficher une icône différente pour les messages d'agent.
  • avatarAgent - URL de la source d'image ou chaîne source de l'image SVG qui est affichée en même temps que les messages de l'agent. Si cette valeur n'est pas fournie, mais que avatarBot est défini, l'icône avatarBot est utilisée à la place.
Note

Ces valeurs ne peuvent être transmises que dans les paramètres d'initialisation. Elles ne peuvent pas être modifiées dynamiquement. 
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>'
}
})

Synchronisation de conversation entre onglets

Indicateur de fonction : enableTabsSync: true (par défaut : true)

Les utilisateurs peuvent avoir besoin d'ouvrir le site Web dans plusieurs onglets pour diverses raisons. Avec enableTabsSync: true, vous pouvez synchroniser et poursuivre la conversation de l'utilisateur à partir de n'importe quel onglet, à condition que les paramètres de connexion (URI, channelId et userId) soient identiques dans tous les onglets. Cette fonction garantit que les utilisateurs peuvent voir les messages de la compétence dans n'importe quel onglet et répondre à partir du même onglet ou de n'importe quel autre. De plus, si l'utilisateur efface l'historique de conversation dans un onglet, il est également supprimé des autres onglets. Si l'utilisateur met à jour la langue de clavardage dans un onglet, la langue de clavardage est synchronisée dans les autres onglets.

Il existe certaines limitations :
  • Un nouvel onglet se synchronise avec les onglets existants pour les nouveaux messages entre l'utilisateur et la compétence à l'ouverture. Si vous n'avez pas configuré la trousse SDK pour afficher les messages de l'historique de conversation, le widget de clavardage initial dans le nouvel onglet apparaîtra vide lorsqu'il sera ouvert.
  • Si vous avez configuré la trousse SDK pour afficher l'historique des conversations, les messages du clavardage courant dans les onglets existants s'affichent dans l'historique des conversations dans un nouvel onglet. Le réglage de disablePastActions à all ou postback peut empêcher l'interaction avec les actions pour les messages dans le nouvel onglet.
  • Le navigateur Safari ne prend actuellement pas en charge cette fonctionnalité.

Rendu de message personnalisé

Indicateur de fonction : delegate.render: (message) => boolean (default: undefined)

Utilisez cette fonction pour remplacer le rendu de message par défaut par votre propre modèle de message personnalisé. Pour utiliser cette fonction, vous devez mettre en oeuvre la fonction de délégation render qui prend le modèle de message comme entrée et retourne un indicateur booléen comme sortie. Il doit retourner true pour remplacer le rendu par défaut par votre rendu personnalisé pour un type de message particulier. Si false est retourné, le message par défaut est affiché à la place.
Note

Pour un rendu personnalisé, le traitement de tous les clics d'action et la désactivation ou l'activation de l'action doivent être traités explicitement.
Vous pouvez utiliser n'importe quel composant de structure externe pour le rendu de vos messages. Consultez les exemples d'intégration inclus dans le répertoire samples de la trousse SDK pour vérifier comment utiliser cette fonction avec des cadres tels que React, Angular et Oracle JavaScript Extension Toolkit (JET).

Réponses de client par défaut

Indicateur de fonction : enableDefaultClientResponse: true (par défaut : false)

Utilisez cet indicateur pour fournir des réponses côté client par défaut ainsi qu'un indicateur de saisie lorsque la réponse de la compétence a été retardée ou lorsqu'il n'y a aucune réponse de la compétence. Si l'utilisateur envoie le premier message/interrogation, mais que la compétence ne répond pas dans le délai de secondes défini par l'indicateur defaultGreetingTimeout, la compétence peut afficher un message de salutation configuré à l'aide de la chaîne de traduction defaultGreetingMessage. Ensuite, le client vérifie à nouveau la réponse de la compétence. Le client affiche la réponse de la compétence si elle a été reçue, mais dans le cas contraire, il affiche un message d'attente (configuré avec la chaîne de traduction defaultWaitMessage) à des intervalles définis par defaultWaitMessageInterval. Lorsque l'attente de la réponse de la compétence dépasse le seuil défini par l'indicateur typingIndicatorTimeout, le client affiche une réponse désolée à l'utilisateur et arrête l'indicateur de saisie. Vous pouvez configurer la réponse désolée à l'aide de la chaîne de traduction defaultSorryMessage.

Délégation

Configuration de fonction : delegate

La fonction de délégation définit un délégué pour la réception de rappels avant certains événements de la conversation. Pour définir un délégué, transmettez le paramètre delegate ou utilisez la méthode setDelegate. L'objet délégué peut éventuellement contenir les fonctions de délégation beforeDisplay, beforeSend, beforePostbackSend, beforeEndConversation et 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

Le délégué beforeDisplay permet la modification d'un message de la compétence avant son affichage dans la conversation. Le message retourné par le délégué s'affiche à la place du message initial. Le message retourné n'est pas affiché si le délégué retourne une valeur fausse telle que null, undefined ou false. En cas d'erreur du délégué, le message initial sera affiché au lieu du message retourné par le délégué. Utilisez le délégué beforeDisplay pour appliquer de manière sélective le comportement relatif aux liens de la vue Web dans le widget.

beforeSend

Le délégué beforeSend permet de modifier un message de l'utilisateur avant de l'envoyer au serveur de clavardage dans le cadre de sendMessage. Le message retourné par le délégué est envoyé à la compétence au lieu du message initial. Le message retourné par le délégué n'est pas défini si le délégué retourne une valeur fausse telle que null, undefined ou false, le message n'est pas envoyé. En cas d'erreur, le message initial sera envoyé au lieu du message retourné par le délégué.

beforePostbackSend

Le délégué beforePostbackSend est similaire à beforeSend, mais il s'applique aux messages de republication de l'utilisateur. La republication retournée par le délégué est envoyée à la compétence. S'il retourne une valeur fausse, par exemple null, undefined ou false, aucun message n'est envoyé.

beforeEndConversation

Le délégué beforeEndConversation permet une interception à la fin d'un flux de conversation si une activité de pré-sortie doit être effectuée. function reçoit le message de sortie en tant que paramètre d'entrée et doit retourner une valeur Promise. Si cette Promise se résout avec le message de sortie, le message de sortie CloseSession est envoyé au serveur de clavardage. Sinon, le message de sortie ne peut pas être envoyé.
...

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

rendu

Le délégué render vous permet de remplacer le rendu de message par défaut. Si la fonction déléguée render retourne true pour un type de message particulier, WebSDK crée un emplacement de paramètre fictif au lieu du rendu de message par défaut. Pour identifier le paramètre fictif, ajoutez msgId du message en tant que id de l'élément. Dans la fonction de délégué render, vous pouvez utiliser cet identificateur pour obtenir la référence du paramètre fictif et afficher votre modèle de message personnalisé. Voir Rendu des messages personnalisés.

Bouton et widget de lancement avec fonction de déplacement

Indicateur de fonction : enableDraggableButton: true (par défaut : false)

Parfois, en particulier sur les appareils mobiles où la taille de l'écran est limitée, le widget de clavardage ou le bouton de lancement peut bloquer le contenu d'une page Web. En définissant enableDraggableButton: true, vous pouvez permettre aux utilisateurs de déplacer le widget ou le bouton de lancement lorsqu'il bloque la vue. Cet indicateur n'affecte que l'emplacement du bouton de lancement, et non le widget de clavardage : ce dernier s'ouvrira toujours depuis son emplacement initial.

Indicateur de frappe dynamique

Indicateur de fonction : showTypingIndicator: 'true'

Un indicateur de frappe signale aux utilisateurs de différer l'envoi d'un message parce que la compétence est en train de préparer une réponse. Par défaut, les compétences affichent l'indicateur de frappe uniquement pour leur première réponse lorsque vous initialisez la trousse SDK avec showTypingIndicator: 'true'. Pour une expérience utilisateur optimale, la compétence doit être dotée d'un indicateur de frappe dynamique, c'est-à-dire qui s'affiche après chaque réponse de la compétence. En plus de tenir les utilisateurs informés que la compétence n'a pas expiré mais est occupée à répondre, l'affichage de l'indicateur de frappe après chaque réponse de compétence garantit que les utilisateurs n'enverront pas de message prématurément, comme cela pourrait être le cas lorsque la propriété keepTurn spécifie à la compétence de répondre avec une série de messages distincts qui empêchent à l'utilisateur de réagir.

Pour activer un indicateur de frappe après chaque réponse de la compétence :
  • À l'initialisation de la trousse SDK, réglez showTypingIndicator à true.
  • Appelez l'API showTypingIndicator
showTypingIndicator ne peut activer l'affichage de l'indicateur de frappe dynamique que lorsque :
  • Le widget est connecté à Oracle Chat Server. L'indicateur de frappe dynamique n'apparaît pas lorsque la connexion est fermée.
  • showTypingIndicator a été réglé à true à l'initialisation de la trousse SDK.
    Note

    Cette API ne fonctionne pas lorsque la trousse SDK est utilisée en mode sans interface.
L'indicateur de frappe s'affiche pour la durée définie par la propriété facultative typingIndicatorTimeout, dont le paramètre par défaut est 20 secondes. Si l'API est appelée alors qu'un indicateur de saisie est déjà affiché, le temporisateur est réinitialisé et l'indicateur, masqué.

L'indicateur de frappe disparaît dès que l'utilisateur reçoit les messages de la compétence. Si un utilisateur entre un message, charge un fichier joint ou envoie un emplacement alors que l'indicateur de saisie est affiché, celui-ci passe en bas de la fenêtre de clavardage.

Contrôler le comportement des liens intégrés

  • Traitement personnalisé : linkHandler: { onclick: <function>, target: '<string>' }
  • Dans la vue Web du widget : linkHandler: { target: 'oda-chat-webview' }
  • Dans une nouvelle fenêtre : openLinksInNewWindow: 'true'
En plus d'ouvrir des liens dans une nouvelle fenêtre en définissant openLinksInNewWindow: true, ou le comportement par défaut de l'ouverture de liens dans un nouvel onglet, vous pouvez également ouvrir des liens qui superposent la page Web du widget. Pour activer cette option et d'autres remplacements au comportement relatif aux liens, initialisez la trousse SDK avec 
linkHandler: {
    target: '_blank',   // open link in a new page
    onclick: (event) => { // some operation }
}
Utilisez linkHander pour :
  • Contrôler la navigation du cadre iframe pour qu'il se superpose systématiquement à la page sans avoir à inclure le widget à chaque page, à le rouvrir après une navigation et à conserver le même ID utilisateur.
    Description d'open-iframe.png :
    Description de l'illustration open-iframe.png

  • Ouvrir certains liens dans une nouvelle fenêtre et d'autres dans le même onglet.
  • Effectuer une action lors d'un clic sur un lien.
  • Empêcher un lien de s'ouvrir.
  • Ouvrir un lien dans une vue Web.
Pour remplacer le comportement relatif aux liens défini par le paramètre openLinksInNewWindow, vous devez l'un des attributs suivants ou les deux :
  • self - Contexte de navigation actuel
  • target – Nomme le contexte de l'emplacement de navigation, tel qu'un onglet, une fenêtre ou un cadre iFrame. Définissez l'emplacement iFrame comme attribut target d'un élément d'ancrage (<a>). Vous pouvez définir les attributs _self, _blank, _parent et _top de la cible.
  • onclick - Accepte une fonction de rappel lancée par un clic sur le lien. L'événement MouseEvent reçu lors du clic est transmis au rappel. Ce dernier peut être utilisé pour effectuer une action ou même pour empêcher l'ouverture du lien.

Mode intégré

  • Indicateur de fonction : embedded: true (par défaut : false)
  • Transmettez l'ID de l'élément de conteneur cible : targetElement
En plus des autres paramètres qui permettent de personnaliser l'aspect et la convivialité du widget qui exécute le clavardage, vous pouvez intégrer le widget lui-même dans la page Web en effectuant les opérations suivantes :
  • Ajouter embedded: true.
  • Définir la propriété targetElement avec l'ID de l'élément DOM (composant HTML) utilisé comme conteneur du widget (tel que 'container-div' dans l'extrait de code suivant). 
<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>
Note

Le widget occupe toute la largeur et la hauteur du conteneur. S'il ne rentre pas dans le conteneur, le widget ne s'affiche pas sur la page.

Terminer la session de conversation

Indicateur de fonction : enableEndConversation: true (par défaut : true)

À partir de la version 21.12, la trousse SDK ajoute par défaut un bouton de fermeture à l'en-tête du widget de clavardage (enableEndConversation: true) qui permet aux utilisateurs de mettre fin à la session courante.
Ceci est une image du bouton Fermer dans l'en-tête du widget de clavardage.

Une fois que les utilisateurs ont cliqué sur ce bouton, la trousse SDK leur présente une invite de confirmation dont le texte ("Voulez-vous mettre fin à la conversation? Cela effacera également votre historique de conversation.") que vous pouvez personnaliser avec les clés endConversationConfirmMessage et endConversationDescription. Lorsqu'un utilisateur rejette l'invite en cliquant sur Yes (Oui), la trousse SDK envoie à la compétence un message d'événement qui marque la session de conversation courante comme terminée. L'instance se déconnecte ensuite de la compétence, réduit le widget de clavardage et efface l'historique de conversation de l'utilisateur courant. Il déclenche également un événement chatend pour lequel vous pouvez vous inscrire :
Bots.on('chatend', function() {
    console.log('The conversation is ended.');
});
L'ouverture du widget de clavardage démarre ensuite une nouvelle session de conversation.
Note

Vous pouvez également mettre fin à une session en appelant la méthode Bots.endChat() (décrite dans la référence qui accompagne la trousse SDK Oracle Web disponible à partir de la page Téléchargements). L'appel de cette méthode peut s'avérer utile lorsque la trousse SDK est initialisée en mode sans périphérique.

Focalisation sur la première action d'un message

Indicateur de fonction : focusOnNewMessage: 'action' (par défaut : 'input')

Pour les utilisateurs qui préfèrent la navigation par clavier (parmi eux, les utilisateurs expérimentés), vous pouvez déplacer la focalisation du champ d'entrée d'utilisateur vers le premier bouton d'action (ou le plus à gauche) d'un message. Par défaut, le widget de clavardage remet la focalisation sur le champ d'entrée d'utilisateur à chaque nouveau message (focusOnNewMessage: 'input'). Cela fonctionne bien pour les flux de dialogue qui attendent beaucoup d'entrée textuelle de l'utilisateur, mais lorsque le flux de dialogue contient un certain nombre de messages avec des actions, les utilisateurs ne peuvent sélectionner ces actions que par la souris ou la navigation par tabulation arrière. Pour ce cas d'utilisation, vous pouvez déplacer la focalisation sur le premier bouton d'action dans le message de compétence à sa réception en définissant focusOnNewMessage: 'action'. Si le message ne contient aucune action, la focalisation est placée sur le champ d'entrée d'utilisateur.

Claviers et raccourcis clavier

En définissant l'objet hotkeys, vous pouvez créer des raccourcis de combinaison de clé alternative qui activent les éléments d'interface utilisateur dans le widget de clavardage ou qui se concentrent sur eux. Les utilisateurs peuvent exécuter ces raccourcis au lieu d'utiliser la souris ou les gestes tactiles. Par exemple, les utilisateurs peuvent entrer Alt + L pour lancer le widget de clavardage et Alt + C pour le réduire. Vous affectez les touches du clavier aux éléments à l'aide des paires clé-valeur de l'objet hotkeys. Par exemple : 
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
    }
};
Lors de la création de ces paires clé-valeur :
  • Vous ne pouvez transmettre qu'une seule lettre ou un seul chiffre pour une clé.
  • Vous ne pouvez utiliser que les touches de clavier a-z et 0-9 comme valeurs.
Vous pouvez transmettre l'attribut hotkey en définissant les clés suivantes.
Note

L'attribut n'est pas sensible à la casse.
Clé Élément
clearHistory Bouton qui efface l'historique de conversation.
close Bouton qui ferme le widget de clavardage et termine la conversation.
collapse Bouton qui réduit le widget de clavardage développé.
input Champ d'entrée de texte dans le pied de page du clavardage
keyboard Bouton qui fait passer le mode d'entrée de la voix au texte.
language Menu de sélection qui affiche la liste de sélection de la langue.
launch Bouton de lancement du widget de clavardage
mic Bouton qui fait passer le mode d'entrée du texte à la voix.
send Bouton qui envoie le texte d'entrée à la compétence.
shareMenu Bouton du menu de partage dans le pied de page du clavardage
shareMenuAudio Élément de menu dans la fenêtre contextuelle du menu de partage qui sélectionne un fichier audio à partager.
shareMenuFile Élément de menu dans la fenêtre contextuelle du menu de partage d'un fichier générique
shareMenuLocation Élément de menu dans la fenêtre contextuelle du menu de partage qui sélectionne l'emplacement de l'utilisateur à partager.
shareMenuVisual Élément de menu dans la fenêtre contextuelle du menu de partage qui sélectionne un fichier image ou vidéo à partager.

SDK sans interface

Indicateur de fonction : enableHeadless: true (par défaut : false)

Tout comme les navigateurs, la trousse SDK peut être utilisée sans son interface utilisateur. La trousse SDK gère la connexion au serveur et fournit des API pour l'envoi et la réception de messages, et pour l'obtention de mises à jour du statut du réseau. Vous pouvez utiliser ces API pour interagir avec la trousse SDK et mettre à jour l'interface utilisateur. Pour activer cette fonction, transmettez enableHeadless: true dans les paramètres initiaux. La communication peut être mise en oeuvre comme suit :
  • Envoi de messages - Appelle Bots.sendMessage(message) pour transmettre les données utiles au serveur.
  • Réception de messages - Les réponses peuvent être écoutées à l'aide de Bots.on('message:received', <messageReceivedCallbackFunction>).
  • Obtention des mises à jour du statut de connexion - Écoute les mises à jour de statut de la connexion à l'aide de Bots.on('networkstatuschange', <networkStatusCallbackFunction>). Le rappel est associé à un paramètre de statut qui est mis à jour avec les valeurs 0 à 3, correspondant aux états WebSocket :
    • 0 : WebSocket.CONNECTING
    • 1: WebSocket.OPEN
    • 2: WebSocket.CLOSING
    • 3: WebSocket.CLOSED
    • Retour de suggestions pour une interrogation – Retourne une promesse qui se résout en suggestions pour la chaîne d'interrogation donnée. La promesse est rejetée si elle prend trop de temps (environ 10 secondes) pour extraire la suggestion. 
      Bots.getSuggestions(utterance)
    .then((suggestions) => {
        const suggestionString = suggestions.toString();
        console.log('The suggestions are: ', suggestionString);
    })
    .catch((reason) => {
        console.log('Suggestion request failed', reason);
    });
    Note

    Pour utiliser cette API, vous devez activer autocomplete (
    enableAutocomplete: true
    ) et configurer le remplissage automatique pour les intentions.

Chat multilingue

La prise en charge linguistique native de la trousse SDK Web permet au widget de clavardage de détecter la langue d'un utilisateur ou de permettre aux utilisateurs de sélectionner la langue de conversation. Les utilisateurs peuvent passer d'une langue à l'autre, mais seulement d'une conversation à l'autre, et non pendant une conversation, car celle-ci est réinitialisée chaque fois qu'un utilisateur sélectionne une nouvelle langue.

Activer le menu Langue

Vous pouvez activer un menu qui permet aux utilisateurs de sélectionner une langue privilégiée dans un menu déroulant en définissant la propriété multiLangChat avec un objet contenant le tableau supportedLangs, qui est composé de marqueurs de langue (lang) et d'étiquettes d'affichage facultatives (label). En dehors de ce tableau, vous pouvez éventuellement définir la langue par défaut avec la clé primary (primary: 'en' dans l'extrait suivant).
multiLangChat: {
    supportedLangs: [{
        lang: 'en'
    }, {
        lang: 'es',
        label: 'Español'
    }, {
        lang: 'fr',
        label: 'Français'
    }, {
        lang: 'hi',
        label: 'हिंदी'
    }],
    primary: 'en'
}
Le widget de clavardage affiche les langues prises en charge dans un menu déroulant situé dans l'en-tête. En plus des langues disponibles, le menu comprend également une option Détecter la langue. Lorsqu'un utilisateur sélectionne une langue dans ce menu, la conversation courante est réinitialisée et une nouvelle conversation est lancée avec la langue sélectionnée. La langue sélectionnée par l'utilisateur est conservée dans toutes les sessions du même navigateur. La langue précédente de l'utilisateur est donc automatiquement sélectionnée lorsque celui-ci revisite la compétence par la page contenant le widget de clavardage.

Conseil :

Vous pouvez ajouter un module d'écoute d'événement pour l'événement chatlanguagechange (décrit dans la référence qui accompagne la trousse SDK Oracle Web disponible à partir de la page Téléchargements), qui est déclenché lorsqu'un langage de clavardage a été sélectionné dans le menu déroulant ou a été modifié.
Bots.on('chatlanguagechange', function(language) {
    console.log('The selected chat language is', language);
});
Voici ce que vous devez garder à l'esprit lors de la configuration du menu déroulant Langue :
  • Vous devez définir au moins deux langues pour activer l'affichage du menu déroulant.
  • La clé label est facultative pour les langues prises en charge de manière native : fr devient French (Français) dans le menu; es, Spanish (Espagnol), etc.
  • Les étiquettes pour les langues peuvent être définies dynamiquement en les transmettant avec le paramètre i18n. Vous pouvez définir l'étiquette pour n'importe quelle langue en la transmettant à sa clé language_<languageTag>. Ce modèle permet de définir des étiquettes pour n'importe quelle langue, prise en charge ou non, et permet également de les traduire dans différentes langues. Par exemple :
    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'
    }
}
    Si la propriété i18n inclut des chaînes de traduction pour la langue sélectionnée, le texte de champs tels que le paramètre fictif d'entrée, le titre de clavardage, le texte de survol des boutons et les titres d'infobulle passent automatiquement à la langue sélectionnée. Le texte du champ ne peut passer à une autre langue que s'il existe des chaînes de traduction pour la langue sélectionnée. Sinon, la langue du texte du champ reste inchangée.
  • Le widget détecte automatiquement la langue dans le profil de l'utilisateur et active l'option Detecter la langue si vous omettez la clé primary.
  • Bien que la clé label soit facultative, si vous avez ajouté une langue qui n'est pas prise en charge de manière native, vous devez ajouter une étiquette pour identifier la balise, surtout s'il n'y a pas de chaîne i18n pour la langue. Par exemple, si vous ne définissez pas label: 'हिंदी', pour lang: hi, la liste déroulante affiche hi à la place, contribuant à une expérience utilisateur imparfaite.

Désactiver menu langue

À partir de la version 21.12, vous pouvez également configurer et mettre à jour le langage de clavardage sans avoir à configurer le menu déroulant de sélection de langue en transmettant multiLangChat.primary dans la configuration initiale sans transmettre également un tableau multiLangChat.supportedLangs. La valeur transmise dans la variable primary est définie comme langue de clavardage pour la conversation.

Détection de la langue

En plus des langues transmises, le widget de clavardage affiche une option Detect Language dans la liste déroulante. La sélection de cette option indique à la compétence de détecter automatiquement la langue de conversation à partir du message de l'utilisateur et, si possible, de répondre dans cette même langue.
Note

Si vous omettez la clé primary, le widget détecte automatiquement la langue dans le profil de l'utilisateur et active l'option Detect Language dans le menu.

Vous pouvez mettre à jour dynamiquement la langue sélectionnée en appelant l'API setPrimaryChatLanguage(lang). Si le fichier lang transmis correspond à l'une des langues prises en charge, cette langue est sélectionnée. Lorsqu'aucune correspondance ne peut être trouvée, l'option Détecter la langue est activée. Vous pouvez également activer l'option Langue détectée en appelant l'API setPrimaryChatLanguage('und'), où 'und' indique une valeur indéterminée ou en transmettant multiLangChat: {primary: null} ou multiLangChat: {primary: 'und'}.

Vous pouvez mettre à jour le langage de clavardage de manière dynamique à l'aide de l'API setPrimaryChatLanguage(lang) même si le menu déroulant n'a pas été configuré. Par exemple :
Bots.setPrimaryChatLanguage('fr')
Vous pouvez mettre à jour la langue de manière dynamique, que la langue de clavardage soit initialement configurée ou non.
Note

La reconnaissance vocale, lorsqu'elle est configurée, est disponible lorsque les utilisateurs sélectionnent une langue prise en charge. Elle n'est pas disponible lorsque l'option Detect Language (Détecter la langue) est définie. La sélection d'une langue qui n'est pas prise en charge par la reconnaissance vocale désactive la fonctionnalité de reconnaissance jusqu'à ce qu'une langue prise en charge soit sélectionnée.

Référence rapide du clavardage multilingue

Pour ce faire... ... Faire ceci
Afficher la liste déroulante de sélection de la langue aux utilisateurs finaux. Passez multiLangChat.supportedLangs.
Définissez la langue du clavardage sans afficher le menu déroulant de sélection de la langue pour les utilisateurs finaux. Passez multiLangChat.primary.
Définissez une langue par défaut. Transmettez multiLangChat.primary avec multiLangChat.supportedLangs. La valeur primary doit être l'une des langues prises en charge incluses dans le tableau.
Activer la détection de la langue. Transmettez primary: null ou primary: 'und' avec multiLangChat.
Mettez à jour dynamiquement la langue du clavardage. Appelez l'API setPrimaryChatLanguage(lang).

Vue Web dans le widget

Vous pouvez configurer le comportement du lien dans les messages de clavardage pour permettre aux utilisateurs d'accéder aux pages Web depuis le widget de clavardage. Au lieu d'avoir à sortir de la conversation pour afficher une page dans un onglet ou une fenêtre de navigateur distincte, un utilisateur peut y rester parce que le widget de clavardage ouvre le lien dans une vue Web.

Configurer le comportement relatif aux liens à la vue Web

Vous pouvez appliquer la vue Web à tous les liens, ou dans un cas d'utilisation plus typique, à quelques liens sélectionnés. Vous pouvez également personnaliser la vue Web elle-même.
  • Pour ouvrir tous les liens dans la vue Web, transmettez linkHandler: { target: 'oda-chat-webview' } dans les paramètres. Cela définit la cible de tous les liens vers oda-chat-webview, qui est le nom de l'iframe dans la vue Web.
  • Pour ouvrir seulement certains liens dans la vue Web tout en veillant à ce que d'autres liens s'ouvrent normalement dans d'autres onglets ou fenêtres, utilisez le délégué beforeDisplay. Pour ouvrir une action URL de message spécifique dans la vue Web, remplacez la valeur 'url' du champ action.type par 'webview'. Lorsque le type d'action est 'webview' dans la fonction beforeDisplay, le bouton d'action ouvrira le lien dans la vue Web lorsqu'il sera cliqué.

Ouvrir des liens depuis la vue Web

Les liens intégrés dans une page qui s'affiche dans la vue Web ne peuvent être ouverts dans cette dernière que lorsqu ils sont convertis en élément d'ancrage (<a>), avec un attribut target défini comme target="oda-chat-webview".

Personnaliser WebView

Vous pouvez personnaliser la vue Web avec le paramètre webViewConfig qui accepte un objet. Par exemple :
{ referrerPolicy: 'no-referrer-when-downgrade', closeButtonType: 'icon', size: 'tall'
Les champs de cet objet sont facultatifs.
Note

La configuration peut également être mise à jour dynamiquement en transmettant un objet webViewConfig dans la méthode setWebViewConfig. Chaque propriété de l'objet est facultative.
Champ Valeur Description
accessibilityTitle Chaîne Nom de l'élément de cadre de la vue Web pour l'accessibilité Web.
closeButtonIcon Chaîne Chaîne URL/SVG de l'image utilisée pour afficher l'icône du bouton de fermeture.
closeButtonLabel Chaîne Titre de l'étiquette de texte/infobulle pour le bouton de fermeture.
closeButtonType
  • 'icon'
  • 'label'
  • 'iconWithLabel'
Définit la façon dont le bouton de fermeture s'affiche dans la vue Web.
referrerPolicy ReferrerPolicy Indique quel référent envoyer lors de l'extraction de la ressource du cadre. La valeur de la politique referrerPolicy doit être une directive valide. La politique par défaut appliquée est 'no-referrer-when-downgrade'.
sandbox Tableau de chaînes Tableau de chaînes de restriction valides qui permet d'exclure certaines actions à l'intérieur du cadre. Les restrictions qui peuvent être transmises à ce champ sont incluses dans la description de l'attribut sandbox dans la documentation MDN Web.
size
  • 'tall'
  • 'full'
Hauteur de la vue Web par rapport à celle du widget de clavardage. Lorsqu' elle est réglée à 'tall', elle est réglée à 80 % de la hauteur du widget. Lorsqu' elle est réglée à 'full', elle est égale à la hauteur du widget.
title Chaîne Titre affiché dans l'en-tête du conteneur de la vue Web.
Tous les liens ne peuvent pas s'ouvrir dans la vue Web. Voici quelques raisons :
  • Les pages qui fournissent l'en-tête de réponse X-frame-options: deny ou X-frame-options: sameorigin peuvent ne pas s'ouvrir dans la vue Web en raison de restrictions côté serveur qui empêchent l'ouverture de la page dans des cadres insérés. Dans de tels cas, la vue Web retourne le lien à l'utilisateur afin qu'il puisse l'ouvrir dans une nouvelle fenêtre ou un nouvel onglet.
  • En raison de restrictions côté serveur, les pages d'autorisation ne peuvent pas s'ouvrir dans WebViews, car les pages d'autorisation retournent toujours X-frame-options: deny pour empêcher une attaque de détournement de clic.
  • Des liens externes qui ne peuvent pas s'ouvrir correctement dans la vue Web. Seuls les liens intégrés dans les messages de conversation peuvent être ouverts dans la vue Web.
    Note

    Comme les messages externes sont incompatibles avec la vue Web, ne créez aucun lien externe à ouvrir dans la vue Web.
Lorsqu'un lien ne peut pas s'ouvrir dans la vue Web, le widget présente à l'utilisateur un texte d'information et un lien vers la vue Web, qui ouvre la page dans un nouvel onglet lorsque vous cliquez dessus. Vous pouvez personnaliser ce texte à l'aide de la chaîne de traduction i18n webViewErrorInfoText :
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}.'
        }
    }
}

Scrutation longue

Indicateur de fonction : enableLongPolling: true (par défaut : false)

La trousse SDK utilise WebSocket pour se connecter au serveur et converser avec les compétences. Si, pour une raison quelconque, WebSocket est désactivé sur le réseau, les appels HTTP traditionnels peuvent être utilisés pour clavarder avec la compétence. Cette fonction est connue sous le nom de scrutation longue car la trousse SDK doit appeler, ou scruter continuellement le serveur pour extraire les derniers messages de la compétence. Cette fonction de remplacement peut être activée en transmettant enableLongPolling: true dans les paramètres initiaux.

Indicateur de saisie pour les conversations utilisateur-agent

Indicateur de fonction : enableSendTypingStatus : booléen (par défaut : false)

Cette fonction permet aux agents de déterminer si les utilisateurs sont encore engagés dans la conversation en envoyant le statut de l'utilisateur à l'agent humain. Lorsque enableSendTypingStatus est réglé à true, la trousse SDK envoie un événement de statut de saisie RESPONDING avec le texte en cours d'entrée par l'utilisateur à Oracle B2C Service ou Oracle Fusion Service. Ceci, à son tour, affiche un indicateur de frappe sur la console de l'agent. Lorsque l'utilisateur a terminé de taper, la trousse SDK envoie un événement LISTENING au service pour masquer l'indicateur de taper sur la console de l'agent.

La configuration typingStatusInterval, qui a une valeur minimale de trois secondes, ralentit la mise à jour du statut de saisie.

Pour envoyer un agent Oracle B2C Service à la fois le texte tel qu'il est entré par l'utilisateur et le statut de saisie, enableAgentSneakPreview (qui est par défaut false) doit être réglé à true et la prévisualisation sneak doit être activée dans la configuration de clavardage d'Oracle B2C Service.
Note

Il n'est pas nécessaire de configurer le statut de saisie en direct côté utilisateur. L'utilisateur peut voir le statut de saisie de l'agent par défaut. Lorsque l'agent entre, la trousse SDK reçoit un message de statut RESPONDING qui entraîne l'affichage d'un indicateur de saisie dans la vue de l'utilisateur. De même, lorsque l'agent est inactif, la trousse SDK reçoit un message de statut LISTENING qui masque l'indicateur de saisie.

Reconnaissance de la parole

Indicateur de fonction : enableSpeech: true (par défaut : false)

La définition de enableSpeech: true permet d'afficher le bouton du microphone au lieu du bouton d'envoi lorsque le champ d'entrée d'utilisateur est vide.

Votre compétence peut également utiliser la reconnaissance de la parole avec la méthode startVoiceRecording(onSpeechRecognition, onSpeechNetworkChange) pour commencer l'enregistrement et la méthode stopVoiceRecording pour l'arrêter. (Ces méthodes sont décrites dans le guide de l'utilisateur inclus dans la trousse SDK.)

À l'aide de l'indicateur enableSpeechAutoSend, vous pouvez indiquer si le texte reconnu à partir de l'entrée vocale de l'utilisateur doit être envoyé directement au serveur de clavardage, sans entrée manuelle de l'utilisateur. En réglant cette propriété à true (valeur par défaut), vous permettez que la réponse vocale de l'utilisateur soit envoyée automatiquement au serveur de clavardage. Si vous la réglez à false, vous autorisez l'utilisateur à modifier ou à supprimer le message avant qu'il soit envoyé au serveur de clavardage.

Visualiseur vocal

Configuration de fonction : enableSpeechAutoSend

Le widget de clavardage affiche un visualiseur vocal lorsque les utilisateurs cliquent sur l'icône vocale Ceci est une image de l'icône Speak (Parler) du visualiseur vocal.. Il indique si le niveau audio est suffisamment élevé pour permettre à la trousse SDK de capter la voix de l'utilisateur. Le message de l'utilisateur, converti en texte, s'affiche sous le visualiseur.
Note

Le mode vocal est indiqué par l'apparition de l'icône de clavier Ceci est une image de l'icône de clavier..
Une description de voice-visualizer.png suit
Description de l'illustration voice-visualizer.png
En raison de la valeur par défaut de enableSpeechAutosend, true (enableSpeechAutoSend: true), les messages sont envoyés automatiquement après leur reconnaissance. Le réglage enableSpeechAutoSend: false bascule le mode d'entrée à texte une fois le message vocal reconnu. Les utilisateurs peuvent alors modifier ou compléter le texte de leurs messages avant de les envoyer manuellement. Les utilisateurs peuvent également cliquer sur l'icône vocale pour compléter leur message oralement avant de l'envoyer manuellement.
Note

Le visualiseur vocal est créé à l'aide d'AnalyserNode. Vous pouvez mettre en oeuvre le visualiseur vocal en mode sans interface à l'aide de la méthode startVoiceRecording. Consultez la trousse SDK pour en savoir plus sur AnalyserNode et les niveaux de fréquence.