Pour que votre Assistant Shopping fonctionne correctement, de la recommandation produit jusqu'à l'ajout au panier et le suivi des ventes, un même identifiant produit doit circuler de manière cohérente entre quatre points d'intégration distincts. Toute divergence entre ces identifiants entraîne des dysfonctionnements : fiche produit introuvable, ajout au panier en échec ou attribution de conversion incorrecte.

Cet article centralise les contraintes d'unification à respecter impérativement lors de votre intégration.

Principe : un identifiant, quatre points d'intégration

iAdvize utilise l'identifiant produit comme clé de jointure entre ses différents composants. La valeur définie dans le catalogue produit constitue la référence absolue : elle doit être reproduite à l'identique dans les trois autres points d'intégration.

Les quatre points concernés sont :

Le catalogue produit : champ id
La donnée personnalisée product_id : envoyée via le tag GTM ou le tag principal iAdvize sur la page produit
Le tag de transaction : identifiants produits transmis lors de la commande (via products[].id en intégration manuelle, ou via le dataLayer en GTM)
L'Add-to-Cart : identifiant transmis à l'API native de votre plateforme e-commerce

⚠ Si l'identifiant utilisé dans le catalogue ne correspond pas à celui attendu par votre plateforme e-commerce pour l'ajout au panier, la fonctionnalité Add-to-Cart sera inopérante. Vérifiez ce point en priorité lors de votre intégration.

1. Le catalogue produit : définir la valeur de référence

Rôle du champ `id`

Le champ id de votre catalogue produit est l'identifiant de référence. C'est la valeur que le système iAdvize utilise pour retrouver et afficher la fiche produit dans l'Assistant.

Il doit être unique par produit (ou par variant, selon votre logique métier).
Il est défini lors de l'indexation de votre flux (CSV, XML Google Shopping, Lengow, SmartFeeds, Channable…).
Une fois attribué à un produit dans le catalogue, cet identifiant ne peut plus être réutilisé pour un autre produit.

NB Dans un fichier CSV, ce champ est intitulé id. Dans un flux XML Google Shopping, il correspond à la balise <g:id>. Quelle que soit la méthode d'import, la valeur doit être identique à celle transmise dans les autres points d'intégration.

Cas particulier : gestion des variants

Si votre catalogue est structuré au niveau des variants (taille, couleur, format, etc.), l'id doit correspondre à l'identifiant du variant, et non à celui du produit parent.

Tips : sur Shopify, l'identifiant à utiliser dans le catalogue est le Variant ID Shopify (et non le Product ID parent). C'est le seul identifiant que l'API Shopify accepte pour l'ajout au panier via /cart/add.js. Cette contrainte s'applique donc à l'ensemble des quatre points d'intégration décrits dans cet article.

2. La donnée personnalisée `product_id` : signaler le produit consulté

Sur chaque page produit de votre site, le tag iAdvize doit recevoir l'identifiant du produit actuellement consulté par le visiteur. Cette information est transmise via les données personnalisées (custom data).

Le système utilise cette valeur pour faire correspondre le produit consulté avec la fiche correspondante dans le catalogue. Si les valeurs ne correspondent pas, l'Assistant ne peut pas accéder aux informations du produit et la notification d'engagement ne peut pas être personnalisée.

Le mode de transmission dépend de votre méthode d'intégration :

Intégration manuelle : la donnée personnalisée product_id est incluse directement dans le tag principal iAdvize.
→ Intégrer le tag principal manuellement
Intégration via GTM : la donnée personnalisée product_id est transmise via le tag dédié "iAdvize - Custom Data tag".
→ Installer iAdvize via Google Tag Manager

NB La clé utilisée par défaut est product_id. Elle doit correspondre à la configuration renseignée dans votre source de connaissance iAdvize (champ "Identification produit" lors de la création de la source). Si vous utilisez une clé différente, assurez-vous que la configuration de votre source de connaissance est alignée en conséquence.

3. Le tag de transaction : mesurer les conversions

Rôle dans l'attribution des ventes

Pour que iAdvize puisse attribuer les ventes générées après une conversation à l'Assistant et identifier quels produits ont été achetés, les identifiants produits transmis lors de la transaction doivent correspondre à ceux indexés dans le catalogue.

Le mode de transmission dépend de votre méthode d'intégration :

Intégration manuelle : les identifiants produits sont transmis directement dans le tag de transaction, via le tableau products[].id de la méthode iAdvize.recordTransaction().
→ Intégrer le tag de transaction manuellement
Intégration via GTM : le template "iAdvize - Transaction tag" transmet uniquement l'identifiant et le montant de la commande. Les identifiants produits sont capturés automatiquement par le tag principal iAdvize, qui observe le dataLayer et extrait les produits de l'événement GA4 purchase (champ ecommerce.items[].item_id). Aucune configuration supplémentaire n'est requise.
→ Installer iAdvize via Google Tag Manager

⚠ Quelle que soit la méthode d'intégration, si les identifiants produits transmis lors de la transaction ne correspondent pas à ceux indexés dans le catalogue iAdvize, les ventes ne pourront pas être attribuées aux produits recommandés par l'Assistant. Le rapport des ventes iAdvize sera incomplet.

4. L'Add-to-Cart : transmettre l'identifiant à votre plateforme

Lorsqu'un visiteur clique sur le bouton "Ajouter au panier" dans une conversation avec l'Assistant, iAdvize déclenche un callback JavaScript sur votre site. Ce callback reçoit le productId du produit recommandé — soit la valeur du champ id définie dans votre catalogue produit.

C'est votre implémentation du callback qui se charge de transmettre cet identifiant à l'API d'ajout au panier de votre plateforme e-commerce.
→ Guide d'installation de l'Add-To-Cart

L'identifiant transmis par iAdvize via le productId est celui indexé dans le catalogue. Votre plateforme e-commerce doit être en mesure de l'accepter tel quel pour l'ajout au panier.

⚠ Si votre plateforme e-commerce n'accepte pas l'identifiant défini dans votre catalogue (par exemple parce que votre catalogue utilise un Product ID parent alors que la plateforme attend un Variant ID), l'ajout au panier échouera systématiquement. Vous devez vous assurer que l'identifiant indexé dans le catalogue est bien celui attendu par votre API d'ajout au panier.