Installer le chat
Deux lignes de code sur chaque page où le chat doit être disponible.
Vous êtes sur Shopify ?
Pas besoin de cette page. Installez l'app Humind depuis le Shopify App Store : le widget est injecté automatiquement sur toutes les pages de votre boutique, déjà câblé avec votre domaine.
1. Autoriser votre domaine
Requis avant que le chat se charge
Humind ne s'affiche que sur les domaines que vous avez explicitement autorisés. Ouvrez la page URL whitelist dans votre dashboard et ajoutez chaque domaine où vous embarquerez le widget : production, staging, branches de preview, environnements de dev custom. Un domaine qui n'est pas dans la liste ne chargera pas le chat.
2. Coller le snippet
Sur chaque page où vous voulez le chat :
<script src="https://embed.thehumind.com/loader.js" defer></script>
<humind-widget
shop-domain="votre-shop.com"
template-name="index"
></humind-widget>Le <script> va à la fin du <body>. L'élément se positionne en overlay fixe, placez-le n'importe où dans le DOM.
shop-domain: remplacez par le domaine canonique de cet environnement (sans protocole, sans slash final). Doit être dans votre whitelist.template-name: le type de page. Choisissez la valeur qui correspond (étape suivante).
3. Choisir le bon template-name par page
template-name indique à l'IA ce que le visiteur regarde. C'est ce qui permet à l'assistant de remonter les bons sujets, points d'entrée et messages proactifs.
La plupart des sites n'ont besoin que de quatre valeurs :
| Valeur | Quand |
|---|---|
index | Page d'accueil |
product | Page produit |
collection | Listing collection / catégorie |
cart | Panier |
Si la page ne rentre dans aucune, consultez la liste complète en référence.
WARNING
Passer une valeur qui n'est pas dans la liste fait que le widget refuse de charger. Choisissez toujours depuis la liste, jamais une chaîne libre.
template-name="product" cache le bouton flottant
Sur les pages produit, le bouton de chat flottant est intentionnellement supprimé. Le CTA « Add to cart » est généralement pinné en bas de l'écran sur mobile et le bouton flottant venait se poser dessus. On attend des visiteurs qu'ils entrent dans la conversation via le widget inline <humind-product-questions> sur la page produit elle-même. Gardez template-name="product" sur ces pages, car le contexte continue de remonter à l'assistant, et associez-le au bloc product questions.
Sur les pages produit, passez aussi product-id
template-name="product" indique à l'assistant que le visiteur est sur une page produit, mais pas lequel. Ajoutez product-id pour que le chat sache exactement ce que le visiteur regarde :
<humind-widget
shop-domain="votre-shop.com"
template-name="product"
product-id="gid://shopify/Product/12345"
></humind-widget>Avec cet attribut, le chat affiche une barre de contexte produit en haut de la conversation et l'IA ancre ses réponses sur ce produit précis. Chaque message envoyé par le visiteur porte le contexte produit. Valeurs acceptées : un GID Shopify (gid://shopify/Product/12345) ou votre ID produit interne, résolu côté serveur. Sur les pages non produit, omettez l'attribut.
4. Vérifier
Ouvrez DevTools → onglet Network. Vous devriez voir :
GET https://embed.thehumind.com/loader.js→ 200- Quelques chunks JS supplémentaires
- Aucune erreur console
document.querySelector('humind-widget') doit renvoyer l'élément, et un bouton flottant de chat doit apparaître en bas à droite de la page.
Référence
Tous les attributs
| Attribut | Obligatoire | Défaut | Rôle |
|---|---|---|---|
shop-domain | ✅ | - | Votre domaine canonique pour cet environnement (sans protocole). Doit être whitelisté. Omettez uniquement si vous passez company-id à la place. |
template-name | ✅ | - | Template de la page courante. Voir valeurs. |
language | Langue navigateur | Tag BCP-47 (en, fr, de, es, it, nl, pt, ru, ar, he, zh). Forcez une locale uniquement si vous voulez ignorer la langue du navigateur du visiteur. | |
country-code | - | ISO 3166-1 alpha-2, ex. FR. Utilisé pour le contexte régional (prix, livraison). | |
cookie-consent | - | Statut de consentement du visiteur. Voir valeurs. | |
company-id | - | Alternative à shop-domain pour les setups sans domaine public. Voir ci-dessous. | |
product-id | - | Pages produit uniquement : le produit consulté. GID Shopify (gid://shopify/Product/12345) ou votre ID produit interne. Affiche une barre de contexte produit dans le chat et ancre les réponses de l'IA sur ce produit. Voir plus haut. | |
market-key | - | Setups multimarché uniquement : nomme le marché quand plusieurs marchés partagent le même domaine (obligatoire dans ce cas, ignoré sur un domaine mono-marché). Posé automatiquement sur Shopify. Voir ci-dessous. |
Valeurs de template-name
Utilisez la chaîne exactement telle qu'écrite (sensible à la casse, tirets / underscores / slashes préservés).
| Valeur | Page |
|---|---|
index | Page d'accueil |
product | Page produit (PDP) |
collection | Listing collection / catégorie |
list-collections | Index de toutes les collections |
search | Résultats de recherche |
cart | Panier |
page | Page CMS / statique |
blog | Index blog |
article | Article de blog |
gift_card | Page d'achat carte cadeau |
password | Splash de boutique password-protected |
404 | Page not-found |
metaobject | Page metaobject Shopify |
robots.txt | Route robots.txt (edge case) |
customers/account | Dashboard compte client |
customers/login | Login client |
customers/register | Signup client |
customers/order | Détail d'une commande |
customers/addresses | Carnet d'adresses |
customers/reset_password | Reset mot de passe |
customers/activate_account | Activation de compte |
Si aucune ne correspond (flow checkout, page contact, route bespoke), parlez-en à votre lead d'intégration avant de choisir une valeur.
Valeurs de cookie-consent
Par défaut, Humind n'affiche aucune UI de consentement et les analytics PostHog sont actifs. Le marchand peut exiger un consentement depuis le dashboard ou transmettre le choix de sa propre CMP. Les stockages strictement fonctionnels du widget restent utilisés indépendamment des analytics. Consultez l'inventaire des traceurs et du stockage navigateur pour le détail des clés, finalités et durées.
Pour proposer les analytics facultatifs, activez Require cookie consent dans le dashboard sur Paramètres du chat survey. Le widget présente alors le choix au premier message. L'acceptation active PostHog. Le refus maintient PostHog désactivé et ferme le widget.
L'attribut cookie-consent est optionnel. Utilisez-le pour transmettre au widget le statut de votre propre CMP, par exemple OneTrust, Didomi, Cookiebot ou Axeptio. Les valeurs explicites envoyées par la CMP sont prioritaires sur une ancienne décision locale.
| Valeur | Comportement |
|---|---|
accepted | Le visiteur a accepté. Le widget saute le choix inline, mémorise l'acceptation sans expiration automatique et active PostHog. |
rejected | Le visiteur a refusé. Le widget supprime une éventuelle acceptation précédente, ne mémorise pas le refus, garde PostHog désactivé et ferme le chat. |
pending | La CMP n'a pas encore reçu de réponse. En l'absence d'une acceptation Humind enregistrée, le widget présente son choix inline au premier message. |
Mettez l'attribut à jour dynamiquement quand le visiteur change d'avis. Une valeur rejected supprime l'acceptation enregistrée et bloque les nouveaux événements. PostHog n'utilise aucun stockage navigateur.
Omettez l'attribut pour utiliser le réglage du dashboard. Si Require cookie consent n'est pas activé, aucun choix n'apparaît et les analytics restent actifs.
Pas de domaine public ? Utilisez company-id
Pour les sessions playground du dashboard, les backends headless ou les environnements de staging sans domaine enregistré, passez company-id à la place de shop-domain :
<humind-widget
company-id="YOUR_COMPANY_ID"
template-name="index"
integration="playground"
></humind-widget>Récupérez YOUR_COMPANY_ID depuis la page Credentials développeur dans le dashboard. Le texte YOUR_COMPANY_ID est cliquable dans le snippet ci-dessus.
Plusieurs marchés sur un même domaine
Si vous vendez sur plusieurs marchés depuis le même domaine (par exemple votre-shop.com qui sert à la fois la France et la Belgique), chaque marché est un espace Humind distinct avec son propre catalogue, ses prix et sa configuration. Les marchés se gèrent dans votre dashboard sur la page Markets.
Sur un domaine partagé par plusieurs marchés, le snippet doit nommer son marché avec l'attribut market-key. Humind ne devine jamais : sans lui, le widget ne charge pas et écrit une erreur explicite dans la console du navigateur, avec la liste des clés acceptées.
<humind-widget
shop-domain="votre-shop.com"
template-name="index"
market-key="be"
></humind-widget>La valeur est la clé de marché affichée sur la page Markets (lettres minuscules, chiffres, tirets, underscores). Sur un domaine partagé, un market-key qui n'existe pas fait que le widget refuse de charger, copiez-le donc toujours depuis le dashboard. Un domaine qui ne sert qu'un seul marché ignore l'attribut : vous pouvez garder le même snippet partout.
Vous êtes sur Shopify ?
Rien à faire. L'app embed Shopify envoie automatiquement le marché Shopify du visiteur (localization.market.handle), et Humind le fait correspondre à l'espace concerné : les marchés activés depuis la page Markets ont chacun leur catalogue et leurs prix, et les marchés Shopify que vous n'avez pas activés dans Humind sont servis par votre boutique principale. Renommer un marché sur Shopify est pris en compte à la prochaine ouverture de la page Markets.
Thème
Les couleurs, le style du bouton add-to-cart et l'identité visuelle de l'assistant se configurent par company dans le dashboard, sur la page Chat interface. Les changements propagent à tous les widgets embarqués au reload.
Le widget utilise DM Sans comme police par défaut (chargée dans le Shadow DOM) et n'hérite pas de la typographie du site hôte. Contactez le support si vous avez besoin d'une police custom.
Pour aller plus loin
- Déclencher le chat depuis votre UI : câbler un CTA, une carte produit ou n'importe quel élément pour ouvrir le chat.
- Dépannage : widget qui ne s'affiche pas, problèmes CSP, câblage des évènements.
- FAQ : questions fréquentes sur l'intégration de Humind.