Setup guide V2

Liens vers: Documentation v2,
Documentation v1

Documentation V2

Intégration Smart Tribune

Objet du document

Ce document a pour but d’expliquer en détail les différentes procédures pour intégrer les solutions proposées par Smart Tribune.
Dernière mise à jour le : 25/11/2020


Intégration de Smart FAQ

Etape 1: Intégration de la solution

L’installation de la solution Smart FAQ sur le site du client s’effectue en intégrant un bout de HTML et un snippet de code javascript au sein de la page souhaitée.

Etape 1.1: Intégration du HTML à la page qui va contenir Smart FAQ.

Intégrer le bout de code HTML à l’endroit dans votre code où la FAQ doit s’afficher.

<div id="st-faq"></div>
Etape 1.2: Intégration du JS à la page qui va contenir Smart FAQ.

Intégrer le snippet Javascript juste avant la fermeture de la balise </body>. Le script Smart Tribune doit être chargé le plus en aval possible dans la chaîne de chargement des scripts afin d’éviter d’éventuels conflits avec les scripts présents sur la page client.

<script type="text/javascript">
    window.addEventListener('STFAQLoaded', function(e){
         e.detail.init({
            "analyticsUA": "UA-00000000-0",
            "kbId":2,
            "locale":"fr",
            "cookieOptin":false,
            "filters":{
                "thematics":[],
                "tags":[]
            }
        });
    });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/FAQ/faq.main.js"></script>

Lien vers la démonstration live : Cliquez ici

L’intégration du snippet de code ci-dessus suffit à permettre l’affichage partiel de la FAQ 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 faq.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.

Variable Type Condition Exemple Description
analyticsUA string optionnel "analyticsUA" : "UA-00000000-0" Cette variable permet de contenir l’UA Google Analytics dans le but de vous envoyer différentes informations relatives à l’activité de vos visiteurs.
kbId int requis "kbId" : 2 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. La base de connaissances intégrant déjà du contenu de test est identifié par la valeur : 2. 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.
buildName string optionnel "buildName" : "design-2" Cette variable est très pratique si vous avez une FAQ qui doit changer de couleur (par exemple) entre un espace public et un espace membre. Si cela est nécessaire à votre produit Smart Tribune, la valeur de la variable vous sera communiquée après la phase de développement.
cookieOptin bool required "cookieOptin" : false Elle permet d’empêcher ou non l’activation du cookie Google Analytics (valeur possible : true ou false). En désactivant cette fonctionnalité, il ne sera plus possible d’envoyer des informations dans Google Analytics pour votre FAQ. La valeur par défaut est false.
searchFiltered bool optionnel "searchFiltered" : true Cette variable permet de contextualiser la recherche avec les valeurs du paramètre filters. La valeur par défaut est true afin que le moteur de recherche renvoie uniquement des résultats dans le contexte choisi. La valeur false permet de rendre accessible tous les contenus de la base de connaissances dans le moteur de recherche.
customVariables obj optionnel "customVariables" : { "marque":"Smart Tribune"} Cette variable permet de remplacer la valeur d’un jeton de personnalisation créé dans le contenu d’une réponse via Smart Dashboard. Note : On attend ici une chaîne de caractères qui peut contenir des balises HTML (span, a, b, u, i, br, img) avec ses attributs (id, class, style, name, title, target, href, rel, src, alt).
filters obj optionnel "filters" : { "thematics":[], "tags":[] } Cette variable de configuration permet de spécifier la contextualisation de la FAQ à appliquer. Il est possible de définir le filtrage en utilisant l’identifiant système thematics ou tags. L’opérateur utilisé est AND dans le cas de multiples valeurs au sein du même filtre ou entre les filtres. Note : Ces objets contiennent un tableau (array) de chaîne de caractères (string).
headerId string optionnel "headerId": "headerTop" Cette variable de configuration permet de spécifier l’identifiant de votre menu horizontal. L’intéret de cette option réside dans le fait qu’elle corrige les problèmes de Scroll lors que le menu horizontal est dans un état CSS : ‘position: fixed’. Dans cet état le menu peut cacher, dans certain cas, des éléments de la FAQ lorsque celle-ci est affichée.

NOTE IMPORTANTE: Le chemin d’accès au fichier faq.js évolue en fonction de l’environnement : public, 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.

ACTION REQUISE: 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.

Etape 2: Contextualisation de Smart FAQ

Cas de contextualisation #1: Filtrer en fonction de plusieurs tags.

Je souhaite seulement afficher des questions/réponses qui sont associées aux tags suivants: “tag-1”, “tag-2”.

"filters":{
    "thematics":[],
    "tags":[
        "tag-1",
        "tag-2"
    ]
}
Cas de contextualisation #2: Filtrer en fonction de plusieurs catégories.

Je souhaite seulement afficher des questions/réponses qui sont associées aux catégories suivantes: “category-1”, “category-2”.

"filters":{
    "thematics":[
        "category-1",
        "category-2"
    ],
    "tags":[]
}
Cas de contextualisation #3: Filtrer en fonction d’un tag et d’une catégorie.

Je souhaite seulement afficher des questions/réponses qui sont associées à la fois à la catégorie “category-1” ET au tag “tag-1”.

"filters":{
    "thematics":[
        "category-1"
    ],
    "tags":[
        "tag-1"
    ]
}
Cas de contextualisation #4: Customiser le contenu avec “customVariables” et du HTML.

Je souhaite que les “customVariables” se nommant “marque” et “persona” que j’ai paramétré depuis mon Back-Office V2 prennent pour valeur, les données suivantes:

"customVariables": {
   "marque": "<a href='https://smart-tribune.com' target='_blank'><span class='demo'>Smart Tribune</span></a>",
   "persona":"<b>Particuliers</b>",
},


Intégration de Smart PUSH

Etape 1: Intégration de la solution

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

Etape 1.1: Intégration du JS à la page qui va contenir Smart PUSH.

Intégrer le snippet Javascript juste avant la fermeture de la balise </body>. Le script Smart Tribune doit être chargé le plus en aval possible dans la chaîne de chargement des scripts afin d’éviter d’éventuels conflits avec les scripts présents sur la page client.

<script type="text/javascript">
    window.addEventListener('STPUSHLoaded', function(e) {
        var stPush = e.detail;
        stPush.init({
            "analyticsUA": "UA-00000000-0",
            "searchFiltered": false,
            "kbId": 2,
            "locale": "fr",
            "cookieOptin": false,
            "filters": {
                "thematics": [],
                "tags": []
            },
        });
    });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/PUSH/push.main.js"></script>

Lien vers la démonstration live : Cliquez ici

L’intégration du snippet de code ci-dessus suffit à permettre l’affichage partiel de la PUSH 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 push.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.

Variable Type Condition Exemple Description
analyticsUA string optionnel "analyticsUA" : "UA-00000000-0" Cette variable permet de contenir l’UA Google Analytics dans le but de vous envoyer différentes informations relatives à l’activité de vos visiteurs.
kbId int requis "kbId" : 2 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. La base de connaissances intégrant déjà du contenu de test est identifié par la valeur : 2. 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.
cookieOptin bool required "cookieOptin" : false Elle permet d’empêcher ou non l’activation du cookie Google Analytics (valeur possible : true ou false). En désactivant cette fonctionnalité, il ne sera plus possible d’envoyer des informations dans Google Analytics pour Smart Push. La valeur par défaut est false.
searchFiltered bool optionnel "searchFiltered" : true Cette variable permet de contextualiser la recherche avec les valeurs du paramètre filters. La valeur par défaut est true afin que le moteur de recherche renvoie uniquement des résultats dans le contexte choisi. La valeur false permet de rendre accessible tous les contenus de la base de connaissances dans le moteur de recherche.
customVariables obj optionnel "customVariables" : { "marque":"Smart Tribune"} Cette variable permet de remplacer la valeur d’un jeton de personnalisation créé dans le contenu d’une réponse via Smart Dashboard. Note : On attend ici une chaîne de caractères qui peut contenir des balises HTML (span, a, b, u, i, br, img) avec ses attributs (id, class, style, name, title, target, href, rel, src, alt).
filters obj optionnel "filters" : { "thematics":[], "tags":[] } Cette variable de configuration permet de spécifier la contextualisation de la PUSH à appliquer. Il est possible de définir le filtrage en utilisant l’identifiant système thematics ou tags. L’opérateur utilisé est AND dans le cas de multiples valeurs au sein du même filtre ou entre les filtres. Note : Ces objets contiennent un tableau (array) de chaîne de caractères (string).
entrypoint obj optionnel "entrypoint" : { "type":"", "value":"" } Cette variable de configuration permet d’afficher lors de l’ouverture de Smart Push, une question ou les questions d’une catégorie. Pour cela il faut choisir le type (‘question’ ou ‘thematic’) et insérer dans ‘value’ le slug* de la question ou de la catégorie. Note : L’objet contient un tableau (array) avec 2 chaînes de caractères (string). La valeur par défaut est homepage.

*Slug : C’est l’identifiant au format “chaîne de caractères” d’une question et d’une catégorie. Celui de la catégorie est trouvable dans Smart Dashboard (‘Menu’ > ‘Base de connaissances’ > ‘Catégories’ > ‘identifiant système’). Celui de la question est disponible directement depuis la FAQ dans l’url (example.com/faq?question=SLUG).

Etape 1.1.1: Les fonctions optionnelles

Smart PUSH fournit des fonctions supplémentaires pour contrôler le comportement de la box depuis votre page, selon les conditions qui vous conviennent le mieux.

Etape 1.1.1.1: Utiliser 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="detail.show()">Btn</button>
Depuis un… Description
timer Placez un setTimeout dans une balise <script> après l’initialisation de Smart PUSH.
<script type="text/javascript">
    window.addEventListener("STPUSHLoaded", function(e) {
        var stPush = e.detail;
        stPush.init({
            "analyticsUA": "UA-00000000-0",
            "searchFiltered": false,
            "kbId": 2,
            "locale": "fr",
            "cookieOptin": false,
            "filters": {
                "thematics": [],
                "tags": []
            },
        });
        setTimeout(() => {
            stPush.show();
        }, 3000);
    });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/PUSH/push.main.js"></script>
Depuis un… Description
scroll Placez un écouteur après l’initialisation de Smart PUSH.
<script type="text/javascript">
    window.addEventListener("STPUSHLoaded", function(e) {
        var stPush = e.detail;
        stPush.init({
            "analyticsUA": "UA-00000000-0",
            "searchFiltered": false,
            "kbId": 2,
            "locale": "fr",
            "cookieOptin": false,
            "filters": {
                "thematics": [],
                "tags": []
            },
        });
        window.addEventListener("scroll", function(e) {
            stPush.show();
        }, false);
    });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/PUSH/push.main.js"></script>

Si vous avez besoin d’utiliser ces fonctions à l’exterieur du script (sur un bouton par exemple), vous aurez besoin de stocker stPush à l’interieur de window qui est une variable globale :

<script type="text/javascript">
    window.addEventListener("STPUSHLoaded", function(e) {
        window.stPush = e.detail;
        window.stPush.init({
            "analyticsUA": "UA-00000000-0",
            "searchFiltered": false,
            "kbId": 2,
            "locale": "en",
            "cookieOptin": false,
            "filters": {
                "thematics": [],
                "tags": []
            },
        });
    });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/PUSH/push.main.js"></script>

Etape 1.1.1.2: Utiliser la fonction hide()
La fonction hide() va vous permettre de fermer la box.

Depuis un… Description
bouton Appelez simplement la fonction hide() sur votre bouton.
<button onclick="window.stPush.hide()">Btn</button>

Etape 1.1.1.3: Utiliser la fonction off()
La fonction off() va vous permettre de faire disparaitre la box de la page.

Depuis un… Description
bouton Appelez simplement la fonction off() sur votre bouton.
<button onclick="window.stPush.off()">Btn</button>

Etape 1.1.1.4: Utiliser 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.stPush.on()">Btn</button>

URL_SMART_TRIBUNE : https://components-library.app.smart-tribune.com/main/CLIENTNAME. Attention, 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.
CLIENTNAME : Cette information est communiquée par votre point de contact Smart Tribune en charge de votre dossier.

NOTE IMPORTANTE: Le chemin d’accès au fichier push.js évolue en fonction de l’environnement : public, 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.

ACTION REQUISE: 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.

Etape 2: Contextualisation de Smart Push

Cas de contextualisation #1: Filtrer en fonction de plusieurs tags.

Je souhaite seulement afficher des résultats contenant les tags suivants: “tag-1”, “tag-2”.

"filters":{
    "thematics":[],
    "tags":[
        "tag-1",
        "tag-2"
    ]
}
Cas de contextualisation #2: Filtrer en fonction de plusieurs catégories.

Je souhaite seulement afficher des résultats étant dans les catégories suivantes: “category-1”, “category-2”.

"filters":{
    "thematics":[
        "category-1",
        "category-2"
    ],
    "tags":[]
}
Cas de contextualisation #3: Filtrer en fonction d’un tag et d’une catégorie.

Je souhaite seulement afficher des résultats appartenant à la fois à la catégorie “category-1” ET au tag “tag-1”.

"filters":{
    "thematics":[
        "category-1"
    ],
    "tags":[
        "tag-1"
    ]
}
Cas de contextualisation #4: Customiser le contenu avec “customVariables” et du HTML.

Je souhaite que les “customVariables” se nommant “marque” et “persona” que j’ai paramétré depuis mon Back-Office V2 prennent pour valeur, les données suivantes:

"customVariables": {
   "marque": "<a href='https://smart-tribune.com' target='_blank'><span class='demo'>Smart Tribune</span></a>",
   "persona":"<b>Particuliers</b>",
},


Intégration du widget Stand Alone Search

Cette solution a pour but d’afficher un moteur de recherche permettant de rechercher dans la base de connaissance (KbId) spécifiée.

Lors d’une recherche, une autocomplétion s’affiche avec des suggestions. Si une recherche est validée via la touche “ENTREE” ou le clic sur le bouton de recherche, l’utilisateur sera dirigé vers la FAQ en question avec la recherche effectuée.

Etape 1: Intégration de la solution

L’installation de la solution se fait via l’intégration du snippet de code javascript avant la balise fermante </body> sur la ou les pages où celui ci doit être affiché.

Etape 1.1: Intégration du HTML sur la page qui va afficher le widget Stand Alone Search

Ajouter dans votre code HTML un conteneur avec un identifiant qui permettra d’afficher le widget à l’endroit de votre choix sur la page <div id="containerId_DE_VOTRE_CHOIX"></div>. Il faudra indiquer cet identifiant dans l’étape suivante (1.2) au niveau de containerId.

Etape 1.2: Intégration du JS à la page qui va contenir le widget Stand Alone Search

Intégrer le snippet Javascript juste avant la fermeture de la balise </body>. Le script Smart Tribune doit être chargé le plus en aval possible dans la chaîne de chargement des scripts afin d’éviter d’éventuels conflits avec les scripts présents sur la page client.

<script type="text/javascript">
        window.addEventListener('STSearchStandaloneLoaded', function(e){
            e.detail.init({
                "kbId": 2,
                "locale": "fr",
                "cookieOptin": true,
                "filters": {
                    "thematics": [
                        "category-1"
                    ],
                    "tags": [
                        "tag-1"
                    ]
                },
                "labels": {
                    "title": {
                        "fr": "Moteur de recherche",
                        "en": "Search bar" 
                    },
                    "emptyMessage": {
                        "fr": "Aucune question",
                        "en": "No question" 
                    },
                    "placeholder": {
                        "fr": "Saisir ta question",
                        "en": "Enter your question" 
                    },
                    "examplesTitle": {
                        "fr": "Exemples de recherche ?",
                        "en": "Examples" 
                    },
                    "submit": {
                        "fr": "Chercher",
                        "en": "Search" 
                    }
                },
                "limit": 50,
                "faqUrl": "https://example.com/faq",
                "openInNewTab": false,
                "searchExamples": {
                  "fr": [
                      "Lorem ipsum",
                      "Aenean",
                      "Consectetur adipiscing" 
                    ]
                },
                "containerId": "st-search-standalone" 
            });
        });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/SearchStandalone/searchstandalone.main.js"></script>

Lien vers la démonstration live : Cliquez ici

Variable Type Condition Exemple Description
kbId int requis "kbId" : 2 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. La base de connaissances intégrant déjà du contenu de test est identifié par la valeur : 2. 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.
cookieOptin bool required "cookieOptin" : false Elle permet d’empêcher ou non l’activation du cookie Google Analytics (valeur possible : true ou false). En désactivant cette fonctionnalité, il ne sera plus possible d’envoyer des informations dans Google Analytics pour votre widget. La valeur par défaut est false.
filters obj optionnel "filters" : { "thematics":[], "tags":[] } Cette variable de configuration permet de spécifier la contextualisation de la FAQ à appliquer. Il est possible de définir le filtrage en utilisant l’identifiant système thematics ou tags. L’opérateur utilisé est AND dans le cas de multiples valeurs au sein du même filtre ou entre les filtres. Note : Ces objets contiennent un tableau (array) de chaîne de caractères (string).
labels obj optionnel "labels" : { "title":{}, "emptyMessage":{}, "placeholder":{}, "examplesTitle":{}, "submit":{} } Cette variable permet de surcharger les chaines de caractères du widget par celles de votre choix. Nous vous conseillons de vous baser sur le snippet d’exemple ci-dessus pour ajouter vos propres textes.
limit int optionnel "limit": 5 Limite du nombre d’éléments à afficher (max: 50).
faqUrl string optionnel "faqUrl": "https://example.com/faq" Cela permet de rediriger les utilisateurs vers votre FAQ.
openInNewTab bool optionnel "openInNewTab": true Permet de charger la FAQ dans un nouvel onglet.
containerId string optionnel "containerId": "containerId_DE_VOTRE_CHOIX" Il s’agit de l’identifiant du container qui va recevoir le contenu de votre widget Stand Alone Search

ACTION REQUISE: 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.

Intégration du widget FAQ contextualisée

Etape 1: Intégration de la solution

La solution de widget FAQ contextualisée permet d’ajouter un bloc sur la page de votre choix, afin de récupérer dynamiquement les questions/réponses présentes dans votre base de connaissances, filtrées ou non en fonction d’un ou plusieurs critères.

Etape 1.1: Intégration du HTML sur la page qui va afficher le widget FAQ contextualisée

Ajouter dans votre code HTML un conteneur avec un identifiant qui permettra d’afficher le widget à l’endroit de votre choix sur la page <div id="containerId_DE_VOTRE_CHOIX"></div>. Il faudra indiquer cet identifiant dans l’étape suivante (1.2) au niveau de containerId.

Etape 1.2: Intégration du JS sur la page qui va afficher le widget FAQ contextualisée

Intégrer le snippet Javascript juste avant la fermeture de la balise </body>. Le script Smart Tribune doit être chargé le plus en aval possible dans la chaîne de chargement des scripts afin d’éviter d’éventuels conflits avec les scripts présents sur la page client.

<script type="text/javascript">
window.addEventListener('STFAQContextLoaded', function(e){
  e.detail.init({
    "kbId": 2,
    "locale": "fr",
    "cookieOptin": false,
    "filters":{
        "thematics":[
            "category-1"
        ],
        "tags":[
            "tag-1"
        ]
    },
    "labels": {
        "title": {
            "fr": "Questions pertinentes"
        },
        "emptyMessage": {
            "fr": "Aucune question"
        },
        "openOnFaq": {
            "fr": "Ouvrir sur la FAQ"
        },
        "goToFaqLink": {
            "fr": "Voir la FAQ"
        }
    },
    "limit": 5,
    "faqUrl": "https://example.com/faq",
    "openInNewTab": true,
    "containerId": "st-faq-context"
    });
  });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/FAQContext/faqcontext.main.js"></script>

Lien vers la démonstration live : Cliquez ici

Variable Type Condition Exemple Description
kbId int requis "kbId" : 2 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. La base de connaissances intégrant déjà du contenu de test est identifié par la valeur : 2. 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.
cookieOptin bool required "cookieOptin" : false Elle permet d’empêcher ou non l’activation du cookie Google Analytics (valeur possible : true ou false). En désactivant cette fonctionnalité, il ne sera plus possible d’envoyer des informations dans Google Analytics pour votre widget. La valeur par défaut est false.
customVariables obj optionnel "customVariables" : { "marque":"Smart Tribune"} Cette variable permet de remplacer la valeur d’un jeton de personnalisation créé dans le contenu d’une réponse via Smart Dashboard. Note : On attend ici une chaîne de caractères qui peut contenir des balises HTML (span, a, b, u, i, br, img) avec ses attributs (id, class, style, name, title, target, href, rel, src, alt).
filters obj optionnel "filters" : { "thematics":[], "tags":[] } Cette variable de configuration permet de spécifier la contextualisation de la FAQ à appliquer. Il est possible de définir le filtrage en utilisant l’identifiant système thematics ou tags. L’opérateur utilisé est AND dans le cas de multiples valeurs au sein du même filtre ou entre les filtres. Note : Ces objets contiennent un tableau (array) de chaîne de caractères (string).
labels obj optionnel "labels" : { "title":{}, "emptyMessage":{}, "openOnFaq":{}, "goToFaqLink":{} } Cette variable permet de surcharger les chaines de caractères du widget par celles de votre choix. Nous vous conseillons de vous baser sur le snippet d’exemple ci-dessus pour ajouter vos propres textes.
limit int optionnel "limit": 5 Limite du nombre d’éléments à afficher (max: 25).
faqUrl string optionnel "faqUrl": "https://example.com/faq" Cela permet de rediriger les utilisateurs vers votre FAQ.
openInNewTab bool optionnel "openInNewTab": true Permet de charger la FAQ dans un nouvel onglet.
containerId string optionnel "containerId": "st-faq-context" Il s’agit de l’identifiant du container qui va recevoir le contenu de votre widget FAQ contextualisée

ACTION REQUISE: 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.

Etape 2: Contextualisation du widget

Cas de contextualisation #1: Filtrer en fonction de plusieurs tags.

Je souhaite seulement afficher des résultats contenant les tags suivants: “tag-1”, “tag-2”.

"filters":{
    "thematics":[],
    "tags":[
        "tag-1",
        "tag-2"
    ]
}
Cas de contextualisation #2: Filtrer en fonction de plusieurs catégories.

Je souhaite seulement afficher des résultats étant dans les catégories suivantes: “category-1”, “category-2”.

"filters":{
    "thematics":[
        "category-1",
        "category-2"
    ],
    "tags":[]
}
Cas de contextualisation #3: Filtrer en fonction d’un tag et d’une catégorie.

Je souhaite seulement afficher des résultats appartenant à la fois à la catégorie “category-1” ET au tag “tag-1”.

"filters":{
    "thematics":[
        "category-1"
    ],
    "tags":[
        "tag-1"
    ]
}
Cas de contextualisation #4: Customiser le contenu avec “customVariables” et du HTML.

Je souhaite que les “customVariables” se nommant “marque” et “persona” que j’ai paramétré depuis mon Back-Office V2 prennent pour valeur, les données suivantes:

"customVariables": {
   "marque": "<a href='https://smart-tribune.com' target='_blank'><span class='demo'>Smart Tribune</span></a>",
   "persona":"<b>Particuliers</b>",
},


Intégration du widget formulaire de contact

Etape 1: Choix du mode de fonctionnement

Le widget formulaire de contact permet d’afficher un bloc sur un formulaire de contact, afin de récupérer dynamiquement les questions/réponses présentes dans votre base de connaissances, filtrées par plusieurs critères en fonction de votre besoin.

Pour proposer des questions/réponses adaptées, le widget peut analyser deux types de champs sur un formulaire de contact :

Deux snippets différents sont disponibles en fonction du type de champ que le widget va analyser.

Etape 2: Intégration de la solution

Etape 2.1: Intégration de la solution sur un champ de saisie
Etape 2.1.1: Intégration du HTML

Ajouter dans votre code HTML un conteneur avec un identifiant qui permettra d’afficher le widget à l’endroit de votre choix sur la page <div id="containerId_DE_VOTRE_CHOIX"></div>.
Sur votre champ de saisie, pensez à spécifier un identifiant afin de pouvoir le préciser dans le code JS <input id="inputId_DE_VOTRE_CHOIX"/>.

Etape 2.1.2: Intégration du JS

Intégrer le snippet Javascript juste avant la fermeture de la balise </body>. Le script Smart Tribune doit être chargé le plus en aval possible dans la chaîne de chargement des scripts afin d’éviter d’éventuels conflits avec les scripts présents sur la page client.

<script type="text/javascript">
window.addEventListener('STContactFormInputLoaded', function(e){
  e.detail.init({
    "kbId": 2,
    "locale": "fr",
    "cookieOptin": false,
    "filters": {
        "thematics": [],
        "tags": []
    },
    "labels": {
        "title": {
            "fr": "Suggestions"
        },
        "openOnFaq": {
            "fr": "Ouvrir sur la FAQ"
        },
        "goToFaqLink": {
            "fr": "Voir la FAQ"
        }
    },
    "limit": 5,
    "faqUrl": "https://example.com/faq",
    "openInNewTab": true,
    "inputId": "my-input",
    "containerId": "st-contact-form-input-container"
    });
  });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/ContactFormInput/contactforminput.main.js"></script>

Lien vers la démonstration live : Cliquez ici

Variable Type Condition Exemple Description
kbId int requis "kbId" : 2 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. La base de connaissances intégrant déjà du contenu de test est identifié par la valeur : 2. 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.
cookieOptin bool required "cookieOptin" : false Elle permet d’empêcher ou non l’activation du cookie Google Analytics (valeur possible : true ou false). En désactivant cette fonctionnalité, il ne sera plus possible d’envoyer des informations dans Google Analytics pour votre widget formulaire de contact. La valeur par défaut est false.
customVariables obj optionnel "customVariables" : { "marque":"Smart Tribune"} Cette variable permet de remplacer la valeur d’un jeton de personnalisation créé dans le contenu d’une réponse via Smart Dashboard. Note : On attend ici une chaîne de caractères qui peut contenir des balises HTML (span, a, b, u, i, br, img) avec ses attributs (id, class, style, name, title, target, href, rel, src, alt).
filters obj optionnel "filters" : { "thematics":[], "tags":[] } Cette variable de configuration permet de spécifier la contextualisation du widget formulaire de contact à appliquer. Il est possible de définir le filtrage en utilisant l’identifiant système thematics ou tags. L’opérateur utilisé est AND dans le cas de multiples valeurs au sein du même filtre ou entre les filtres. Note : Ces objets contiennent un tableau (array) de chaîne de caractères (string).
labels obj optionnel "labels" : { "title":{}, "emptyMessage":{}, "openOnFaq":{}, "goToFaqLink":{} } Cette variable permet de surcharger les chaines de caractères du widget par celles de votre choix. Nous vous conseillons de vous baser sur le snippet d’exemple ci-dessus pour ajouter vos propres textes.
limit int optionnel "limit": 5 Limite du nombre d’éléments à afficher (max: 25).
faqUrl string optionnel "faqUrl": "https://example.com/faq" Cela permet de rediriger les utilisateurs vers la FAQ.
openInNewTab bool optionnel "openInNewTab": true Permet d’ouvrir les liens des suggestions dans un nouvel onglet.
inputId string optionnel "inputId": "my-input" Il s’agit de l’identifiant du champ du formulaire sur lequel il faut appliquer la recherche.
containerId string optionnel "containerId": "st-contact-form-input-container" Il s’agit de l’identifiant du container qui va afficher le widget.

ACTION REQUISE: 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.

Etape 2.2: Intégration de la solution sur une liste déroulante
Etape 2.2.1: Intégration du HTML

Ajouter dans votre code HTML un conteneur avec un identifiant qui permettra d’afficher le widget à l’endroit de votre choix sur la page <div id="containerId_DE_VOTRE_CHOIX"></div>.
Sur votre liste déroulante, pensez à spécifier un identifiant afin de pouvoir le préciser dans le code JS <select id="selectId_DE_VOTRE_CHOIX"></select>.

Etape 2.2.2: Intégration du JS

Intégrer le snippet Javascript juste avant la fermeture de la balise </body>. Le script Smart Tribune doit être chargé le plus en aval possible dans la chaîne de chargement des scripts afin d’éviter d’éventuels conflits avec les scripts présents sur la page client.

<script type="text/javascript">
    window.addEventListener('STContactFormSelectLoaded', function(e){
        e.detail.init({
            "kbId": 2,
            "locale": "fr",
            "cookieOptin": false,
            "filters": {
                "thematics": [],
                "tags": []
            },
            "labels": {
                "title": {
                    "fr": "Suggestions"
                },
                "openOnFaq": {
                    "fr": "Ouvrir sur la FAQ"
                },
                "goToFaqLink": {
                    "fr": "Voir la FAQ"
                }
            },

            "limit": 5,
            "faqUrl": "https://example.com/faq",
            "openInNewTab": true,
            "selectId": "my-select",
            "containerId": "st-contact-form-select-container",
            "mapping": {
                "option-1": {
                    "thematics": ["category-1"],
                    "tags": []
                },
                "option-2": {
                    "thematics": ["category-2"],
                    "tags": ["tag-1"]
                }
            }
        });
    });
</script>
<script type="text/javascript" async src="https://assets.app.smart-tribune.com/smart-tribune/ContactFormSelect/contactformselect.main.js"></script>

Lien vers la démonstration live : Cliquez ici

Variable Type Condition Exemple Description
kbId int requis "kbId" : 2 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. La base de connaissances intégrant déjà du contenu de test est identifié par la valeur : 2. 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.
cookieOptin bool required "cookieOptin" : false Elle permet d’empêcher ou non l’activation du cookie Google Analytics (valeur possible : true ou false). En désactivant cette fonctionnalité, il ne sera plus possible d’envoyer des informations dans Google Analytics pour le widget. La valeur par défaut est false.
customVariables obj optionnel "customVariables" : { "marque":"Smart Tribune"} Cette variable permet de remplacer la valeur d’un jeton de personnalisation créé dans le contenu d’une réponse via Smart Dashboard. Note : On attend ici une chaîne de caractères qui peut contenir des balises HTML (span, a, b, u, i, br, img) avec ses attributs (id, class, style, name, title, target, href, rel, src, alt).
filters obj optionnel "filters" : { "thematics":[], "tags":[] } Cette variable de configuration permet de spécifier la contextualisation du widget à appliquer. Il est possible de définir le filtrage en utilisant l’identifiant système thematics ou tags. L’opérateur utilisé est AND dans le cas de multiples valeurs au sein du même filtre ou entre les filtres. Note : Ces objets contiennent un tableau (array) de chaîne de caractères (string).
labels obj optionnel "labels" : { "title":{}, "emptyMessage":{}, "openOnFaq":{}, "goToFaqLink":{} } Cette variable permet de surcharger les chaines de caractères du widget par celles de votre choix. Nous vous conseillons de vous baser sur le snippet d’exemple ci-dessus pour ajouter vos propres textes.
limit int optionnel "limit": 5 Limite du nombre d’éléments à afficher (max: 25).
faqUrl string optionnel "faqUrl": "https://example.com/faq" Cela permet de rediriger les utilisateurs vers la FAQ.
openInNewTab bool optionnel "openInNewTab": true Permet d’ouvrir les liens des suggestions dans un nouvel onglet.
selectId string optionnel "selectId": "my-select" Il s’agit de l’identifiant du champ du formulaire sur lequel il faut appliquer la recherche.
containerId string optionnel "containerId": "st-contact-form-select-container" Il s’agit de l’identifiant du container qui va afficher le widget.
mapping obj optionnel "mapping" : { "option-1":[], "option-2":[]} Cette variable permet de spécifier les catégories et les tags qui doivent être associés au motif sélectionné dans la liste déroulante (option value). Nous vous conseillons de vous baser sur le snippet d’exemple ci-dessus.

ACTION REQUISE: 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.

Etape 3: Contextualisation du widget

Cas de contextualisation #1: Filtrer en fonction de plusieurs tags.

Je souhaite seulement afficher des résultats contenant les tags suivants: “tag-1”, “tag-2”.

"filters":{
    "thematics":[],
    "tags":[
        "tag-1",
        "tag-2"
    ]
}
Cas de contextualisation #2: Filtrer en fonction de plusieurs catégories.

Je souhaite seulement afficher des résultats étant dans les catégories suivantes: “category-1”, “category-2”.

"filters":{
    "thematics":[
        "category-1",
        "category-2"
    ],
    "tags":[]
}
Cas de contextualisation #3: Filtrer en fonction d’un tag et d’une catégorie.

Je souhaite seulement afficher des résultats appartenant à la fois à la catégorie “category-1” ET au tag “tag-1”.

"filters":{
    "thematics":[
        "category-1"
    ],
    "tags":[
        "tag-1"
    ]
}
Cas de contextualisation #4: Customiser le contenu avec “customVariables” et du HTML.

Je souhaite que les “customVariables” se nommant “marque” et “persona” que j’ai paramétré depuis mon Back-Office V2 prennent pour valeur, les données suivantes:

"customVariables": {
   "marque": "<a href='https://smart-tribune.com' target='_blank'><span class='demo'>Smart Tribune</span></a>",
   "persona":"<b>Particuliers</b>",
},


Optimisation du référencement naturel de Smart FAQ (SEO)

Smart FAQ étant entièrement générée via de l’AJAX, celle-ci ne sera pas référencée de façon optimale par les moteurs de recherche, comme notamment Google. Pour cette raison, nous utilisons la méthode la plus performante à ce jour, à savoir celle du Dynamic Rendering qui consiste à « servir » des templates HTML statiques équivalents à l’affichage effectué pour l’internaute, que l’on aura au préalable générés, et qui seront délivrés exclusivement aux moteurs de recherche pour un référencement optimal.

Solution Seo4Ajax

Implémentation sur APACHE Server

Action 1:

Vérifier que le module “proxy_http” soit bien activé sur le serveur.

Action 2:

Intégrer sous APACHE les règles suivantes :

### Activate the rewrite rule engine
RewriteEngine On

### If the request comes from a bot, set a flag to proxy the request to SEO4Ajax
RewriteCond %{ENV:PROXY} !true
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} ^/URI-A-DEFINIR
RewriteCond %{HTTP_USER_AGENT} (google|bot|spider|pinterest|crawler|archiver|flipboardproxy|mediapartners|facebookexternalhit|insights|quora|whatsapp|slurp) [NC,OR]
RewriteCond %{HTTP:from} .+
RewriteRule .* - [E=PROXY:true,E=REQUEST_PATH:%{REQUEST_URI}]

### Proxify the request to SEO4Ajax
RewriteCond %{ENV:PROXY} true
RewriteRule ^(.*)$ http://api.seo4ajax.com/CLE-A-DEFINIR%{ENV:REQUEST_PATH} [P,QSA,L]

### If request sitemap file, set a flag to proxy the request to SEO4Ajax
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_URI} ^/sitemap_seo4ajax.xml
RewriteRule .* - [E=PROXY_SITEMAP:true]

### Proxify the request to SEO4Ajax
RewriteCond %{ENV:PROXY_SITEMAP} true
RewriteRule ^(.*)$ http://api.seo4ajax.com/CLE-A-DEFINIR/sitemap.xml [P,QSA,L]
Action 3:

Remplacer les termes “CLE-A-DEFINIR” et “URI-A-DEFINIR” par les éléments ci-dessous.

Paramètres Description
CLE-A-DEFINIR C’est une donnée que Smart Tribune vous fournit. C’est le token permettant d’autoriser les appels à SEO4AJAX.
URI-A-DEFINIR URI de la page de FAQ sur le site client.

Exemple pour URI-A-DEFINIR:
Pour l’url de FAQ http://example.com/fr/faq, je dois remplacer dans le snippet ci-dessus ^/URI-A-DEFINIR par ^/fr/faq
Conclusion:

RewriteCond %{REQUEST_URI} ^/URI-A-DEFINIR    >    RewriteCond %{REQUEST_URI} ^/fr/faq
NGINX Server

Action 1:

Intégrer sous NGINX les règles suivantes :

location /URI-A-DEFINIR {
    ### If the files exists on the server, serve it, otherwise execute the @s4a_analyse location
    try_files $uri @s4a_analyse;
}

### This location determines if a request comes from bots
location @s4a_analyse {

    ### If the request comes from a bot, proxy the request through /s4a_proxy location
    if ($http_user_agent ~* (google|bot|spider|pinterest|crawler|archiver|flipboardproxy|mediapartners|facebookexternalhit|insights|quora|whatsapp|slurp)) {
        rewrite ^(.*)$ /s4a_proxy last;
    }

    if ($http_from ~* .+) {
        rewrite ^(.*)$ /s4a_proxy last;
    }
}

### This location proxy requests coming from bots to SEO4Ajax
### You can update the resolver directive with your own DNS provider if needed
location /s4a_proxy {
    set $s4a_domain 'https://api.seo4ajax.com/CLE-A-DEFINIR';
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    resolver 8.8.8.8 8.8.4.4;
    proxy_pass $s4a_domain$request_uri;
}

### Following rules are used to provide FAQ dedicated sitemap
location /sitemap_seo4ajax.xml {
    rewrite ^(.*)$ /s4a_proxy_sitemap last;
}

location /s4a_proxy_sitemap {
    set $s4a_domain 'https://api.seo4ajax.com/CLE-A-DEFINIR';
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    resolver 8.8.8.8 8.8.4.4;
    proxy_pass $s4a_domain/sitemap.xml;
}
ACTION 2:
Paramètres Description
CLE-A-DEFINIR C’est une donnée que Smart Tribune vous fournit. C’est le token permettant d’autoriser les appels à SEO4AJAX.
URI-A-DEFINIR URI de la page de FAQ sur le site client.

Exemple pour URI-A-DEFINIR:
Pour l’url de FAQ http://example.com/fr/faq, je dois remplacer dans le snippet ci-dessus /URI-A-DEFINIR par /fr/faq
Conclusion:

location /URI-A-DEFINIR     >    location /fr/faq

NOTE:
IIS server : règles disponibles pour IIS Server sur demande

Vérification / Validation :

Méthode de vérification 1:
Afin de vérifier l’implémentation des règles et par la même occasion accélérer le référencement de votre nouvelle FAQ, vous pouvez utiliser l’outil Google Search Console (GSC) afin de vérifier que le contenu des templates HTML statiques sont correctement délivrés aux moteurs de recherche et si besoin, de forcer la première indexation manuellement.

Méthode de vérification 2:
Pour vérifier la bonne implémentation, il vous faut vérifier le comportement de la page en tant que Bot de moteur de recherche et donc pour résumer simplement en tant que GoogleBot.

Procédure A:

  1. Installer une extension de Chrome prévue à cet effet (https://bit.ly/3gshRLL).
  2. Cliquer sur "Googlebot (Google’s spider)".
  3. Se rendre sur la page d’accueil de la FAQ (ou la rafraichir si vous êtes déjà dessus).
  4. Cliquer droit > "Afficher le code source de la page".
  5. Rechercher la balise <div id=“st-faq”></div>.
    a. Si vous n’avez pas de contenu, alors il est fortement possible que l’implémentation des règles ne soit pas bonne, il faut vérifier votre configuration serveur (proxy_http pour APACHE, blocage au niveau de votre CDN, robots.txt, firewall…) et recommencer la procédure.
    b. Si vous avez du contenu à l’intérieur de la balise, alors les snapshots sont bien présents et les bots sont bien redirigés vers la page en HTML statique. La procédure se termine ici mais nous vous conseillons d’utiliser la procédure B (ci-dessous) pour avoir une analyse plus poussée.

Procédure B:

  1. Installer CURL sur votre ordinateur si ça n’est pas le cas (Comment installer CURL).
  2. Lancer la commande suivante depuis votre CMD/Terminal:
$ curl -L -A "Googlebot/2.1 (+http://www.google.com/bot.html)" https://example.com/fr/faq
  1. Rechercher la balise <div id=“st-faq”></div>.
    a. Si vous n’avez pas de contenu, alors il est fortement possible que l’implémentation des règles ne soit pas bonne, il faut vérifier votre configuration serveur (proxy_http pour APACHE, blocage au niveau de votre CDN, robots.txt, firewall…) et recommencer la procédure.
    b. Si vous avez du contenu à l’intérieur de la balise, alors les snapshots sont bien présents et les bots sont bien redirigés vers la page en HTML statique.
  2. Pour confirmer que vous avez bien un snapshot de SEO4AJAX il faut lancer la ligne de commande suivante:
$ curl -I -A "Googlebot" https://example.com/fr/faq"
  1. Le résultat devrait vous retourner le header de la page et une ligne se nommant “Vary” et contenant X-S4a-Debug.
    a. C’est le cas, et donc la procédure se termine ici, tout est OK.
    b. Ça n’est pas le cas et il faut vérifier votre configuration car il est possible que vous ayez un CDN qui s’occupe de cela ou un outil de Server Side Rendering qui est priorisé par rapport à SEO4AJAX. Il faut donc investiguer et recommencer la procédure.

Pour forcer manuellement l’indexation du contenu :

  1. Rendez-vous sur Google Search Console (GSC) puis sélectionnez votre site (si celui-ci n’existe pas, veuillez l’ajouter en suivant la procédure décrite).
  2. Dirigez-vous dans la section Exploration puis « Explorer comme google » (Fetch as Google) et renseignez l’url de votre FAQ puis lancez l’exploration.
    Si vous observez le contenu HTML de la FAQ (catégories, questions entre la balise div ayant pour identifiant (id) ‘st-faq’, vous pouvez « Envoyer pour indexation » en cliquant sur le bouton prévu à cet effet.

Il est parfois nécessaire de spécifier à Google comment se comporter avec les paramètres (query string) utilisés par la FAQ, pour cela il vous suffit d’éditer les réglages dans la section “Ancien outils et Rapports” puis “Paramètres d’URL” puis pour les paramètres suivants :

Configurer de la façon suivante :