Documentation AI Personal Shopper

Installation

Prérequis

Magento 2.4.x — testé sur 2.4.9, compatible avec les versions précédentes 2.4.*. PHP 8.1–8.5. Compatible avec le thème Luma par défaut comme avec le thème Hyvä (le widget de chat s'affiche dans un Shadow DOM isolé, donc identique sur les deux, sans modification de template). Dépend du module gratuit codingrow/module-core, installé automatiquement. Nécessite une clé API d'au moins un fournisseur d'IA (OpenAI, Anthropic, Google ou OpenRouter) — facturée directement par le fournisseur.

Étapes d'installation

1. Ajoutez les identifiants que vous recevrez par e-mail à auth.json à la racine de votre projet Magento :

   { "http-basic": { "repo.codingrow.com": { "username": "...", "password": "..." } } }

2. composer config repositories.codingrow composer https://repo.codingrow.com
3. composer require codingrow/module-ai-personal-shopper
4. bin/magento module:enable Codingrow_AiPersonalShopper
5. bin/magento setup:upgrade && bin/magento setup:di:compile
6. Collez votre clé de licence dans Admin → Stores → Configuration → Codingrow → AI Personal Shopper → License → License Key, enregistrez, puis bin/magento cache:flush.

Configuration

Ouvrez Admin → Stores → Configuration → Codingrow → AI Personal Shopper. Saisissez la License Key, mettez Enable sur Yes, puis passez en revue les Capabilities. Fournisseur, modèle et clé API ne sont pas ici : on ajoute une IA dans l’onglet AI Models (Codingrow → AI Personal Shopper → AI Models).

Désinstallation

Réglez Enable sur No et enregistrez pour masquer le widget immédiatement. Pour supprimer complètement le module : bin/magento module:disable Codingrow_AiPersonalShopper puis composer remove codingrow/module-ai-personal-shopper.

Configuration du fournisseur d'IA

Choisir un fournisseur

L'assistant fonctionne avec l'un des quatre fournisseurs — vous apportez votre propre clé API, et l'usage de l'IA vous est facturé directement par le fournisseur choisi. OpenAI (ChatGPT/GPT) offre la gamme la plus large ; Anthropic (Claude) convient bien à un assistant qui doit rester dans le cadre ; Google (Gemini) a des prix compétitifs et est rapide ; OpenRouter vous donne une seule clé pour des dizaines de modèles de différents fournisseurs, pratique pour comparer coût et qualité.

Obtenir une clé API OpenAI

1. Connectez-vous sur platform.openai.com.
2. Allez sur platform.openai.com/api-keys.
3. Cliquez sur Create new secret key, donnez-lui un nom (par ex. « AI Personal Shopper ») et copiez-la immédiatement — elle n'est affichée qu'une seule fois.
4. Ajoutez-la comme nouvelle IA dans l’onglet AI Models (Codingrow → AI Personal Shopper → AI Models) avec Provider réglé sur OpenAI, puis utilisez Load models pour choisir le modèle.

Obtenir une clé API Anthropic

1. Connectez-vous sur console.anthropic.com.
2. Allez sur console.anthropic.com/settings/keys.
3. Cliquez sur Create Key, donnez-lui un nom et copiez la valeur.
4. Ajoutez-la comme nouvelle IA dans l’onglet AI Models (Codingrow → AI Personal Shopper → AI Models) avec Provider réglé sur Anthropic, puis utilisez Load models pour choisir le modèle.

Obtenir une clé API Google

1. Connectez-vous sur aistudio.google.com avec un compte Google.
2. Allez sur aistudio.google.com/app/apikey.
3. Cliquez sur Create API key, choisissez ou créez un projet Google Cloud et copiez la clé.
4. Ajoutez-la comme nouvelle IA dans l’onglet AI Models (Codingrow → AI Personal Shopper → AI Models) avec Provider réglé sur Google, puis utilisez Load models pour choisir le modèle.

Obtenir une clé API OpenRouter

1. Connectez-vous sur openrouter.ai.
2. Allez sur openrouter.ai/keys.
3. Cliquez sur Create Key, donnez-lui un nom et copiez la valeur.
4. Ajoutez-la comme nouvelle IA dans l’onglet AI Models (Codingrow → AI Personal Shopper → AI Models) avec Provider réglé sur OpenRouter, puis utilisez Load models pour choisir le modèle.

Load models

Une fois la clé API en place, cliquez sur Load models sous le champ Model : le module interroge le point de terminaison de liste de modèles du fournisseur avec votre clé et remplit une liste déroulante avec tous les modèles que votre clé peut réellement utiliser — choisissez dans la liste plutôt que de saisir un id. Un champ de texte manuel reste disponible en secours pour un id de modèle pas encore dans la liste. Un lien juste sous le champ pointe toujours vers la bonne page pour obtenir la clé du fournisseur actuellement sélectionné.

Calculateur de duree du budget

L'usage de l'IA est facture par le fournisseur au token, la question naturelle est donc combien de temps durera un budget donne. L'ecran de configuration y repond directement : juste sous les cles API se trouve un petit calculateur de budget. Saisissez votre budget, le prix du modele par million de tokens en entree/sortie (des prereglages sont fournis pour Gemini Flash, OpenAI gpt-4o-mini, Claude Haiku 4.5 et Claude Sonnet 4.5) et le nombre de chats attendu par jour. Il affiche instantanement le cout par chat et le nombre de jours que dure le budget dans un scenario optimiste (chats courts) et un scenario pessimiste (chats longs).

Les hypotheses de tokens par chat sont identiques d'une plateforme a l'autre — seul le prix du modele change — la comparaison est donc equitable. Un tableau de reference indique approximativement combien de temps dure un budget de €100 sur chaque modele a environ 10 chats par jour. Ce n'est qu'une aide a la planification ; le cout reel est toujours facture par le fournisseur.

Qualité et coût. Le module donne déjà au modèle tout ce dont il a besoin pour répondre et assister — catalogue, commandes, promotions, catégories, synonymes et outils. La qualité des réponses dépend ensuite du modèle que vous choisissez : si elles ne vous satisfont pas, essayez simplement un autre modèle ou fournisseur. Le coût découle directement de ce choix — mais ce type d'assistant n'a pas besoin d'un modèle coûteux, « de raisonnement » ou complexe : un modèle économique et rapide (gamme « flash »/« mini ») convient parfaitement.

Réglage IA et diagnostics

Chaque IA du pool porte ses propres réglages, sur sa carte dans l’onglet AI Models — plus une limite qui reste dans Configuration :

• Max response tokens (sur la carte de l’IA) — limite la longueur de chaque réponse ; le baisser garde les réponses courtes et les coûts bas.
• Temperature (sur la carte de l’IA) — de réponses concentrées et prévisibles à des formulations plus variées. Laissé vide, il n’est pas envoyé du tout, ce qu’exigent les familles de modèles les plus récentes.
• Max tool rounds (Stores → Configuration → … → Agent limits) — de 1 à 8, combien de fois le modèle peut appeler ses outils (recherche, suivi de commande, …) avant de devoir répondre ; plus haut autorise des réponses plus fouillées en plusieurs étapes, plus bas est plus rapide et moins cher.
• Recent AI calls (diagnostic) (onglet AI Models) — les 10 derniers appels au modèle avec leur résultat, l’erreur, le message et la réponse : quand une réponse n’arrive pas, on voit pourquoi d’un coup d’œil. Avec le failover actif, il nomme l’IA qui a réellement répondu, pas la principale.

Note importante : la qualité, la cohérence et la proactivité des réponses dépendent surtout du modèle IA que vous choisissez, pas seulement du module. Un modèle rapide et bon marché (une gamme « flash »/« mini »/Haiku) coûte peu mais est moins bon pour organiser l'ordre des cartes, réduire les options à quelques-unes et proposer des associations/du cross-sell ; un modèle plus performant (par ex. Claude Sonnet, un modèle de classe GPT-4) suit cette logique de façon bien plus fiable. Si les réponses ne vous satisfont pas, la première chose à essayer est de passer à un modèle plus puissant — le coût évolue en conséquence, utilisez le calculateur ci-dessus.

Guide d'utilisation

Capabilities

Chaque capability est un interrupteur indépendant sous Capabilities. En désactiver une retire immédiatement cette capacité à l'agent — rien n'est jamais supposé ou déduit au-delà de ce qui est activé :

• Recherche de produits — recherche en langage naturel sur le catalogue en direct, renvoyée sous forme de cartes produit (ou de cartes catégorie quand la demande est trop vague pour un seul produit).
• Statut de commande — consulte le statut réel de la commande pour les clients connectés, ou pour les invités qui confirment le numéro de commande + l'email.
• Promotions — l'agent connaît les remises actives et peut les mentionner ou filtrer en fonction.
• Lecture du contenu de catégorie — permet à l'agent de lire la description PageBuilder propre à une catégorie (get_category_info), pour que les guides d'achat, guides des tailles et textes éditoriaux que vous avez déjà rédigés sur les pages de catégorie alimentent la réponse au lieu d'être ignorés.
• Ajout au panier — permet au client d'ajouter un produit directement depuis une carte, avec un sélecteur de quantité, sans quitter le chat.
• Saisie vocale — les clients peuvent dicter leur demande au lieu de la taper (microphone Web Speech).
• Synonymes auto-appris — enregistre la correspondance entre un mot de recherche qui a échoué et le terme du catalogue qui a fini par correspondre.
• Tickets de support humain — permet à l'agent d'ouvrir un ticket et de passer la main à une personne quand une demande a vraiment besoin d'un humain ; en la désactivant, l'agent ne proposera jamais d'ouvrir un ticket.
• Suggestions de cross-sell final — lorsque le client s'apprête à conclure, l'agent peut ajouter un ou deux produits complémentaires en dernière suggestion avant de prendre congé. Désactivé par défaut ; ne l'activez que si vous voulez ce petit coup de pouce final.

L'expérience produit

Tout ce que le client voit dans le chat — quels produits, dans quel ordre, et comment les cartes changent au fil de la conversation — est piloté par l'assistant, et non par une liste de résultats figée.

• Cartes sélectionnées, en direct — l'assistant recherche largement, puis choisit quels produits afficher et dans quel ordre, en orientant vers 2–3 options solides plutôt que de déverser un mur de résultats. Les cartes se rafraîchissent en temps réel à chaque tour : à mesure que le client affine (« celle en mangue », « quelque chose de moins cher »), la grille est reconstruite en conséquence.
• Cartes catégorie — quand une demande est trop vague pour un seul produit (« un cadeau pour la maison, je ne sais pas trop quoi »), l'assistant propose des catégories à explorer au lieu d'une impasse.
• Réponses rapides — des boutons d'options cliquables proposés sous un message, pour que le client puisse avancer d'un clic au lieu de taper.
• Ajouter au panier — un sélecteur de quantité sur la carte confirme avant l’ajout. Depuis la 2.2.0, les produits avec tailles, couleurs ou plusieurs articles s’achètent aussi dans le chat : l’assistant pose une question à la fois et la bonne variante part au panier. La fiche produit n’est proposée que pour les options que le chat ne sait pas gérer, comme une gravure ou un fichier à téléverser.
• Cartes enrichies — les cartes produit affichent le nom, l'image, le prix et toute remise, plus un « Tell me more » ; les cartes de commande affichent le suivi (transporteur + numéro) lorsqu'il est disponible.
• Persistance — la conversation survit à un rafraîchissement de page pendant 7 jours, et un bouton Start over l'efface pour repartir de zéro.

Tailles, couleurs et kits

Depuis la 2.2.0, le panier du chat n’accepte plus seulement les produits simples. Lorsqu’un produit comporte des choix, l’assistant les propose un à la fois dans la conversation, et le produit part au panier avec la bonne variante.

• Configurables — d’abord la taille, puis la couleur, puis la quantité, dans l’ordre où vous avez configuré les attributs dans Magento. Les combinaisons qui n’existent pas ne sont jamais proposées.
• Groupés (kits) — tous les articles d’un coup, chacun avec sa quantité ; ceux laissés à zéro ne finissent pas au panier.
• Bundle (ensembles modulaires) — un choix par option, accessoires facultatifs compris.

Les choix sont dessinés comme vous les avez configurés dans Magento : les couleurs avec leur vrai code hexadécimal, les tailles en grand et lisibles, les longues listes en menu déroulant. La quantité apparaît sur la dernière carte du parcours. Sur ordinateur tout se passe dans le panneau latéral, sur téléphone dans le chat. Sur les cartes de bundle et de groupés, le prix est la vraie fourchette, et non 0,00 €.

Les options épuisées restent visibles, grisées. C’est le comportement par défaut : cacher une taille épuisée ferait croire au client que vous ne la faites pas. L’interrupteur se trouve dans Stores → Configuration → Codingrow → AI Personal Shopper → Catalog Search → Show unavailable choices, greyed out ; celles encore commandables ne sont jamais grisées. À ne pas confondre avec Only in-stock products, qui décide si le produit est proposé tout court.

Si un produit a des options personnalisées que le chat ne sait pas gérer (une gravure à saisir, un fichier à téléverser), l’assistant le dit et propose le lien vers la fiche, au lieu d’ouvrir une page sans explication.

Sessions et conscience de la page

L'assistant garde la trace de qui il parle et où, pour que la conversation semble continue et reste sur le bon produit.

• Rite d'entrée — au lieu d'une réponse toute faite instantanée, le widget affiche un bref Connecting…, puis un opérateur portant un nom « rejoint le chat » après 10–20 s et demande le nom du client. Le timing et la frappe sont simulés, et le rythme est configurable.
• Sessions — si le client revient après plus de ~5 minutes, une nouvelle session démarre sans redemander le nom, marquée par une ligne de séparation dans le chat ; en deçà de quelques minutes, elle continue simplement.
• Contexte de page produit — quand le chat est ouvert depuis une page produit, une question implicite (« parle-m'en », « de quoi est-ce fait ? ») se résout sur ce produit, lié nativement par URL/url_key et robuste face aux redirections.
• Conscience du panier — via get_cart l'assistant peut prendre ce qui est déjà dans le panier comme un signal d'intérêt — pour suggérer des correspondances et éviter de reproposer ce qui s'y trouve déjà — sans le commenter.
• Cross-sell final — lorsque la capability est activée et que le client a terminé, il ajoute un ou deux produits complémentaires en dernière suggestion, puis prend congé.

Assistant proactif

Depuis la 2.2.0, l’assistant peut prendre l’initiative. Cela se règle dans Stores → Configuration → Codingrow → AI Personal Shopper → Proactive assistant et tout est éteint au départ : un vendeur qui parle le premier vend davantage ou agace, et vous seul savez comment vous parlez à vos clients. En aucun cas la fenêtre du chat ne s’ouvre toute seule : l’assistant allume la pastille sur le bouton et attend.

• Suggest pairings after an add to cart — Never (par défaut), only the first time in a visit ou every time. Quand le client met quelque chose au panier en parcourant la boutique, l’assistant prépare deux associations. Chaque fois, c’est un appel à l’IA, facturé par votre fournisseur. Il n’y a aucun délai ici : cela part immédiatement et apparaît quand le modèle répond.
• Offer help after (seconds on the page) — 0 = jamais (par défaut). Si le client est sur une page depuis ce temps-là sans avoir jamais ouvert le chat, on lui propose un coup de main. Cela ne coûte rien : la phrase est écrite par le widget. Jamais sur le panier ni sur le checkout.
• What it says — le texte de l’invitation. Vide = phrase par défaut, traduite dans toutes les langues du module.

Fonctionne aussi bien sur Hyvä que sur Luma : le widget écoute les événements que le thème émet déjà quand le panier change, donc un ajout en AJAX sans rechargement de page est lui aussi détecté.

Les conversations nées ainsi sautent le rituel du nom et arrivent dans Conversations sans nom : on les reconnaît à la colonne Origin (Customer, Assistant — after an add to cart, Assistant — offered help). Si le client répond et donne son nom, celui-ci est enregistré comme dans n’importe quelle autre conversation.

Branding et couleurs

Définissez un Assistant name (affiché comme le nom de l'opérateur, par ex. « Anna ») et, optionnellement, un Brand logo (hauteur fixe pour qu'il ne se déforme jamais) ou un Brand text avec le nom de votre entreprise — affichés en haut à gauche de l'en-tête du chat. Le nom de l'opérateur reste visible en sous-ligne avec un point de présence en direct sous la marque, même quand un logo est défini. Accent color contrôle le bouton d'ouverture et les accents du chat ; Header/theme color (optionnel) colore la barre d'en-tête et les bulles de message du client — laissez-le vide pour réutiliser l'accent color.

Bouton de recherche IA

Lorsque la barre de recherche fixe du module Live Search est active, l'AI Personal Shopper peut ajouter un second bouton loupe IA juste a cote du champ de recherche. Un clic ouvre le chat de l'assistant ; et si le client a deja saisi quelque chose dans le champ de recherche, ce texte est envoye directement comme premier message — ainsi une recherche qui renvoie trop (ou zero) resultats devient une conversation guidee en un seul geste.

Activez-le dans Stores → Configuration → Codingrow → AI Personal Shopper → Assistant & Branding avec AI button in the search bar = Yes. C'est une integration souple : si Live Search n'est pas installe ou si sa barre fixe est desactivee, le bouton n'apparait tout simplement pas — aucune dependance obligatoire.

Synonymes auto-appris

Lorsqu'elle est activée (Capabilities → Self-learning synonyms), l'agent enregistre une correspondance chaque fois que le mot de recherche d'un client ne correspond pas directement au catalogue mais qu'une tentative ultérieure fonctionne — noms régionaux, dialecte, fautes de frappe, synonymes. Consultez et modifiez le registre dans Codingrow → AI Personal Shopper → Synonyms : un tableau paginé et modifiable en ligne. Utilisez Export CSV / Import CSV pour le sauvegarder, le modifier en masse ou le déplacer entre environnements. Le bouton Inject into site search déverse tout le registre dans les Search Synonyms natifs de Magento, pour que la barre de recherche du site en profite aussi — pas seulement le chat. L'agent lit aussi vos Search Synonyms natifs entretenus manuellement, si bien que les deux systèmes se renforcent mutuellement.

Exemple : un client cherche « sweat à capuche » et l'agent ne trouve rien directement, mais une tentative ultérieure avec « hoodie » correspond — la paire est enregistrée automatiquement, si bien que la prochaine recherche « sweat à capuche » se résout immédiatement, et vous pouvez l'injecter dans la recherche native en un clic.

Tickets de support humain

Lorsqu'elle est activée (Capabilities → Human support tickets), l'agent propose d'ouvrir un ticket si un client a besoin d'un humain et que la conversation seule ne résout pas le problème. Il demande l'e-mail (obligatoire) et, si utile, le numéro de commande et un contact téléphone/WhatsApp, puis attribue un numéro de ticket — préfixé par Ticket number prefix (par défaut AIPS-), par ex. AIPS-000042 — et envoie par e-mail la transcription complète au client, en copie cachée à l'adresse définie dans Human support → Support email (BCC) (si laissée vide, l'e-mail va uniquement au client). Le texte du délai de réponse affiché au client provient de Human support → Response time.

Les tickets apparaissent dans l'onglet Tickets & Support : un tableau où View ouvre les coordonnées et la transcription complète, et une colonne Closed by enregistrant qui a fermé chacun d'eux — admin, cron ou customer. L'action Resolve ferme un ticket et peut remplacer la notification de fermeture par défaut pour ce ticket, en envoyant au client un message personnalisé. Une tâche quotidienne ferme automatiquement tout ticket resté ouvert au-delà de Auto-close open tickets after (days) (enregistré comme closed_by = cron). Le client peut aussi fermer ou annuler son propre ticket depuis le chat, mais seulement après une vérification de propriété — le numéro de ticket et l'e-mail doivent tous deux correspondre. L'agent classe en outre comme Bug report les conversations signalant un problème du site, pour que les problèmes parviennent à votre équipe sans passer par un ticket de support.

Exemple : un client écrit « J'ai besoin de parler à quelqu'un au sujet de ma commande ». L'agent demande son e-mail (et, si utile, le numéro de commande et un contact téléphone/WhatsApp), attribue un numéro de ticket tel que AIPS-000042 et envoie par e-mail la transcription complète au client, en copie cachée à votre adresse de support. Votre équipe le résout depuis l'onglet Tickets & Support — en notifiant éventuellement le client avec un message personnalisé — ou il se ferme automatiquement (closed_by = cron) une fois resté inactif le nombre de jours configuré.

Sécurité et anti-abus

Parce que chaque réponse IA coûte un véritable appel API, le widget est protégé par une défense en couches qui arrête sondes, scanners, tentatives d'injection et de prompt-injection et messages sans valeur avant qu'ils n'atteignent le modèle — à coût nul.

• Plafonds par IP — une limite de rafale de 15 requêtes / 60 s, 300 requêtes par jour, au plus 30 nouveaux chats par jour, et 60 tours par conversation.
• Disjoncteur global — un plafond à l'échelle de la boutique d'environ 5 000 appels IA par jour protège le budget contre une attaque distribuée.
• Jeton de preuve de widget — le widget prouve qu'il est passé par le vrai rituel d'entrée ; l'interrupteur Require widget token (Security & anti-abuse) l'impose et rejette les appels falsifiés vers l'endpoint.
• Journalisation complète — chaque événement bloqué est journalisé avec l'IP, le user-agent et le motif, pour que l'abus reste visible.
• Surveillance du provider — si le provider IA commence à échouer (plus de crédit, mauvaise clé), un watchdog vous envoie un e-mail pour qu'une panne silencieuse ne passe pas inaperçue.

Lire les conversations

Codingrow → AI Personal Shopper → Conversations liste chaque conversation, classée automatiquement comme Shopping, Support, Bug report, Possible spam ou Other, paginée et filtrable par type. L'action View ouvre le fil complet — chaque message du client et de l'assistant, y compris les fiches produit proposées à chaque tour — en lecture seule. Les conversations peuvent être supprimées individuellement ou en masse ; les conversations plus anciennes que la rétention configurée sont supprimées par une tâche quotidienne (les signalements de bugs sont exclus du nettoyage automatique).

Exemple : une conversation où le client décrit une erreur au moment du paiement est automatiquement classée comme Bug report, pour que votre équipe la voie dans la console sans que personne n'ait à envoyer d'e-mail.

Licence

La licence est émise pour un domaine et peut être une clé de module unique (AI Personal Shopper) ou une clé d'abonnement Codingrow (tous les modules). Sans licence valide, le widget de chat ne s'affiche pas. Votre licence couvre la version actuelle plus 1 an de mises à jour et support ; vous gardez l'usage des versions couvertes pour toujours et pouvez renouveler le support (−35%) pour passer aux versions plus récentes.