Documentation Oracle Cloud Infrastructure

Fonctions

Voici les fonctionnalités que vous pouvez configurer dans le kit SDK Web Oracle.

Horodatages absolus et relatifs

  • Indicateur de fonctionnalité : timestampMode: 'relative' | 'absolute' (valeur par défaut : 'relative')
  • Configuration des fonctionnalités : timestampMode

Vous pouvez activer les horodatages absolus ou relatifs pour les messages de discussion. Les horodatages absolus affichent l'heure exacte de chaque message. Les heures relatives s'affichent uniquement sur le dernier message et expriment le temps en secondes, jours, heures, mois ou années écoulé par rapport au message précédent.
Description de l'image relative-v-absolute-timestamps.png
Description de l'illustration relative-v-absolute-timestamps.png
Précision Grâce à l'horodatage absolu, ils sont idéaux pour les tâches d'archivage, mais dans le contexte limité d'une session de discussion, cette précision détourne l'attention de l'utilisateur, car celui-ci doit comparer l'horodatage pour connaître le temps écoulé entre les messages. Les horodatages relatifs permettent aux utilisateurs de suivre facilement la conversation par le biais de termes tels que A l'instant et 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 qui simplifie vos tâches de développement : étant donné que les horodatages relatifs marquent les messages en secondes, jours, heures, mois ou années écoulés, il n'est pas nécessaire de les convertir selon les fuseaux horaires.

Comportement des horodatages relatifs

Comme mentionné précédemment, l'horodatage relatif apparaît uniquement sur le dernier message. Etudions ce comportement plus en détail. Lorsque vous configurez l'horodatage (timestampMode: 'relative' ou timestampMode: 'default'), un horodatage absolu est affiché avant le premier message du jour sous forme d'en-tête. Cet en-tête apparaît lorsque la conversation n'a pas été effacée et que des messages plus anciens sont toujours disponibles dans l'historique.
Description du premier message-day.png ci-après
Description de la première image message-day.png

Un horodatage relatif s'affiche sur chaque nouveau message.
Description de l'image most-recent-message-timestamp.png
Description de l'illustration most-recent-message-timestamp.png
Cet horodatage est mis à jour aux intervalles réguliers suivants (secondes, minutes, etc.) jusqu'à réception d'un nouveau message.
  • 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 la discussion, l'horodatage relatif du message précédent est enlevé et un nouvel horodatage apparaît sur le nouveau message indiquant le temps écoulé depuis le message précédent. A ce stade, l'horodatage relatif est mis à jour jusqu'à l'arrivée des messages suivants.

Ajout d'un horodatage relatif

Pour ajouter un horodatage relatif, effectuez les opérations suivantes :
  • Activez les horodatages relatifs : timestampMode: 'relative'.
  • Etapes facultatives :
    • Définissez la couleur de l'horodatage relatif : timestamp: '<a hexadecimal color value>'
    • Pour les briques multilingues, localisez le texte d'horodatage à l'aide des clés suivantes :
      Clé Texte par défaut Description
      relTimeNow Now Horodatage initial, affiché 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 tous les jours du premier mois.
      relTimeMon {0}mth ago Se met à jour tous les mois pendant les douze premiers mois.
      relTimeYr {0}yr ago Se met à jour tous les ans.
    • Utilisez les paramètres timeStampFormat pour modifier le format de l'horodatage absolu affiché avant le premier message de chaque jour.

Ecriture automatique

  • Indicateur de fonctionnalité : enableAutocomplete: true (valeur par défaut : false)
  • Activer la mise en cache côté client : enableAutocompleteClientCache
L'écriture automatique réduit les erreurs utilisateur en fournissant des expressions effectives qui peuvent être utilisées à la fois en tant qu'entrée directe et en tant que suggestions. Pour activer cette fonctionnalité, mettez à jour les paramètres du widget avec enableAutocomplete: true et ajoutez un ensemble de messages utilisateur optimisés à la page Créer une intention. Une fois la fonctionnalité activée, une fenêtre instantanée affiche ces messages une fois que les utilisateurs ont entré au moins trois caractères. Les mots des messages suggérés qui correspondent à l'entrée utilisateur sont affichés en gras. A partir de là, les utilisateurs peuvent saisir leur propre entrée ou choisir l'un des messages d'écriture automatique.
Remarque

Cette fonctionnalité n'est disponible que sur WebSocket.

Description de l'image autocomplete-phrase-list.png
Description de l'image autocomplete-phrase-list.png

Lorsqu'un assistant numérique est associé au canal Oracle Web, tous les exemples de variation configurés pour l'une des briques inscrites auprès de cet assistant numérique peuvent être utilisés en tant que suggestions d'écriture automatique.

Soumission automatique d'un champ

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

Remplacement d'un formulaire de saisie précédent

Lorsque l'utilisateur final soumet le formulaire, car autosubmit est défini sur true dans un champ, la brique peut envoyer un nouveau EditFormMessagePayload. Ce message doit remplacer le message de formulaire d'entrée précédent. En définissant la propriété d'extension de canal replaceMessage sur true, vous autorisez le kit SDK à remplacer le message de formulaire d'entrée précédent par le message de formulaire d'entrée en cours.

Mise en page automatique RTL

Lorsque la direction de base de la page hôte est définie avec <html dir="rtl"> pour s'adapter aux langues écrites de droite à gauche, le widget de discussion s'affiche automatiquement à gauche. Etant donné que le widget est aligné à gauche pour les langues écrites de droite à gauche, ses icônes et ses éléments de texte sont également repositionnés. Les icônes se trouvent dans des positions opposées à celles de l'affichage pour les langues écrites de gauche à droite. Par exemple, les icônes d'envoi, de micro et de pièce jointe sont inversées : les icônes de micro et d'envoi occupent le côté gauche du champ de saisie (l'icône d'envoi directionnelle pointant vers la gauche) tandis que l'icône de pièce jointe se trouve du côté droit du champ de saisie. L'alignement des éléments de texte tels que inputPlaceholder et chatTitle dépend de l'écriture de gauche à droite ou de droite à gauche de la langue. Pour les langues écrites de droite à gauche, le texte inputPlaceHolder et chatTitle apparaissent sur le côté droit du champ de saisie.

Avatars

Par défaut, aucun des messages de la discussion n'est accompagné d'un avatar. Toutefois, à l'aide des paramètres suivants, vous pouvez configurer des avatars pour la brique et l'utilisateur, et pour l'agent lorsque la brique intègre la prise en charge des agents physiques.
  • avatarBot : URL de la source d'image ou chaîne source de l'image SVG affichée en regard des messages de brique.
  • avatarUser : URL de la source d'image ou chaîne source de l'image SVG affichée en regard des messages utilisateur. En outre, si la brique dispose d'une intégration d'agent physique, le kit SDK peut être configuré de manière à 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 affichée en regard des messages d'agent. Si cette valeur n'est pas fournie, mais que avatarBot est défini, l'icône avatarBot est utilisée à la place.
Remarque

Ces paramètres peuvent être transmis uniquement dans les paramètres d'initialisation. Ils ne peuvent pas être modifiés de façon dynamique. 
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 conversations entre onglets

Indicateur de fonctionnalité : enableTabsSync: true (valeur 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 fonctionnalité garantit que les utilisateurs peuvent afficher les messages de la brique sur n'importe quel onglet et répondre à partir du même onglet ou de tout autre onglet. De plus, si l'utilisateur efface l'historique des conversations dans un onglet, il est également supprimé des autres onglets. Si l'utilisateur met à jour la langue de discussion dans un onglet, la langue de discussion est synchronisée avec les autres onglets.

Restrictions :
  • Un nouvel onglet est synchronisé avec les onglets existants pour les nouveaux messages entre l'utilisateur et la brique lors de l'ouverture. Si vous n'avez pas configuré le kit SDK pour qu'il affiche les messages de l'historique de conversation, le widget de discussion initial du nouvel onglet apparaît vide lorsqu'il est ouvert.
  • Si vous avez configuré le kit SDK pour qu'il affiche l'historique des conversations, les messages de la discussion en cours sur les onglets existants apparaîtront dans l'historique des conversations sur un nouvel onglet. La définition de disablePastActions sur all ou postback peut empêcher toute interaction avec les actions des messages dans le nouvel onglet.
  • Le navigateur Safari ne prend actuellement pas en charge cette fonctionnalité.

Rendu de message personnalisé

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

Utilisez cette fonctionnalité pour remplacer l'affichage des messages par défaut par votre propre modèle de message personnalisé. Pour utiliser cette fonctionnalité, vous devez implémenter la fonction de délégation render qui prend le modèle de message comme entrée et renvoie un indicateur booléen comme sortie. Il doit renvoyer true pour remplacer le rendu par défaut par votre rendu personnalisé pour un type de message particulier. Si false est renvoyé, le message par défaut est affiché à la place.
Remarque

Pour un rendu personnalisé, la gestion de tous les clics d'action et la désactivation ou l'activation de l'action doivent être traitées explicitement.
Vous pouvez utiliser n'importe quel composant de structure externe pour l'affichage des messages. Reportez-vous aux exemples d'intégration inclus dans le répertoire samples du kit SDK pour savoir comment utiliser cette fonctionnalité avec des structures telles que React, Angular et Oracle JavaScript Extension Toolkit (JET).

Réponses client par défaut

Indicateur de fonctionnalité : enableDefaultClientResponse: true (valeur 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 brique a été retardée ou lorsqu'il n'y a aucune réponse de brique. Si l'utilisateur envoie le premier message/la première requête, mais que la brique ne répond pas dans les secondes définies par l'indicateur defaultGreetingTimeout, la brique peut afficher un message d'accueil configuré à l'aide de la chaîne de traduction defaultGreetingMessage. Ensuite, le client vérifie à nouveau la réponse de la brique. Le client affiche la réponse de brique si elle a été reçue, mais si ce n'est pas le cas, 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 brique 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 des fonctionnalités : delegate

La fonctionnalité de délégation définit un délégué pour recevoir les callbacks avant certains événements dans 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 de modifier le message d'une brique avant de l'afficher dans la conversation. Le message renvoyé par le délégué s'affiche à la place du message d'origine. Le message renvoyé n'est pas affiché si le délégué renvoie une valeur fausse telle que null, undefined ou false. Si le délégué renvoie une erreur, le message d'origine s'affiche à la place du message renvoyé par le délégué. Utilisez le délégué beforeDisplay pour appliquer de manière sélective le comportement des liens de vue Web dans le widget.

beforeSend

Le délégué beforeSend permet de modifier un message utilisateur avant qu'il ne soit envoyé au serveur de discussion dans le cadre de sendMessage. Le message renvoyé par le délégué est envoyé à la brique au lieu du message d'origine. Le message renvoyé par le délégué n'est pas défini si ce dernier renvoie une valeur erronée telle que null, undefined ou false, le message n'est pas envoyé. En cas d'erreur, le message d'origine est envoyé à la place du message renvoyé par le délégué.

beforePostbackSend

Le délégué beforePostbackSend est semblable à beforeSend, et est simplement appliqué aux messages de postback de l'utilisateur. Le postback renvoyé par le délégué est envoyé à la brique. S'il renvoie une valeur incorrecte, telle que null, undefined ou false, aucun message n'est envoyé.

beforeEndConversation

Le délégué beforeEndConversation autorise 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 renvoyer une valeur Promise. Si cette Promise est résolue avec le message de sortie, le message de sortie CloseSession est envoyé au serveur de discussion. Sinon, le message de sortie ne peut pas être envoyé.
...

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

recomposer

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

Bouton de lancement et widget déplaçables

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

Parfois, en particulier sur les appareils mobiles limitant la taille de l'écran, le widget de discussion ou le bouton de lancement peuvent bloquer du contenu sur une page Web. En définissant enableDraggableButton: true, vous pouvez permettre aux utilisateurs de faire glisser le widget ou le bouton de lancement vers l'extérieur lorsqu'il bloque la vue. Cet indicateur concerne uniquement l'emplacement du bouton de lancement, et non le widget de discussion : le widget est toujours ouvert à son emplacement d'origine.

Indicateur de saisie dynamique

Indicateur de fonctionnalité : showTypingIndicator: 'true'

Grâce à l'indicateur de saisie, les utilisateurs comprennent qu'ils peuvent s'interrompre dans l'envoi de messages car la brique prépare une réponse. Par défaut, les briques affichent l'indicateur de saisie uniquement pour leur première réponse lorsque vous initialisez le kit SDK avec showTypingIndicator: 'true'. Pour une expérience utilisateur optimale, la brique doit disposer d'un indicateur de saisie dynamique, qui est un indicateur de saisie affiché à chaque réponse de la brique. En plus d'informer les utilisateurs du fait que la brique n'est pas arrivée à expiration mais travaille toujours activement à une réponse, l'affichage de l'indicateur de saisie à chaque réponse de la brique veille à ce que les utilisateurs ne tentent pas d'envoyer des messages prématurément, comme cela peut être le cas lorsque la propriété keepTurn ordonne à la brique de répondre avec une série de messages distincts qui ne permettent pas à l'utilisateur de la couper avec une réponse.

Pour activer un indicateur de saisie à chaque réponse de la brique, effectuez les opérations suivantes :
  • Initialisez le kit SDK avec showTypingIndicator défini sur true.
  • Appelez l'API showTypingIndicator.
showTypingIndicator peut uniquement activer l'affichage de l'indicateur de saisie dynamique dans les circonstances suivantes :
  • Le widget est connecté au serveur de discussion Oracle. L'indicateur de saisie dynamique n'apparaît pas lorsque la connexion est fermée.
  • Le kit SDK a été initialisé avec showTypingIndicator défini sur true.
    Remarque

    Cette API ne peut pas fonctionner lorsque le kit SDK est utilisé en mode sans interface utilisateur.
L'indicateur de saisie apparaît pendant la durée définie par la propriété facultative typingIndicatorTimeout, dont la valeur par défaut est de 20 secondes. Si l'API est appelée alors qu'un indicateur de saisie est déjà affiché, l'horloge est réinitialisée et l'indicateur est masqué.

L'indicateur de saisie disparaît dès que l'utilisateur reçoit les messages de la brique. L'indicateur de saisie se déplace en bas de la fenêtre de discussion si un utilisateur saisit un message, télécharge une pièce jointe ou envoie une localisation pendant qu'il est affiché.

Contrôle du comportement des liens imbriqués

  • Gestion personnalisée : linkHandler: { onclick: <function>, target: '<string>' }
  • Dans la vue Web dans le widget : linkHandler: { target: 'oda-chat-webview' }
  • Dans une nouvelle fenêtre : openLinksInNewWindow: 'true'
Outre l'ouverture des liens dans une nouvelle fenêtre en définissant openLinksInNewWindow: true ou le comportement par défaut d'ouverture des liens dans un nouvel onglet, vous pouvez également ouvrir les liens en superposition à la page Web du widget. Pour activer cette option et d'autres remplacements du comportement des liens, initialisez le kit SDK avec : 
linkHandler: {
    target: '_blank',   // open link in a new page
    onclick: (event) => { // some operation }
}
Utilisez linkHander aux fins suivantes :
  • Contrôler la navigation iframe pour qu'elle puisse continuer la superposition à la page sans avoir à inclure le widget dans chaque page, à le rouvrir lors de la navigation et à conserver le même ID utilisateur.
    Description de l'image open-iframe.png
    Description de l'image open-iframe.png

  • Ouvrir certains liens dans une nouvelle fenêtre, mais d'autres dans le même onglet.
  • Effectuer une action lorsqu'un utilisateur clique sur un lien.
  • Empêcher l'ouverture d'un lien.
  • Ouvrir un lien dans une vue Web.
Pour remplacer le comportement défini pour les liens par le paramètre openLinksInNewWindow, vous devez définir l'un des attributs suivants ou les deux :
  • self : contexte de navigation actuel
  • target : nomme le contexte d'emplacement de navigation, tel qu'un onglet, une fenêtre ou 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 callback appelée lorsqu'un utilisateur clique sur le lien. Le callback est transmis à l'événement MouseEvent reçu lors du clic et peut être utilisé pour effectuer une action, voire pour empêcher l'ouverture du lien.

Mode imbriqué

  • Indicateur de fonctionnalité : embedded: true (valeur par défaut : false)
  • Transmettez l'ID de l'élément de conteneur cible : targetElement
Outre les autres paramètres qui personnalisent l'apparence du widget qui exécute la discussion, vous pouvez imbriquer le widget lui-même dans la page Web en :
  • ajoutant embedded: true,
  • définissant la propriété targetElement avec l'ID de l'élément DOM (composant HTML) utilisé en tant que conteneur du widget (par exemple, 'container-div' dans le fragment 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>
Remarque

Le widget occupe toute la largeur et la hauteur du conteneur. Si le conteneur ne le permet pas, le widget n'est pas affiché dans la page.

Terminer la session de conversation

Indicateur de fonctionnalité : enableEndConversation: true (valeur par défaut : true)

A partir de la version 21.12, le kit SDK ajoute un bouton de fermeture à l'en-tête du widget de discussion par défaut (enableEndConversation: true) qui permet aux utilisateurs de mettre fin à la session en cours.
Il s'agit d'une image du bouton de fermeture dans l'en-tête du widget de discussion.

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

Vous pouvez également mettre fin à une session en appelant la méthode Bots.endChat() (décrite dans la référence qui accompagne le kit SDK Web Oracle disponible sur la page Téléchargements). L'appel de cette méthode peut être utile lorsque le kit SDK est initialisé en mode sans interface utilisateur.

Focus sur la première action dans un message

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

Pour les utilisateurs qui préfèrent la navigation au clavier (superutilisateurs inclus), vous pouvez déplacer le focus du champ de saisie utilisateur vers le premier bouton d'action (ou le plus à gauche) dans un message. Par défaut, le widget de discussion rétablit le focus sur le champ de saisie utilisateur à chaque nouveau message (focusOnNewMessage: 'input'). Cette méthode fonctionne bien pour les flux de dialogue qui attendent d'importantes entrées textuelles de la part de l'utilisateur, mais lorsque le flux de dialogue implique un certain nombre de messages avec des actions, les utilisateurs peuvent uniquement sélectionner ces actions à l'aide de la souris ou de la navigation Maj+Tab. Pour ce cas d'emploi, vous pouvez passer le focus sur le premier bouton d'action dans le message de brique à sa réception en définissant focusOnNewMessage: 'action'. Si le message ne contient aucune action, le focus est défini sur le champ de saisie utilisateur.

Raccourcis clavier et raccourcis clavier

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

L'attribut n'est pas sensible à la casse.
Clé Elément
clearHistory Bouton qui efface l'historique des conversations.
close Bouton qui ferme le widget de discussion et met fin à la conversation.
collapse Bouton permettant de réduire le widget de discussion développé.
input Champ de saisie de texte dans le pied de page de la discussion
keyboard Bouton permettant de faire 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 discussion
mic Bouton permettant de faire passer le mode d'entrée du texte à la voix.
send Bouton qui envoie le texte d'entrée à la brique.
shareMenu Bouton de menu de partage dans le pied de page de la discussion
shareMenuAudio Option de menu dans la fenêtre instantanée de menu de partage qui sélectionne un fichier audio à partager.
shareMenuFile Option de menu dans la fenêtre instantanée de menu de partage qui sélectionne un fichier générique à partager
shareMenuLocation Option de menu de la fenêtre instantanée de menu de partage qui sélectionne l'emplacement de l'utilisateur à partager.
shareMenuVisual Option de menu dans le menu contextuel de partage qui sélectionne une image ou un fichier vidéo à partager.

SDK sans interface utilisateur

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

De même que pour les navigateurs Web sans interface utilisateur, le kit SDK peut également être utilisé sans son interface utilisateur. Le kit SDK gère la connexion au serveur et fournit des API pour envoyer des messages, en recevoir et obtenir des mises à jour sur le statut du réseau. Vous pouvez utiliser ces API pour interagir avec le kit SDK et mettre à jour l'interface utilisateur. Pour activer cette fonctionnalité, transmettez enableHeadless: true dans les paramètres initiaux. La communication peut être implémentée comme suit :
  • Envoi de messages : appelle Bots.sendMessage(message) pour transmettre la charge utile au serveur.
  • Réception des messages : permet d'écouter les réponses en utilisant Bots.on('message:received', <messageReceivedCallbackFunction>).
  • Obtention de la mise à jour du statut de connexion : écoute les mises à jour de statut de la connexion à l'aide de Bots.on('networkstatuschange', <networkStatusCallbackFunction>). Le callback comporte un paramètre de statut mis à jour avec des valeurs comprises entre 0 et 3, chacune étant mise en correspondance avec des états de socket Web :
    • 0 : WebSocket.CONNECTING
    • 1: WebSocket.OPEN
    • 2: WebSocket.CLOSING
    • 3: WebSocket.CLOSED
    • Renvoyer des suggestions pour une requête : renvoie une promesse résolue en suggestions pour la chaîne de requête donnée. La promesse est rejetée si l'extraction de la suggestion prend trop de temps (environ 10 secondes). 
      Bots.getSuggestions(utterance)
    .then((suggestions) => {
        const suggestionString = suggestions.toString();
        console.log('The suggestions are: ', suggestionString);
    })
    .catch((reason) => {
        console.log('Suggestion request failed', reason);
    });
    Remarque

    Pour utiliser cette API, vous devez activer l'écriture automatique :
    enableAutocomplete: true
    et la configurer pour les intentions.

Discussion multilingue

La prise en charge des langues natives du kit SDK Web permet au widget de discussion de détecter la langue de l'utilisateur ou de permettre aux utilisateurs de sélectionner la langue de la conversation. Les utilisateurs peuvent changer de langue, mais uniquement entre différentes conversations et pas au cours d'une conversation, car la conversation est réinitialisée chaque fois qu'un utilisateur sélectionne une nouvelle langue.

Activer le menu de langue

Vous pouvez activer un menu permettant aux utilisateurs de sélectionner une langue préférée dans un menu déroulant en définissant la propriété multiLangChat avec un objet contenant le tableau supportedLangs, composé de balises de langue (lang) et de libellés d'affichage facultatifs (label). En dehors de ce tableau, vous pouvez éventuellement définir la langue par défaut avec la clé primary (primary: 'en' dans le fragment de code suivant).
multiLangChat: {
    supportedLangs: [{
        lang: 'en'
    }, {
        lang: 'es',
        label: 'Español'
    }, {
        lang: 'fr',
        label: 'Français'
    }, {
        lang: 'hi',
        label: 'हिंदी'
    }],
    primary: 'en'
}
Le widget de discussion affiche les langues prises en charge transmises dans un menu déroulant situé dans l'en-tête. Outre les langues disponibles, le menu inclut également une option Détecter la langue. Lorsqu'un utilisateur sélectionne une langue dans ce menu, la conversation en cours est réinitialisée et une nouvelle conversation est démarrée avec la langue sélectionnée. La langue sélectionnée par l'utilisateur est conservée d'une session à l'autre dans le même navigateur. La langue précédente de l'utilisateur est donc automatiquement sélectionnée lorsque l'utilisateur revient sur la brique via la page contenant le widget de discussion.

Conseil :

Vous pouvez ajouter un processus d'écoute d'événement pour l'événement chatlanguagechange (décrit dans la référence accompagnant le kit SDK Web Oracle disponible à partir de la page Téléchargements), qui est déclenché lorsqu'une langue de discussion a été sélectionnée dans le menu déroulant ou a été modifiée.
Bots.on('chatlanguagechange', function(language) {
    console.log('The selected chat language is', language);
});
Lors de la configuration du menu déroulant de langue, tenez compte des points suivants :
  • 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 façon native : fr affiche Français dans le menu, es affiche Espagnol, etc.
  • Les libellés des langues peuvent être définis de façon dynamique par transmission avec le paramètre i18n. Vous pouvez définir le libellé de n'importe quelle langue en le transmettant à sa clé language_<languageTag>. Ce modèle permet de définir des libellés pour n'importe quelle langue, prise en charge ou non, et de traduire le libellé lui-même dans différents environnements locaux. 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 des champs tels que l'espace réservé d'entrée, le titre de la discussion, le texte de pointage des boutons et les titres d'info-bulle passent automatiquement dans la langue sélectionnée. Le texte du champ peut passer dans une autre langue uniquement s'il existe des chaînes de traduction pour la langue sélectionnée. Si aucune chaîne de traduction n'existe, la langue du texte du champ reste inchangée.
  • Le widget détecte automatiquement la langue dans le profil utilisateur et active l'option Détecter la langue si vous omettez la clé primary.
  • Bien que label soit facultatif, si vous avez ajouté une langue qui ne fait pas partie des langues prises en charge de façon native, vous devez ajouter un libellé pour identifier la balise, en particulier lorsqu'il n'existe aucune chaîne i18n pour la langue. Par exemple, si vous ne définissez pas label: 'हिंदी', pour lang: hi, la liste déroulante affiche hi, ce qui ne constitue pas une expérience utilisateur optimale.

Désactiver le menu de langue

A partir de la version 21.12, vous pouvez également configurer et mettre à jour la langue de discussion sans avoir à configurer le menu déroulant de sélection de la 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 en tant que langue de discussion pour la conversation.

Détection de la langue

Outre les langues transmises, le widget de discussion affiche l'option Détecter la langue dans la liste déroulante. La sélection de cette option indique à la brique de détecter automatiquement la langue de la conversation à partir du message de l'utilisateur et, si possible, de répondre dans la même langue.
Remarque

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

Vous pouvez mettre à jour dynamiquement la langue sélectionnée en appelant l'API setPrimaryChatLanguage(lang). Si la valeur lang transmise correspond à l'une des langues prises en charge, cette langue est sélectionnée. Si aucune correspondance n'est trouvée, la langue détectée 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 discussion de façon 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 dynamiquement la langue, que la langue de discussion soit initialement configurée ou non.
Remarque

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 Détecter la langue est définie. La sélection d'une langue non 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 de discussion multilingue

Procédez comme suit... ... Procédure
Afficher la liste déroulante de sélection de la langue pour les utilisateurs finaux. Transmettez multiLangChat.supportedLangs.
Définissez la langue de la discussion sans afficher le menu déroulant de sélection de la langue pour les utilisateurs finaux. Transmettez 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 dans le tableau.
Activer la détection de la langue. Transmettez primary: null ou primary: 'und' avec multiLangChat.
Mettez à jour dynamiquement le langage de discussion. Appelez l'API setPrimaryChatLanguage(lang).

Vue Web dans le widget

Vous pouvez configurer le comportement des liens dans les messages de discussion pour permettre aux utilisateurs d'accéder aux pages Web à partir du widget de discussion. Au lieu d'avoir à abandonner la conversation pour afficher une page dans un onglet ou dans une fenêtre de navigateur distincte, l'utilisateur peut rester dans la conversation, car le widget de discussion ouvre le lien dans une vue Web.

Configuration du comportement des liens avec la vue Web

Vous pouvez appliquer la vue Web à tous les liens, ou dans le cas d'emploi plus courant, à certains liens spécifiques uniquement. Vous pouvez également personnaliser la vue Web en elle-même.
  • Pour ouvrir tous les liens dans la vue Web, transmettez linkHandler: { target: 'oda-chat-webview' } dans les paramètres. La cible de tous les liens est ainsi définie sur oda-chat-webview, qui est le nom pour iframe dans la vue Web.
  • Pour ouvrir uniquement certains liens dans la vue Web tout en vous assurant que les autres liens sont ouverts normalement dans d'autres onglets ou fenêtres, utilisez le délégué beforeDisplay. Pour ouvrir une action d'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 ouvre le lien dans la vue Web lorsque vous cliquez dessus.

Ouverture de liens à partir de la vue Web

Les liens imbriqués dans une page affichée dans la vue Web peuvent uniquement être ouverts dans la vue Web lorsqu'ils sont convertis en éléments d'ancrage (<a>), avec un attribut cible défini sur target="oda-chat-webview".

Personnalisation de 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.
Remarque

La configuration peut également être mise à jour de façon dynamique via la transmission d'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 vue Web pour l'accessibilité Web.
closeButtonIcon Chaîne Chaîne SVG/d'URL d'image utilisée pour afficher l'icône du bouton de fermeture.
closeButtonLabel Chaîne Libellé de texte/titre d'info-bulle pour le bouton de fermeture.
closeButtonType
  • 'icon'
  • 'label'
  • 'iconWithLabel'
Définit l'affichage du bouton de fermeture de la vue Web.
referrerPolicy ReferrerPolicy Indique le référent à envoyer lors de l'extraction de la ressource du cadre. La valeur de stratégie referrerPolicy doit être une directive valide. La stratégie par défaut appliquée est 'no-referrer-when-downgrade'.
sandbox Tableau de chaînes Tableau de chaînes de restriction valides permettant d'exclure certaines actions dans le cadre. Les restrictions qui peuvent être transmises à ce champ sont incluses dans la description de l'attribut sandbox sur MDN Web Docs.
size
  • 'tall'
  • 'full'
Hauteur de la vue Web par rapport à la hauteur du widget de discussion. Lorsqu'elle est définie sur 'tall', elle correspond à 80 % de la hauteur du widget, mais lorsqu'elle est définie sur '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 être ouverts dans la vue Web. Voici quelques-unes des 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 iFrames. Dans ce cas, la vue Web présente à nouveau 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 être ouvertes dans WebViews, car les pages d'autorisation renvoient toujours X-frame-options: deny pour empêcher une attaque par détournement de clic.
  • Les liens externes ne peuvent pas être ouverts correctement dans la vue Web. Seuls les liens imbriqués dans les messages de conversation peuvent être ouverts dans la vue Web.
    Remarque

    Les messages externes étant incompatibles avec la vue Web, ne ciblez aucun lien externe à ouvrir dans la vue Web.
Lorsqu'un lien ne peut pas être ouvert 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}.'
        }
    }
}

Interrogation longue

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

Le kit SDK utilise des sockets Web pour se connecter au serveur et converser avec des briques. Si, pour une raison quelconque, le socket Web est désactivé sur le réseau, les appels HTTP traditionnels peuvent être utilisés pour discuter avec la brique. Cette fonctionnalité est appelée interrogation longue car le kit SDK doit appeler en continu (ou interroger) le serveur afin d'extraire les derniers messages de la brique. Cette fonctionnalité de basculement peut être activée en transmettant enableLongPolling: true dans les paramètres initiaux.

Indicateur de saisie pour les conversations utilisateur-agent

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

Cette fonctionnalité permet aux agents de vérifier si les utilisateurs sont toujours engagés dans la conversation en envoyant le statut de l'utilisateur à l'agent physique. Lorsque enableSendTypingStatus est défini sur true, le kit SDK envoie un événement de statut de saisie RESPONDING avec le texte en cours de saisie par l'utilisateur à Oracle B2C Service ou Oracle Fusion Service. Cela, à son tour, affiche un indicateur de saisie sur la console de l'agent. Lorsque l'utilisateur a terminé la saisie, le kit SDK envoie un événement LISTENING au service pour masquer l'indicateur de saisie 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 saisi par l'utilisateur et le statut de saisie, enableAgentSneakPreview (qui est par défaut false) doit être défini sur true et l'aperçu en avant-première doit être activé dans la configuration de discussion Oracle B2C Service.
Remarque

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 saisit, le kit 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, le kit SDK reçoit un message de statut LISTENING qui masque l'indicateur de saisie.

Reconnaissance vocale

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

Si vous définissez enableSpeech: true, le bouton de microphone sera affiché à la place du bouton d'envoi lorsque le champ d'entrée utilisateur est vide.

Votre brique peut également utiliser la reconnaissance vocale avec la méthode startVoiceRecording(onSpeechRecognition, onSpeechNetworkChange) pour démarrer l'enregistrement et la méthode stopVoiceRecording pour arrêter l'enregistrement. (Ces méthodes sont décrites dans le guide de l'utilisateur fourni avec le kit SDK.)

L'indicateur enableSpeechAutoSend vous permet de définir si vous souhaitez envoyer le texte reconnu à partir de la voix de l'utilisateur directement au serveur de discussion, sans saisie manuelle de la part de l'utilisateur. En définissant cette propriété sur true (valeur par défaut), vous autorisez l'envoi automatique de la réponse vocale de l'utilisateur au serveur de discussion. En la définissant sur false, vous permettez à l'utilisateur de modifier le message avant qu'il ne soit envoyé au serveur de discussion ou de le supprimer.

Visualiseur vocal

Configuration des fonctionnalités : enableSpeechAutoSend

Le widget de discussion affiche un visualiseur vocal lorsque les utilisateurs cliquent sur l'icône de voix Image de l'icône Parler du visualiseur vocal.. Il s'agit d'un indicateur spécifiant si le niveau audio est suffisamment élevé pour permettre au kit SDK de capturer la voix de l'utilisateur. Le message de l'utilisateur, tel qu'il est reconnu en tant que texte, s'affiche sous le visualiseur.
Remarque

Le mode vocal est signalé par l'affichage de l'icône de clavier Image de l'icône de clavier..
Description de l'image vocale visualizer.png
Description de l'image voice-visualizer.png
Le paramètre par défaut de enableSpeechAutosend étant true (enableSpeechAutoSend: true), les messages sont envoyés automatiquement une fois qu'ils sont reconnus. Si vous définissez enableSpeechAutoSend: false, le mode d'entrée passe au texte une fois le message vocal reconnu, ce qui permet aux utilisateurs de modifier ou de compléter leurs messages à l'aide de texte avant de les envoyer manuellement. Sinon, les utilisateurs peuvent compléter leurs messages avec la voix en cliquant sur l'icône vocale avant de les envoyer manuellement.
Remarque

Le visualiseur vocal est créé à l'aide d'AnalyserNode. Vous pouvez implémenter le visualiseur vocal en mode sans interface utilisateur à l'aide de la méthode startVoiceRecording. Pour en savoir plus sur AnalyserNode et les niveaux de fréquence, reportez-vous au kit SDK.