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). Votre propre UI de confirmation prend le relais ; le visiteur reste dans la conversation. 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.
noop	La variante est affichée sans CTA d'ajout au panier. Le bouton devient « Voir le produit » et ouvre la fiche produit à 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).

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.

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"
}

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.
• Vous possédez l'UI de confirmation : affichez votre propre mini-panier, toast ou modale en cas de succès. Le widget n'affiche volontairement aucune confirmation pour les actions function.
• 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.

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"
}

Deux destinations classiques :

• La fiche produit : zéro risque, fonctionne partout. Le visiteur termine l'ajout au panier sur votre propre fiche produit.
• Un lien profond d'ajout au panier : une URL qui, une fois ouverte, ajoute l'article au panier et affiche le panier, si bien que le visiteur saute la fiche produit. 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.

À 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.