Aller au contenu principal

Smart Agents Avancé

Cette page couvre les comportements à connaître une fois le snippet en place : où Smart Agents est rendu, comment circulent les variables de dialogue, comment une conversation est persistée, et comment lire les erreurs d'initialisation.

Cible de rendu​

Smart Agents n'est pas injecté à l'endroit où se trouve la balise de script. Il est rendu, via un portail, dans un élément cible résolu au moment de l'appel à init() :

  1. Si un élément dont l'id correspond à containerId existe dans la page, Smart Agents est rendu à l'intérieur de cet élément.
  2. Sinon, Smart Agents est ajouté à <body>.

containerId vaut st-smartbot par défaut. Concrètement :

Votre page contient...Résultat
rienMode flottant : Smart Agents est ajouté à <body> et positionné par son CSS
<div id="st-smartbot"></div>Mode conteneur : Smart Agents est rendu à l'intérieur de ce bloc
<div id="my-bot"></div> + containerId: 'my-bot'Mode conteneur, dans votre propre élément
<!-- Mode conteneur : Smart Agents remplit ce bloc au lieu de flotter -->
<div id="st-smartbot" style="width: 400px; height: 600px"></div>
attention

L'élément cible doit déjà être présent dans le DOM lors de l'appel à init(). Un containerId qui désigne un élément créé plus tard (ou jamais) retombe silencieusement sur <body>, ce qui donne l'impression que « Smart Agents a ignoré mon conteneur ».

info

En mode conteneur, le dimensionnement et le positionnement sont à votre charge : le conteneur, c'est votre mise en page, et Smart Agents le remplit. Combinez-le avec ui.display.alwaysOpen: true pour obtenir un panneau de conversation déployé en permanence plutôt qu'une bulle à cliquer.

Variables de dialogue​

Les variables sont des valeurs personnalisées que votre page partage avec le dialogue, afin que le bot puisse saluer un visiteur par son prénom, s'orienter selon un type de contrat, ou passer une question dont il connaît déjà la réponse.

Définir des variables​

Les variables peuvent être fournies à l'initialisation :

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'fr',
      variables: {
        userName: 'Jean',
        isVIP: true,
        contractCount: 3,
      },
    });
  });
</script>

...puis mises à jour à tout moment ensuite :

<script type="text/javascript">
  window.stSmartBot.updateVariables({
    isVIP: false,
    cartAmount: 129.9,
  });
</script>

Comportements à connaître​

ComportementDétail
Types acceptésstring, number et boolean uniquement. Les objets imbriqués et les tableaux sont rejetés par le validateur.
Conversion en chaînesLes valeurs sont converties en chaînes avant d'être stockées. true devient "true", 3 devient "3". getVariables() renvoie donc toujours des chaînes.
Fusion, pas remplacementupdateVariables() fusionne les clés transmises avec l'ensemble existant. Les clés que vous ne mentionnez pas conservent leur valeur précédente, et il n'est pas possible de supprimer une clé.
Envoyées à chaque appelLes variables courantes sont attachées à chaque requête vers l'API de dialogue. Un appel à updateVariables() est pris en compte dès le message suivant du visiteur.
<script type="text/javascript">
  window.stSmartBot.updateVariables({ isVIP: true });
  window.stSmartBot.getVariables();
  // → { isVIP: "true" }  (chaîne, et non booléen)
</script>

Session de conversation et persistance​

Chaque conversation est rattachée à un identifiant de session généré par Smart Agents.

  • Mode par défaut : l'identifiant est stocké dans le localStorage du navigateur sous la clé smartBotSessionId. Le visiteur retrouve sa conversation après un rechargement de page ou une navigation, et la clé est conservée jusqu'à ce que le stockage du navigateur soit vidé.
  • Mode éphémère (ui.display.isEphemeralConversation: true) : l'identifiant n'est conservé qu'en mémoire, rien n'est donc écrit dans le localStorage. La fermeture de Smart Agents régénère l'identifiant et vide le dialogue à l'écran : la réouverture démarre une nouvelle conversation.
info

Le mode éphémère est ignoré lorsque ui.display.alwaysOpen vaut true : il n'y a pas de véritable fermeture dans ce mode, la conversation n'est donc jamais réinitialisée.

attention

Mentionnez l'entrée smartBotSessionId dans votre politique de cookies et de stockage local. Elle ne contient aucune donnée personnelle, mais elle est écrite sur l'appareil du visiteur dès que Smart Agents démarre une conversation.

Cibler une version du bot​

Deux réglages distincts déterminent ce que reçoit le visiteur, et ils sont souvent confondus :

RéglageCe qu'il sélectionne
L'URL du script (segment public/ ou non)Le build front de Smart Agents qui est chargé, comme décrit sur la page snippet.
Le paramètre envLa version publiée du bot avec laquelle la conversation s'exécute : production ou preproduction.

env est transmis à l'API de dialogue sous forme d'en-tête de requête. Il permet de tester un scénario de bot non encore publié, tout en conservant la même intégration :

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    e.detail.init({
      botId: 'xxx',
      locale: 'fr',
      env: 'preproduction',
    });
  });
</script>

Lorsque env est omis, aucune version n'est forcée et l'API de dialogue applique sa propre valeur par défaut.

attention

Ne livrez pas env: 'preproduction' sur vos pages de production : vos visiteurs dialogueraient avec une version non validée du scénario.

Erreurs d'initialisation​

init() valide chaque paramètre avant d'afficher quoi que ce soit. En cas d'échec, une erreur préfixée [Initialization Validator] est levée et Smart Agents reste masqué. Les cas les plus fréquents :

MessageCause
botId parameter is requiredbotId n'a pas été transmis.
botId parameter should be a stringbotId a été transmis sous forme de nombre. C'est une chaîne, même lorsqu'il ressemble à un nombre.
locale parameter is requiredlocale n'a pas été transmis.
locale parameter is not a valid locale: "xx"Le code de langue ne peut pas être résolu par le navigateur. Utilisez fr, en, en-GB, ...
locale parameter must be included in availableLocalesavailableLocales a été transmis sans y inclure la locale courante.
availableLocales parameter contains an invalid locale: "xx"Une des langues déclarées n'est pas un code valide.
env parameter should be one of 'production', 'preproduction'env a reçu une autre valeur, par exemple staging ou prod.
variables parameter should be an object of boolean, string or number, X is not a boolean, string or numberUne variable contient un objet ou un tableau. Aplatissez-la d'abord.
ui parameter should be an object of objects, X is not an objectUne entrée de ui a été transmise à plat, par exemple ui: { alwaysOpen: true } au lieu de ui: { display: { alwaysOpen: true } }.
info

Ces erreurs sont levées à l'intérieur de votre écouteur STSmartBotLoaded. Encadrez l'appel à init() d'un try/catch si vous souhaitez les remonter à votre propre supervision.

Paramètres réservés​

init() accepte également trois paramètres réservés à un usage interne Smart Tribune. Ils sont documentés ici pour qu'ils ne soient pas pris pour des options d'intégration :

ParamètreRôle
buildNameNom de la variante de build de Smart Agents. Il pilote la classe CSS st-smartbot-build-<nom> et les blocs conditionnels d'un build.
parameterEnvSurcharge l'environnement interne utilisé pour résoudre les URL des services Smart Tribune. Utilisé pour les environnements de développement Smart Tribune.
extraAccepté et validé par cohérence avec les autres produits Smart Tribune, mais non exploité par Smart Agents à ce jour.
attention

Renseigner ces paramètres vous-même n'a aucun effet supporté et peut casser les montées de version futures. Laissez-les en dehors de votre snippet, sauf demande explicite de votre contact Smart Tribune.