Ajout au panier

Comment fonctionne le bouton « Ajouter au panier » du widget Humind, plateforme par plateforme : ce qui se passe sur Shopify, sur PrestaShop, sur WooCommerce, et comment le brancher sur une boutique custom. Pour personnaliser le style du bouton, voir les réglages du widget ; pour les événements analytics émis autour du panier, voir Analytics GA4 / GTM.

Comment ça marche

Chaque variante produit de votre catalogue Humind porte une cart action : une petite instruction, stockée avec la variante, qui dit au widget quoi faire quand un visiteur clique sur « Ajouter au panier ». Elle est calculée lors de la synchronisation de votre catalogue (app Shopify, flux géré) ou quand vous poussez vos produits via l'API Produits. Le widget l'exécute aveuglément : il n'a jamais besoin de savoir quelle plateforme e-commerce fait tourner votre boutique.

Il existe quatre familles de cart action :

Famille	Ce que vit le visiteur
Native (shopify, prestashop, woocommerce)	Le widget appelle l'endpoint panier de votre propre boutique depuis le navigateur du visiteur, sur votre domaine et avec sa session. Le produit atterrit dans le vrai panier, le mini-panier de votre thème se met à jour, et le visiteur reste dans la conversation.
function	Le widget appelle une fonction JavaScript d'ajout au panier que votre boutique expose sur window (un hook quick-buy, par exemple injecté via votre tag manager). Le widget confirme l'ajout dans la conversation ; le visiteur ne quitte jamais le chat. Voir boutiques custom.
redirect	Le widget envoie le visiteur vers une URL de votre choix : la fiche produit, ou n'importe quel lien profond d'ajout au panier que votre plateforme supporte. Son champ target dit laquelle des deux, et le CTA suit : « Voir le produit » pour une fiche produit, « Ajouter au panier » pour un lien profond.
noop	La variante est affichée sans CTA d'ajout au panier. Le bouton devient « Voir le produit » et ouvre la fiche produit dans le chat à la place. Utile quand l'achat est restreint (B2B) ou que le produit demande une configuration avant achat.

Après un ajout natif réussi, le widget :

1. affiche un toast de confirmation avec l'image du produit et un raccourci optionnel « Aller au paiement »,
2. met à jour le badge panier dans l'en-tête du chat,
3. pousse l'événement humind_product_added_to_cart dans votre dataLayer (voir analytics).

Un ajout function réussi affiche le même toast de confirmation. Son raccourci « Aller au paiement » ouvre la cart_url que vous posez sur la cart action (votre page panier ou paiement) ; sans cart_url, le raccourci est masqué, puisque le widget n'a pas de panier à lui à ouvrir sur une boutique custom. Le badge panier ne se met à jour que sur les plateformes où le widget peut lire le panier.

Les produits avec plusieurs variantes achetables ouvrent d'abord un sélecteur de variantes ; le visiteur en choisit une et le même flux s'exécute pour cette variante. Exception : les produits dont toutes les variantes utilisent redirect avec "target": "product_page", où le CTA mène directement à la fiche produit, sur laquelle le visiteur choisit sa variante.

Quelle famille pour vous ?

Les marchands Shopify ont les actions natives automatiquement. Les marchands PrestaShop et WooCommerce les obtiennent via l'API Produits, explicitement ou par dérivation automatique. Tous les autres choisissent function (ajout dans la conversation via votre propre hook de boutique), redirect ou noop via l'API Produits.

Shopify

Rien à configurer : l'app Humind synchronise votre catalogue et attache une cart action native à chaque variante.

• Le widget appelle l'endpoint standard /cart/add.js de votre boutique, sur votre domaine, donc le panier et la session existants du visiteur sont utilisés.
• Les boutiques multilingues sont gérées : la requête suit les routes de locale de votre boutique.
• Après un ajout réussi, le widget émet l'événement standard cart:updated sur document, que la plupart des thèmes (dont Dawn et ses dérivés) écoutent pour rafraîchir le tiroir panier et l'icône panier.
• L'icône panier de l'en-tête du chat envoie le visiteur vers le paiement par défaut. Vous pouvez l'envoyer vers la page panier à la place avec le réglage widget.cart_button_destination, ou depuis votre dashboard dans Agent IA, Interface de chat.
• Les lignes ajoutées depuis le chat portent une propriété de ligne _humind_source, pour les identifier dans vos données de commande.

Si l'endpoint panier est injoignable sur une page donnée (setups headless ou hybrides), le widget bascule sur l'ouverture de la fiche produit. Voir le dépannage pour les détails.

PrestaShop

PrestaShop 1.7 et suivants est supporté nativement : le widget appelle le contrôleur panier de votre propre boutique, en same-origin, avec le token CSRF que votre thème expose déjà. Le panier natif est mis à jour sur place et l'événement standard updateCart de PrestaShop est émis, donc l'indicateur panier de votre thème se rafraîchit.

Deux façons d'obtenir des cart actions PrestaShop sur vos variantes :

1. Dérivation automatique (recommandé) : poussez votre catalogue via l'API Produits en utilisant les ids PrestaShop comme external_id (id_product pour le produit, id_product_attribute pour la variante), et demandez-nous de marquer votre compte comme PrestaShop. Chaque variante reçoit alors une cart action native automatiquement. Veillez à renseigner online_store_url sur chaque produit : il est requis comme destination de repli.
2. cart_action explicite : poussez { "type": "prestashop", "id_product": ..., "id_product_attribute": ..., "product_url": ... } sur chaque variante. Voir la référence cart action.

Si la page du visiteur n'expose pas les globales front-office de PrestaShop (PrestaShop 1.6, thèmes très personnalisés), le widget bascule sur une redirection vers la fiche produit.

WooCommerce

WooCommerce est supporté nativement via l'API Produits, avec les deux mêmes chemins que PrestaShop :

1. Dérivation automatique : poussez votre catalogue avec les ids WooCommerce comme external_id (product_id pour le produit, variation_id pour la variante, 0 quand le produit n'a pas de variation), et demandez-nous de marquer votre compte comme WooCommerce. online_store_url est requis sur chaque produit.
2. cart_action explicite : poussez { "type": "woocommerce", "product_id": ..., "variation_id": ..., "product_url": ..., "attributes": { ... } }. La map attributes porte les valeurs attribute_* (par exemple pa_color, pa_size) dont les produits variables ont besoin.

Le widget soumet la requête standard add-to-cart vers la page produit, en same-origin, puis rafraîchit les fragments panier du thème pour que votre mini-panier se mette à jour.

Produits variables

La dérivation automatique ne remplit pas attributes. Si vos produits variables exigent des paramètres d'attributs pour ajouter la bonne variation, poussez une cart_action explicite avec la map attributes.

Boutiques custom et autres plateformes

Sur toute autre stack (Magento, BigCommerce, headless, plateformes maison), vous avez trois options.

Appeler votre propre fonction d'ajout au panier

Si votre boutique expose (ou peut exposer) une fonction JavaScript d'ajout au panier, poussez une cart action function et le widget l'appelle directement, pour que les visiteurs ajoutent au panier sans quitter la conversation :

{
  "type": "function",
  "name": "myQuickBuy",
  "args": { "productId": "SKU123" },
  "product_url": "https://www.votre-boutique.com/p/sku123",
  "cart_url": "https://www.votre-boutique.com/panier"
}

Le contrat de votre côté :

• Exposez la fonction sur window (une fonction globale, par exemple injectée via votre tag manager) : window.myQuickBuy = async ({ productId, qty }) => { ... }.
• Quand le visiteur clique sur « Ajouter au panier », le widget l'appelle avec un unique argument objet : vos args stockés plus un nombre qty (la quantité choisie dans le widget, 1 depuis les CTA du chat). Ignorez les champs que vous ne reconnaissez pas : l'objet peut gagner de nouveaux champs optionnels avec le temps (sélection de variante par exemple) sans breaking change.
• Retournez un signal de succès : une Promise résolvant { "success": true } (ou simplement rien) en cas de succès, et { "success": false, "errorName": "out_of_stock" } (ou une Promise rejetée) en cas d'échec. Le widget s'en sert pour enregistrer l'ajout et ses événements analytics, et pour dire au visiteur ce qui s'est passé (voir ci-dessous).
• Le widget possède l'UI de confirmation : en cas de succès, il affiche son toast de confirmation dans la conversation (image du produit, titre et quantité, plus un bouton « Aller au paiement » qui ouvre cart_url si vous en posez une), donc votre fonction ne doit pas ouvrir sa propre modale ou son propre overlay. La fenêtre de chat est à un z-index très élevé et en plein écran sur mobile, une confirmation au niveau de la page serait de toute façon masquée derrière elle. Mettez plutôt votre mini-panier à jour silencieusement.
• Quand la fonction n'est pas présente sur la page (visiteur hors d'un bucket d'AB test, page exclue, tag manager non chargé), le widget bascule automatiquement sur une redirection du visiteur vers product_url. Pas d'erreur, pas de bouton mort.

Nommer un échec

errorName est optionnel, et n'importe quelle valeur continue de fonctionner : un nom que le widget ne reconnaît pas produit simplement un message générique. Nommer la raison, c'est ce qui permet au widget de dire quelque chose d'utile, dans la langue du visiteur, dans toutes les langues qu'il supporte.

Voici les noms sur lesquels il agit :

errorName	Ce que voit le visiteur
out_of_stock	Le produit vient de passer en rupture de stock.
selection_required	Aucun message d'erreur. Le visiteur est envoyé vers product_url, parce qu'une taille, une variante ou une option ne se choisit que sur votre fiche produit. Si cette URL est absente ou n'est pas en http(s), le widget se rabat sur un message invitant le visiteur à choisir ses options sur la fiche produit.
not_purchasable	Le produit ne s'achète pas seul : cadeau, produit vitrine, coffret.
product_not_found	La boutique ne connaît pas ce produit, ou il est hors ligne.
max_quantity_reached	Le visiteur a atteint votre plafond par produit ou par panier.
add_refused	La boutique a refusé l'ajout, sans le qualifier davantage.
context_not_allowed	L'ajout au panier est interdit sur cette page (paiement, confirmation de commande).
integration_error	L'appel sortait du contrat convenu. Jamais présenté comme la faute du visiteur.
network_error	Un échec de transport. Le visiteur est invité à réessayer.
unknown_error	Tout le reste, et le repli des noms non reconnus.

Retournez ces noms tels quels (minuscules, underscores). Tout autre nom est traité comme unknown_error.

Surveillez selection_required et product_not_found

Ces deux-là parlent du catalogue, pas du visiteur. selection_required signifie que nous avons proposé l'achat en un clic sur un produit qui demande d'abord un choix, et product_not_found que notre copie de votre catalogue est en retard sur la vôtre. Les deux méritent de nous être signalés : ils se corrigent chez nous, à la synchronisation, pas chez vous.

Référence des champs : cart action.

redirect

Le widget fait naviguer l'onglet du visiteur vers l'URL que vous avez stockée, exactement comme s'il avait cliqué sur un lien. La conversation se ferme le temps de cette navigation et se rouvre là où elle en était sur la page de destination, tant que le widget y est installé.

{
  "type": "redirect",
  "url": "https://www.votre-boutique.com/panier?add-to-cart=123",
  "target": "add_to_cart"
}

Deux destinations classiques, et target dit laquelle vous avez stockée :

• La fiche produit ("target": "product_page") : zéro risque, fonctionne partout. Le visiteur termine l'ajout au panier sur votre propre fiche produit. Le widget affiche le CTA « Voir le produit » et y envoie le visiteur directement, sans passer par un sélecteur de variantes.
• Un lien profond d'ajout au panier ("target": "add_to_cart") : une URL qui, une fois ouverte, ajoute l'article au panier et affiche le panier, si bien que le visiteur saute la fiche produit. Le widget affiche le CTA « Ajouter au panier ». Toute URL GET que votre stack expose pour cela convient ; les plateformes dont l'endpoint panier exige un jeton CSRF de session ne peuvent pas offrir d'URL stable, auquel cas redirigez vers la fiche produit ou utilisez plutôt une action function.

Posez target quand votre URL est une fiche produit

Les deux destinations sont valides et nous ne pouvons pas les distinguer depuis l'URL : un target absent vaut add_to_cart et le bouton affiche « Ajouter au panier ». L'omettre sur une URL de fiche produit donne donc au visiteur un CTA panier qui le dépose sur votre page sans rien avoir ajouté. Le défaut penche de ce côté volontairement : l'erreur inverse, un bouton « Voir le produit » qui remplit le panier en silence, est celle dont le visiteur ne se remet pas.

À quoi doit ressembler l'URL

• Une URL absolue avec le schéma et le domaine : https://www.votre-boutique.com/panier?add-to-cart=123. Seule la forme raccourcie sans domaine (/panier?add-to-cart=123) est refusée, car l'API ne peut pas deviner quel domaine ajouter devant. Les paramètres de requête sont libres : ajoutez-en autant que nécessaire, y compris des paramètres de tracking ou une URL encodée dans un paramètre.
• http:// ou https:// uniquement. javascript:, data: et tout autre schéma sont refusés.
• Tout domaine est autorisé. L'URL n'a pas besoin d'être sur le domaine où le widget est installé : pointer vers un funnel de vente, une landing page ou un parcours de réservation hébergé sur un autre domaine est un cas d'usage supporté. Deux choses à garder en tête quand vous quittez le domaine de votre boutique : le panier existant du visiteur (stocké dans les cookies de votre domaine boutique) ne suit pas, sauf si votre funnel le gère lui-même, et la conversation ne se rouvre sur la page de destination que si le widget y est aussi installé.
• L'URL est stockée par variante et utilisée telle quelle : le widget n'y ajoute rien. En particulier, la quantité choisie dans le widget n'est pas transmise ; le lien profond ajoute la quantité que l'URL encode elle-même (en général 1).

noop

Affichez le produit avec un bouton « Voir le produit » uniquement.

Les trois se définissent par variante via l'API Produits. redirect et noop fonctionnent sans aucun code de votre côté ; function demande la seule fonction ci-dessus. Si vous hésitez sur ce qui convient à votre stack, contactez-nous.

Mesurer l'activité panier

Indépendamment de la plateforme, chaque ajout et retrait initié depuis le widget est :

• poussé dans votre window.dataLayer sous humind_product_added_to_cart / humind_product_removed_from_cart (avec product_id, product_variant_id, price), prêt à être transféré vers l'événement add_to_cart de GA4 depuis votre tag manager : voir Analytics GA4 / GTM,
• enregistré dans vos analytics Humind, alimentant le reporting de conversion et de revenu de votre dashboard.