Snippet Smart Bot

Intégration

L'installation de la solution Smart Bot 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('STBOTLoaded', function (e) {
    e.detail.init({
      kbId: 0,
      locale: 'fr',
      cookieOptin: false,
      relativeRestPath: 'xxx',
    });
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/BOT/bot.main.js"
></script>

L'intégration du snippet de code ci-dessus suffit à permettre l'affichage partiel du BOT 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 bot.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 pre-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 à la base de connaissances spécifiée devront être préalablement déclarés directement dans la configuration de la base de connaissances dans Smart Dashboard.

Environnement de pré-production

attention

Le chemin d'accès au fichier bot.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/BOT/bot.main.js"
></script>

Script de PRE-PRODUCTION

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

Liste des variables

Variable	Type	Condition	Exemple	Description
kbId	int	requis	kbId : 0	Variable spécifique à chaque client, elle correspond à l'identifiant (identifiant système) de la base de connaissances à utiliser. Celle-ci est disponible dans Smart Dashboard, l'interface d'administration de contenus. Vous pouvez retrouver votre kbId sur la page d'accueil du Dashboard dans le cadre "Sélectionner une base de connaissances" puis "identifiant système".
locale	string	requis	locale : "fr"	Elle permet au client de spécifier dans quelle langue le dispositif doit être affiché. Cela est valable uniquement pour les bases de connaissances multilingues.
relativeRestPath	string	requis	relativeRestPath: "chemin/xx/..."	Cette variable de configuration permet de spécifier le chemin pour venir connecter le bot. Elle vous sera communiquée par l'Account Manager en charge de votre projet.
cookieOptin	bool	optionnel	cookieOptin : false	Elle permet d'empêcher ou non l'activation du cookie d'analyse des statistiques (valeur possible : true ou false). En désactivant cette fonctionnalité, il ne sera plus possible d'envoyer des informations dans le fournisseur d'analyse des statistiques pour votre FAQ. La valeur par défaut est false.
filters	object	optionnel	filters: { tags: ["tag-1"] }	Restreint le contenu que le bot est autorisé à servir. Voir Filtrer le contenu ci-dessous.
extra	object	optionnel	extra: { monGroupe: { plan: "premium" } }	Contexte additionnel transmis au dialogue, afin que le bot puisse s'orienter selon des données connues de votre page. Il doit s'agir d'un objet d'objets dont les valeurs terminales sont des chaînes, des nombres ou des booléens.

attention

kbId, locale et relativeRestPath sont 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 le Smart Bot n'est pas affiché. Attention, kbId est un nombre, pas une chaîne.

Filtrer le contenu

Le paramètre optionnel filters restreint les questions/réponses que le bot peut utiliser, de la même manière que la contextualisation de la Smart FAQ.

Propriété	Type	Description
thematics	string[]	Ne servir que le contenu associé à ces catégories.
tags	string[]	Ne servir que le contenu associé à tous ces tags (opérateur ET).
tagsOr	string[]	Ne servir que le contenu associé à au moins un de ces tags (opérateur OU).

<script type="text/javascript">
  window.addEventListener('STBOTLoaded', function (e) {
    e.detail.init({
      kbId: 0,
      locale: 'fr',
      cookieOptin: false,
      relativeRestPath: 'xxx',
      filters: {
        thematics: ['category-1'],
        tags: ['tag-1', 'tag-2'],
      },
    });
  });
</script>

attention

tags et tagsOr ne peuvent pas être utilisés en même temps : transmettre des valeurs dans les deux lève une erreur et le Smart Bot n'est pas affiché. Les tableaux vides sont simplement ignorés.

Les fonctions optionnelles

Utilisation la fonction show()

La fonction show() va vous permettre d'ouvrir la box.

Depuis un...	Description
bouton	Appelez simplement la fonction show() sur votre bouton.

<button onclick="window.stBot.show()">Btn</button>

Depuis un...	Description
timer	Placez un setTimeout dans une balise <script> après initialisation de Smart Bot.

<script type="text/javascript">
  window.addEventListener('STBOTLoaded', function (e) {
    var stBot = e.detail;
    stBot.init({
      kbId: 0,
      locale: 'fr',
      cookieOptin: false,
      relativeRestPath: 'xxx',
    });
    setTimeout(() => {
      stBot.show();
    }, 3000);
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/BOT/bot.main.js"
></script>

Depuis un...	Description
scroll	Placez un écouteur après initialisation de Smart Bot.

<script type="text/javascript">
  window.addEventListener('STBOTLoaded', function (e) {
    var stBot = e.detail;
    stBot.init({
      kbId: 0,
      locale: 'fr',
      cookieOptin: false,
      relativeRestPath: 'xxx',
    });
    window.addEventListener(
      'scroll',
      function (e) {
        stBot.show();
      },
      false,
    );
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/BOT/bot.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 stBot à l'interieur de window qui est une variable globale :

<script type="text/javascript">
  window.addEventListener('STBOTLoaded', function (e) {
    window.stBot = e.detail;
    window.stBot.init({
      kbId: 0,
      locale: 'fr',
      cookieOptin: false,
      relativeRestPath: 'xxx',
    });
  });
</script>
<script
  type="text/javascript"
  async
  src="https://assets.app.smart-tribune.com/smart-tribune/BOT/bot.main.js"
></script>

Utilisation de la fonction hide()

La fonction hide() va vous permettre de fermer la box.

Depuis un...	Description
button	Appelez simplement la fonction hide() sur votre bouton.

<button onclick="window.stBot.hide()">Btn</button>

Utilisation de la fonction off()

La fonction off() va vous permettre de faire disparaitre la box de la page.

Depuis un...	Description
button	Appelez simplement la fonction off() sur votre bouton.

<button onclick="window.stBot.off()">Btn</button>

Utilisation de la fonction on()

La fonction on() va vous permettre de faire apparaitre la box sur la page.

Depuis un...	Description
bouton	Appelez simplement la fonction on() sur votre bouton.

<button onclick="window.stBot.on()">Btn</button>

Utilisation de la fonction send()

La fonction send() va vous permettre d'envoyer un message ou de déclencher une intention au nom du visiteur, par exemple pour ouvrir le bot directement sur un sujet donné selon la page.

Appelée avec...	Description
une chaîne	Envoyée comme message du visiteur. send("Bonjour") est un raccourci pour send({ message: "Bonjour" }).
{ message: "..." }	Envoyé comme message du visiteur.
{ intent: "..." }	Déclenche l'intention indiquée du dialogue, sans afficher de message visiteur.
{ intent: "...", message: "..." }	Déclenche l'intention indiquée et affiche message comme message du visiteur dans la conversation.

<button onclick="window.stBot.send('Je veux suivre ma commande')">Suivre ma commande</button>
<button onclick="window.stBot.send({ intent: 'delivery_tracking' })">Suivre ma commande</button>

attention

Appeler send() sans message ni intent lève une erreur. Le Smart Bot doit avoir été initialisé au préalable.

Utilisation de la fonction reset()

La fonction reset() va vous permettre de vider la conversation en cours et d'en démarrer une nouvelle.

Depuis un...	Description
bouton	Appelez simplement la fonction reset() sur votre bouton.

<button onclick="window.stBot.reset()">Recommencer la conversation</button>

Utilisation de la fonction read()

La fonction read() renvoie une copie des paramètres avec lesquels le Smart Bot a été initialisé, ou undefined si init() n'a pas encore été appelé. Elle sert surtout à vérifier une intégration depuis la console du navigateur.

<script type="text/javascript">
  var config = window.stBot.read();
  console.log(config);
</script>

Événements

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

STBOTLoaded

Déclenché lorsque le script du Smart Bot est chargé et prêt à être initialisé. Son detail est l'objet qui porte init(), show(), hide(), on(), off(), send(), reset() et read().

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

info

Cet événement n'est émis qu'une seule fois par chargement de page. Déclarez votre écouteur avant la balise de script bot.main.js, sans quoi il peut déjà avoir été émis au moment où votre écouteur est attaché.

STBOTInitialized

Déclenché à chaque fois que init() se termine avec succès. Son detail contient les paramètres d'initialisation validés.

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