Aller au contenu principal

Snippet Smart Agents

info

Smart Agents est le nom actuel du produit anciennement appelé Smart Bot. Les deux noms désignent la même solution. Le script, les classes CSS et l'API JavaScript conservent leur nommage historique smartbot / STSmartBot : c'est normal, et rien n'est à modifier dans une intégration existante.

Intégration​

L'installation de la solution Smart Agents sur le site du client s'effectue en intégrant un snippet de code javascript au sein de la page souhaitée.

JS​

Le snippet Javascript doit être intégré juste avant la fermeture de la balise </body>. Cette contrainte est impérative : le script Smart Tribune doit être chargé le plus en aval possible dans la chaîne de chargement des scripts afin d'éviter tout conflit avec les scripts tiers présents sur la page client.

Tout écart par rapport à cette instruction engage la seule responsabilité du client. Smart Tribune ne pourra être tenu responsable de dysfonctionnements, conflits de scripts ou dégradations de performance résultant d'une intégration non conforme.

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    e.detail.init({
      botId: 'xxx',
      locale: 'fr',
    });
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

L'intégration du snippet de code ci-dessus suffit à permettre l'affichage partiel de Smart Agents au sein de la page. Il faut également communiquer votre nom de domaine à votre point de contact Smart Tribune pour que nous autorisions le produit à s'afficher complètement sur votre environnement.

Attention, le lien vers smartbot.main.js est une démonstration du produit, le dossier smart-tribune dans l'url sera à remplacer par celui qui vous sera communiqué. L'url change complètement lors du passage de la pré-production (public) à la production. L'url complète est communiquée par votre point de contact Smart Tribune en charge de votre dossier.

info

Les domaines faisant appel au bot spécifié devront être préalablement déclarés directement dans la configuration du bot dans Smart Dashboard.

Environnement de pré-production​

attention

Le chemin d'accès au fichier smartbot.main.js évolue en fonction de l'environnement : public ou production. Cette url diffère selon l'environnement sur lequel le dispositif doit être installé sur le site client. Il est d'usage d'utiliser PUBLIC pour la pré-production et d'utiliser PRODUCTION pour la production chez le client. Toutes ces informations sont communiquées par Smart Tribune après la phase de développement.

Script de PRODUCTION​

<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

Script de PRE-PRODUCTION​

<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/public/smartbot.main.js"
></script>

Liste des variables​

VariableTypeConditionExempleDescription
botIdstringrequisbotId: "xxx"Variable spécifique à chaque client, elle correspond à l'identifiant du bot à utiliser. Celle-ci est disponible dans Smart Dashboard, l'interface d'administration de contenus. Elle vous sera communiquée par votre Account Manager.
localestringrequislocale: "fr"Elle permet au client de spécifier dans quelle langue le dispositif doit être affiché. Cela est valable uniquement pour les bots multilingues. La valeur doit être un code de langue que le navigateur sait résoudre (fr, en, en-GB, ...) ; un code inconnu fait échouer init().
availableLocalesstring[]optionnelavailableLocales: ["fr","en"]Liste des langues vers lesquelles vous autorisez Smart Agents à basculer à l'exécution. locale doit faire partie de cette liste. Voir la page Multilingue. Vaut [locale] par défaut.
containerIdstringoptionnelcontainerId: "my-bot"Identifiant de l'élément HTML dans lequel Smart Agents sera rendu. Par défaut, la valeur est st-smartbot. Si aucun élément ne porte cet identifiant, Smart Agents est ajouté à <body>. Voir Cible de rendu.
envstringoptionnelenv: "preproduction"Version publiée du bot avec laquelle la conversation s'exécute : production ou preproduction. Ce réglage n'est pas celui de l'URL du script. Voir Cibler une version du bot.
variablesobjectoptionnelvariables: { key: value }Objet contenant des variables personnalisées (string, number ou boolean) qui seront transmises au dialogue. Les valeurs sont converties en chaînes avant l'envoi. Voir Variables de dialogue.
botIntentstringoptionnelbotIntent: "welcome"Intention jouée au démarrage de la conversation, à la place du point d'entrée par défaut du bot. Utile pour ouvrir Smart Agents directement sur une étape donnée selon la page.
authbooloptionnelauth: trueActive ou désactive le système d'authentification. Lorsqu'il est activé, le visiteur doit se connecter avant d'accéder au dialogue. La valeur par défaut est false.
uiobjectoptionnelui: { display: {...} }Paramètres d'interface utilisateur (voir section dédiée ci-dessous).
attention

botId et locale sont les deux seuls paramètres obligatoires. Chaque paramètre est validé à l'appel de init() : un paramètre obligatoire manquant ou un type incorrect lève une erreur préfixée [Initialization Validator] dans la console du navigateur, et Smart Agents n'est pas affiché. Voir Erreurs d'initialisation.

info

extra, parameterEnv et buildName sont également acceptés par init(). Ils sont réservés à un usage interne Smart Tribune et ne doivent pas être renseignés par l'intégrateur. Voir Paramètres réservés.

Paramètres UI​

Le paramètre ui permet de configurer l'interface utilisateur de Smart Agents. Toutes les propriétés sont optionnelles ; ne transmettez que celles que vous souhaitez modifier.

ui: {
  display: {
    alwaysOpen: true,
    displayAiGenerationVoteSatisfaction: true,
    displayAiGenerationLoader: true,
    isEphemeralConversation: false,
    header: {
      buttons: 'menu'
    }
  },
  authentication: {
    defaultLoginMethod: "sso",
    account: "my-account",
    SSOMode: "sso_popup",
    SSOPopupUrl: "https://login.example.com/sso"
  }
}

ui.display​

PropriétéTypeDéfautDescription
alwaysOpenboolfalseSi true, Smart Agents reste toujours ouvert sans possibilité de le fermer. Le bouton d'ouverture et hide() ne retirent plus la conversation de l'écran.
displayAiGenerationVoteSatisfactionboolfalseSi true, affiche le vote de satisfaction pour les réponses générées par l'IA.
displayAiGenerationLoaderbooltrueAffiche l'indicateur de chargement pendant la génération d'une réponse par l'IA. Passez false pour le masquer.
isEphemeralConversationboolfalseMode éphémère. L'identifiant de conversation n'est conservé qu'en mémoire, et la fermeture de Smart Agents démarre une nouvelle conversation à la réouverture. Ignoré lorsque alwaysOpen vaut true. Voir Session de conversation.
header.buttonsstringlistDisposition des actions de l'en-tête : list les affiche côte à côte, menu les regroupe dans un menu déroulant.

ui.authentication​

Ces propriétés n'ont d'effet que lorsque auth: true.

PropriétéTypeDéfautDescription
defaultLoginMethodstringpasswordFormulaire de connexion affiché en premier. Valeurs possibles : password, sso (redirection pleine page) ou sso_popup (fenêtre popup dédiée).
accountstring–Identifiant du compte pour l'authentification. Lorsqu'il est renseigné, il est transmis au fournisseur SSO via le paramètre d'URL org.
SSOModestringssoFlux SSO attendu lorsque le fournisseur redirige vers votre page avec ?ssocallback. Valeurs possibles : sso ou sso_popup. Il doit correspondre au flux réellement démarré par le visiteur.
SSOPopupUrlstringURL Smart TribuneURL ouverte dans la fenêtre popup en mode sso_popup. Les paramètres openerOrigin (et org si account est renseigné) y sont ajoutés automatiquement.

Les fonctions optionnelles​

Utilisation de la fonction show()​

La fonction show() va vous permettre d'ouvrir Smart Agents.

Depuis un...Description
boutonAppelez simplement la fonction show() sur votre bouton.
<button onclick="window.stSmartBot.show()">Ouvrir le chat</button>
Depuis un...Description
timerPlacez un setTimeout dans une balise <script> après initialisation de Smart Agents.
<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'fr',
    });
    setTimeout(() => {
      window.stSmartBot.show();
    }, 3000);
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>
Depuis un...Description
scrollPlacez un écouteur après initialisation de Smart Agents.
<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'fr',
    });
    window.addEventListener(
      'scroll',
      function (e) {
        window.stSmartBot.show();
      },
      false,
    );
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

Si vous avez besoin d'utiliser ces fonctions en dehors du script (sur un bouton par exemple), vous aurez besoin de stocker stSmartBot à l'intérieur de window qui est une variable globale :

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'fr',
    });
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

Utilisation de la fonction hide()​

La fonction hide() va vous permettre de fermer Smart Agents.

Depuis un...Description
boutonAppelez simplement la fonction hide() sur votre bouton.
<button onclick="window.stSmartBot.hide()">Fermer le chat</button>

Utilisation de la fonction read()​

La fonction read() va vous permettre de récupérer les paramètres d'initialisation actuels.

Depuis un...Description
scriptAppelez la fonction read() pour obtenir la configuration.
<script type="text/javascript">
  var config = window.stSmartBot.read();
  console.log(config);
</script>

Utilisation de la fonction updateVariables()​

La fonction updateVariables() va vous permettre de mettre à jour les variables du dialogue en cours.

Depuis un...Description
scriptAppelez la fonction updateVariables() avec un objet contenant les nouvelles valeurs.
<script type="text/javascript">
  window.stSmartBot.updateVariables({
    userName: 'Jean',
    isVIP: true,
    accountAge: 5,
  });
</script>

Utilisation de la fonction getVariables()​

La fonction getVariables() va vous permettre de récupérer les variables actuelles du dialogue.

Depuis un...Description
scriptAppelez la fonction getVariables() pour obtenir les variables.
<script type="text/javascript">
  var variables = window.stSmartBot.getVariables();
  console.log(variables);
</script>

Utilisation de la fonction setLocale()​

La fonction setLocale() va vous permettre de basculer Smart Agents dans une autre langue à l'exécution, sans recharger la page.

Depuis un...Description
boutonAppelez simplement la fonction setLocale() avec le code de la langue.
<button onclick="window.stSmartBot.setLocale('en')">English</button>
<button onclick="window.stSmartBot.setLocale('fr')">Français</button>
attention

La langue cible doit être déclarée dans availableLocales, et l'appel à setLocale() réinitialise la conversation en cours. Voir la page Multilingue pour le comportement complet.

Événements​

Smart Agents émet des événements personnalisés que vous pouvez écouter :

STSmartBotLoaded​

Déclenché lorsque le script Smart Agents est chargé et prêt à être initialisé.

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    console.log('Smart Agents chargé', e.detail);
  });
</script>

STSmartBotInitialized​

Déclenché lorsque Smart Agents a été initialisé avec succès.

<script type="text/javascript">
  window.addEventListener('STSmartBotInitialized', function (e) {
    console.log('Smart Agents initialisé', e.detail);
  });
</script>

STSmartBotLocaleChanged​

Déclenché lorsque la langue a effectivement été changée par setLocale(). Son detail contient le nouveau code de langue.

<script type="text/javascript">
  window.addEventListener('STSmartBotLocaleChanged', function (e) {
    console.log('La langue de Smart Agents est désormais', e.detail.locale);
  });
</script>

STSmartBotClickableButtonClicked​

Déclenché lorsque le visiteur clique sur un bouton cliquable configuré dans Smart Agents. Son detail contient le nom du bouton, ce qui vous permet de brancher votre propre comportement (ouverture d'un formulaire, suivi d'une conversion, ...) sur une interaction du bot.

<script type="text/javascript">
  window.addEventListener('STSmartBotClickableButtonClicked', function (e) {
    console.log('Bouton cliqué dans Smart Agents :', e.detail);
  });
</script>
info

STSmartBotLoaded n'est émis qu'une seule fois par chargement de page, avant tout appel à init(). Déclarez votre écouteur avant la balise de script smartbot.main.js, sans quoi l'événement peut déjà avoir été émis au moment où votre écouteur est attaché.

Exemple complet​

Voici un exemple d'intégration complet avec toutes les options :

<script type="text/javascript">
  window.addEventListener('STSmartBotLoaded', function (e) {
    window.stSmartBot = e.detail;
    window.stSmartBot.init({
      botId: 'xxx',
      locale: 'fr',
      availableLocales: ['fr', 'en'],
      containerId: 'st-smartbot',
      env: 'production',
      botIntent: 'welcome',
      variables: {
        userName: 'John',
        userType: 'premium',
      },
      auth: true,
      ui: {
        display: {
          alwaysOpen: false,
          displayAiGenerationVoteSatisfaction: true,
          displayAiGenerationLoader: true,
          isEphemeralConversation: false,
          header: {
            buttons: 'list',
          },
        },
        authentication: {
          defaultLoginMethod: 'sso',
          account: 'my-account',
          SSOMode: 'sso',
        },
      },
    });
  });

  window.addEventListener('STSmartBotInitialized', function (e) {
    console.log('Smart Agents prêt !');
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/SmartBot/smartbot.main.js"
></script>

Pour aller plus loin​

  • Multilingue — changer de langue à l'exécution.
  • Avancé — cible de rendu, variables de dialogue, session de conversation, ciblage d'une version du bot et erreurs d'initialisation.