Dépannage

Problèmes courants en embarquant les widgets Humind, avec les vérifications les plus rapides pour chacun.

Vérifications rapides

Avant d'aller plus loin, lancez ces checks :

1. document.querySelector('humind-widget') (ou humind-quiz, humind-gift-finder, humind-product-questions) — est-ce que ça renvoie l'élément ?
2. Onglet Network : les scripts du loader (embed.thehumind.com/loader.js et/ou widgets.thehumind.com/v1/loader.js) reviennent-ils en 200 OK ?
3. Le domaine de votre storefront est-il whitelisté sur la company dans le dashboard Humind ?
4. Console : y a-t-il des warnings ou erreurs humind-* ?

La plupart des problèmes tombent sur un de ces quatre points.

Rien ne render

Le script n'a pas chargé

Ouvrez devtools → Network et regardez soit embed.thehumind.com/loader.js (chat), soit widgets.thehumind.com/v1/loader.js (bundle widgets — quiz, gift-finder, product-questions). Si la requête manque, votre balise <script> n'est pas dans le DOM ou un CSP la bloque.

Fix : assurez-vous que la balise est présente sur chaque page qui render un widget. Pour le CSP, ajoutez :

script-src 'self' https://widgets.thehumind.com https://embed.thehumind.com;
connect-src 'self' https://api.thehumind.com wss://api.thehumind.com;
img-src 'self' data: https://*.thehumind.com https://cdn.shopify.com;

Bundle chargé, widget toujours invisible

Vérifiez :

document.querySelector('humind-widget')  // ou humind-quiz, humind-gift-finder, humind-product-questions

Si ça renvoie null, votre markup ne contient pas le custom element. Si ça renvoie l'élément mais que rien n'est visible, regardez les styles calculés. Un conteneur parent avec display: none, height: 0 ou overflow: hidden clip le widget.

Le widget s'affiche mais le backend ne trouve pas mon ID produit / collection

Le widget monte, mais le backend répond 404/400 et le widget reste caché ou bloqué sur « Loading… ».

Marchands Shopify : les produits et collections sont synchronisés automatiquement. Si un ID manque, la synchro initiale n'est peut-être pas terminée (voir La synchro n'a pas fini plus bas).

Marchands non-Shopify : vous devez pousser les produits et collections au backend Humind vous-même, et les externalIds que vous envoyez doivent correspondre exactement aux valeurs que vous passez en product-id / collection-id sur le widget. Si ça ne match pas, le backend ne peut pas résoudre le widget et celui-ci reste caché.

Comment checker : ouvrez l'onglet Network et regardez l'appel de résolution du widget, par exemple :

GET /widgets/product-questions?productId=<votre-id>

• 200 avec un payload → le backend a trouvé le produit, le problème est ailleurs.
• 404 → l'externalId que vous avez poussé ne correspond pas au product-id.
• 400 → le format d'ID est mauvais pour l'integration déclarée.

Re-synchronisez les produits concernés via votre pipeline de push catalogue et re-vérifiez.

Widget charge mais affiche « Loading… » indéfiniment

L'identifiant est faux

Chaque widget a besoin d'un vrai ID dans sa plateforme :

• <humind-quiz collection-id="…"> : handle de collection Shopify ou votre ID de collection interne.
• <humind-product-questions product-id="…"> : GID Shopify (gid://shopify/Product/12345) ou votre ID produit interne.
• <humind-gift-finder shop-domain="…"> : le domaine sous lequel votre compte Humind est enregistré.

Vérifiez la requête vers api.thehumind.com/widgets/* dans devtools. Un 404 ou 400 là vous dit que l'ID est inconnu.

Mauvais matching integration

Si integration="shopify" mais que l'ID passé n'est pas un GID Shopify (ou vice versa), le backend ne peut pas le résoudre. Matchez la valeur integration au format d'ID.

La synchro n'a pas fini

Pour une boutique Shopify fraîchement installée, laissez quelques minutes à la synchro initiale. Les produits apparaissent dans Humind en quelques secondes de leur publication, mais la première synchro catalogue complète peut prendre plus longtemps. Vérifiez app.thehumind.com → Catalogue → Statut de synchro.

Le chat ne s'ouvre pas quand on clique sur une chip widget

Les widgets dispatchent humind-open-chat sur window. Si l'overlay de chat (<humind-widget>) n'est pas sur la page, rien n'écoute et l'event est un no-op.

Fix : installez <humind-widget> à côté du widget in-page. Voir Installer le chat.

Le chat s'ouvre mais ne stream rien

Deux chemins de streaming différents, deux modes d'échec différents :

• Overlay de chat (<humind-widget>) utilise WebSocket (wss://api.thehumind.com). Si WebSocket est bloqué, l'overlay affiche un état « indisponible » et ne montre jamais de messages.
• Bundle widgets (quiz, gift-finder, product-questions) utilise SSE via POST /chat/stream. Si SSE est bloqué, les résultats du quiz (et autre contenu streamé) chargent indéfiniment.

WebSocket bloqué

Certains proxies et firewalls corporate strip le header Upgrade: websocket. Vérifiez l'onglet Network → WS — vous devriez voir une connexion long-lived vers wss://api.thehumind.com. Si elle n'arrive pas à upgrade ou ferme immédiatement, checkez le proxy ou CDN entre le navigateur et Humind.

Assurez-vous aussi que votre CSP inclut connect-src wss://api.thehumind.com.

SSE bloqué

Certains proxies corporate strip Content-Type: text/event-stream. Vérifiez l'onglet Network : vous devriez voir un POST long-lived vers /chat/stream avec des events JSON partiels. Si elle ferme immédiatement ou si elle bufferise toute la réponse, checkez votre proxy ou CDN.

Le quiz s'affiche mal — mon CSS casse son layout

<humind-quiz> est le seul widget à utiliser le light DOM. Du coup votre CSS global cascade dedans et peut écraser les styles propres du quiz.

L'overlay de chat (<humind-widget>), <humind-gift-finder> et <humind-product-questions> utilisent tous Shadow DOM, donc rien ne fuit ni dans un sens ni dans l'autre.

Contournement : scopez vos resets globaux, ou wrappez le quiz dans un conteneur qui reset les propriétés critiques :

.humind-quiz-wrap * {
  box-sizing: border-box;
  /* autres resets nécessaires */
}

Coupables classiques : margin: 0 universel, overrides agressifs de font-family, line-height globaux, et règles img { max-width: 100% } qui écrasent les images produit du quiz.

Pour info, les stacks de polices par défaut sont :

• Quiz (light DOM) : system-ui, -apple-system, sans-serif
• Gift finder / Product questions (Shadow DOM) : Arial, Helvetica, sans-serif
• Overlay de chat (Shadow DOM) : DM Sans

Setup Shopify hybride (backend Shopify + storefront custom)

Si vous utilisez Shopify pour le commerce mais servez votre propre storefront (headless, Hydrogen, ou n'importe quel framework sur un domaine non-Shopify), quelques différences par rapport à une install Shopify standard :

• Le chat n'est pas auto-injecté. L'extension de thème Shopify ne tourne que dans les pages rendues par Shopify. Sur un storefront custom, vous devez coller le markup <humind-widget> et le script embed.thehumind.com/loader.js dans votre layout à la main.
• Le CORS s'applique quand même. integration="shopify" dit juste au backend comment résoudre les produits ; ça n'exempte pas votre domaine de la whitelist CORS. Ajoutez le domaine de votre storefront custom sur la company dans le dashboard Humind.
• L'add-to-cart depuis le quiz ne marchera pas. Le quiz appelle POST /cart/add.js sur la même origine, endpoint qui n'existe que sur les pages hébergées par Shopify. Sur un storefront custom cet endpoint renvoie 404. Il faudra écouter l'event de sélection produit du quiz et appeler votre propre API panier.

Add-to-cart ne marche pas depuis le quiz

N'arrive que sur Shopify. Le quiz appelle POST /cart/add.js sur la même origine que la page où il est. Si vous testez contre une boutique depuis localhost, add-to-cart échoue silencieusement.

Fix : testez sur la vraie URL de preview Shopify, ou utilisez le playground du dashboard Humind.

Shopify headless ou hybride : le quiz ne pourra pas ajouter au panier automatiquement — cart.js n'est pas présent sur les storefronts custom. Il faudra gérer les opérations panier vous-même en écoutant l'event de sélection du quiz et en appelant votre propre API panier.

humind-open-chat se déclenche mais l'overlay l'ignore

Confirmez que la cible de l'event est window, pas document :

// ✅ Marche
window.dispatchEvent(new CustomEvent('humind-open-chat', { detail: { message: 'Salut' } }))

// ❌ Ne déclenche pas le chat
document.dispatchEvent(new CustomEvent('humind-open-chat', { detail: { message: 'Salut' } }))

<humind-widget> render deux fois

Le loader garde contre la double-registration mais certains bundlers (HMR en dev, React strict mode) peuvent déclencher deux scripts. <humind-widget> log un warning console et skip la seconde registration ; les autres widgets (<humind-quiz>, <humind-gift-finder>, <humind-product-questions>) skipent silencieusement. Si vous voyez du double rendering en prod, trouvez la seconde balise <script> et retirez-la.

Erreurs CORS sur api.thehumind.com

api.thehumind.com autorise :

• https://*.thehumind.com
• Le ou les domaines marchands enregistrés sur la company dans le dashboard Humind

La whitelist est appliquée côté backend, donc un mismatch remonte dans le navigateur comme une erreur CORS même si la vraie barrière est côté serveur. Si vous hébergez sous un domaine qu'on ne connaît pas — un storefront custom, un sous-domaine de staging, un domaine reseller en marque blanche — ouvrez les settings de la company dans app.thehumind.com et ajoutez-le, ou contactez le support.

Fallback de langue

Définir language="xx" pour un code non supporté retombe sur l'anglais silencieusement. Pour confirmer quelle langue est active, inspectez l'attribut lang sur l'élément racine du widget après mount.

Humind supporte environ une douzaine de codes de langue (anglais, français, espagnol, allemand, italien, portugais, néerlandais, et quelques autres). Les codes non reconnus retombent sur l'anglais sans lever d'erreur. Voir Installer le chat pour la liste supportée à jour.

Toujours bloqué ?

1. Run document.querySelector('<element>').outerHTML et confirmez que les attributs sont ce que vous pensez.
2. Récupérez un fichier HAR du chargement de page.
3. Emailez le support avec le HAR et la config du widget. Incluez votre company-id qu'on puisse lookup l'état du catalogue.