DocsAPI JavaScript

API JavaScript : ouvrir l’agent Nodale depuis votre code

Les commandes nodale() qu’une page peut appeler : ouvrir l’agent depuis votre bouton ou formulaire, passer un e-mail et du contexte, signaler le consentement.

Une fois le tag installé, votre page peut lui envoyer des commandes par une seule fonction, nodale(). Il y a deux commandes : open et consent. Le tag n’expose aucune autre méthode et n’envoie aucun événement à votre page.

La file de commandes

Le tag définit window.nodale quand il s’exécute. Pour appeler une commande avant que le tag soit chargé, collez ce stub au-dessus de lui. Les commandes attendent dans une file jusqu’à ce que le tag soit prêt :

<script>
  window.nodale = window.nodale || function(){(window.nodale.q = window.nodale.q || []).push(arguments)}
</script>
<script src="https://tag.nodale.app/v1/tag.js" data-workspace="YOUR_WORKSPACE_ID" async></script>

Gardez le ||. Un script qui affecte plus tard window.nodale sans lui supprime la commande du tag, et les appels suivants ne vont nulle part.

nodale('open')

Ouvre l’agent depuis votre propre code, par exemple depuis votre propre bouton ou une fois votre propre formulaire envoyé.

nodale('open')

nodale('open', {
  email: 'sam@acme.io',
  context: { 'Contacts par mois': '1500' }
})

L’appel démarre une conversation écrite dans la boîte de dialogue de l’agent. Le microphone n’est pas demandé : il attend le visiteur.

Options

Option Type Ce qu’elle fait
email string L’e-mail du visiteur, quand votre page le connaît déjà. Il est identifié avant le message d’accueil de l’agent.
context object Ce que le visiteur vous a déjà dit, sous forme de paires libellé et réponse. L’agent le reçoit au démarrage de la conversation. Il est enregistré sur la conversation et jamais montré au visiteur.

Les deux sont facultatives. Le tag vérifie l’argument avant que quoi que ce soit ne quitte la page :

  • L’argument est absent, ou un objet simple sans autre clé que email et context. Dans tout autre cas, rien ne s’ouvre.
  • email est une chaîne de 1 à 254 caractères une fois les espaces de début et de fin retirés. Sinon il est écarté, et l’agent s’ouvre quand même. Le tag ne juge pas l’adresse : le serveur décide de l’accepter ou non.
  • context contient 20 réponses au maximum. Un libellé fait 1 à 60 caractères, une réponse est une chaîne de 300 caractères au maximum, et un libellé sert une seule fois. Les espaces de début et de fin des libellés et des réponses sont retirés, et une réponse vide est ignorée. Si une règle est enfreinte, tout le contexte est écarté, jamais tronqué, et l’agent s’ouvre quand même sans lui.

nodale('open') ne lève jamais d’exception et renvoie undefined.

Où ça fonctionne

  • Sur la barre et sur l’affichage hidden uniquement. Avec l’affichage en bouton, avec un <div data-nodale-agent> intégré à la page, et sur une page où l’agent n’est pas affiché (une règle de page, ou une part des visiteurs), l’appel ne fait rien. Si vous utilisez open, laissez la part des visiteurs désactivée, sinon l’appel ne fait rien pour certains visiteurs.
  • Avant que le tag soit chargé, grâce au stub ci-dessus. Seul le dernier open mis en file est rejoué, une fois.
  • Une seule conversation. Le widget démarre une conversation au plus et garde le premier e-mail et le premier contexte qu’il a reçus. Un open pendant une conversation, ou après la fin de l’une d’elles, affiche seulement la boîte de dialogue.
  • Quand l’agent demande d’abord l’e-mail, l’appel affiche cette étape, et votre e-mail et votre contexte sont envoyés quand le visiteur la valide.

Depuis un bouton

<button type="button" onclick="nodale('open')">Poser une question</button>

Après votre propre formulaire

form.addEventListener('submit', function () {
  nodale('open', {
    email: form.elements.email.value,
    context: {
      'Taille de la société': form.elements.size.value,
      'Ce que la personne veut faire': form.elements.message.value
    }
  })
})

Affichage hidden

hidden est un affichage de l’espace de travail, à côté de la barre et du bouton. Avec lui, rien ne s’affiche tant que votre page n’appelle pas nodale('open').

  • La page reste entièrement utilisable. Le cadre de l’agent est monté mais invisible, et il ne capte aucun clic.
  • Une fois ouvert, c’est la barre. Fermer la boîte de dialogue ramène à la barre et conserve la conversation. La barre reste ensuite jusqu’à la fin de l’onglet.
  • L’onglet s’en souvient. Une page suivante de votre site dans le même onglet affiche la barre aussitôt, pour que le visiteur retrouve la conversation. Le tag conserve cela dans sessionStorage, dans une clé qui ne contient aucun identifiant. Un nouvel onglet démarre masqué.
  • Testé dans les navigateurs Chromium uniquement. Safari et Firefox ne sont pas encore couverts par nos tests navigateur : un navigateur qui ralentit les cadres invisibles peut répondre à open plus tard.

nodale('consent')

Indique au tag si le visiteur a accepté la mesure des visites. Utilisez-la quand votre site n’a pas de bandeau cookies que le tag sait lire, ou quand vous gérez le consentement vous-même.

nodale('consent', 'granted')
nodale('consent', 'revoked')
  • Elle ne compte que si la mesure des visites est activée dans votre espace de travail. La mesure est désactivée par défaut, et l’agent est monté dans les deux cas.
  • La mesure démarre refusée. Rien n’est demandé et aucun cookie n’est écrit avant un accord. Sur revoked, le tag s’arrête et supprime son cookie.
  • Elle passe avant tout bandeau. Une fois que votre page l’a appelée, le tag suit votre appel et ignore ce que dit un bandeau.
  • Global Privacy Control l’emporte sur tout. Un navigateur qui l’envoie reste refusé pendant toute la visite, quoi que votre page appelle.

Sans cet appel, le tag lit la réponse dans l’outil de consentement de la page : Axeptio, Didomi, Cookiebot, OneTrust, Usercentrics, CookieYes, tarteaucitron.js, WP Consent API, Complianz, le bandeau HubSpot, iubenda, Osano, Cookie-Script, CookieFirst, Klaro, Shopify, Wix, IAB TCF v2.2, IAB GPP et Google Consent Mode v2. Certains demandent que Nodale soit déclaré comme fournisseur ou comme service : le guide de la mesure des visites, dans l’application, donne la configuration pour chacun.

Débogage

Le tag ne lève jamais d’exception dans votre page. Il s’explique sur console.debug, par des lignes commençant par nodale tag:. Activez le niveau verbeux de la console de votre navigateur pour les voir.

Ligne Ce qui s’est passé
open refused L’argument n’est pas un objet simple, ou il contient une autre clé que email et context.
open email dropped email n’est pas une chaîne de 1 à 254 caractères.
open context dropped context enfreint l’une de ses règles.
open needs the floating or hidden display L’espace de travail utilise l’affichage en bouton, ou la page monte l’agent dans son propre contenu.
open: agent not on this page Une règle de page ou la part des visiteurs écarte l’agent de cette page.
open not acknowledged Le widget n’a pas répondu dans les 30 secondes.

Pour les agents IA : cette page en Markdown

Faites de chaque visite une opportunité.