Enrichissement des items

Le hook actionKixellTagEnrichItems permet à un module tiers d'ajouter vos propres données aux items du dataLayer e-commerce, côté serveur, et ce par événement GA4. Vous injectez ainsi des informations métier (marge, stock, fournisseur, attributs personnalisés, score client…) qui ne sont pas disponibles côté navigateur — sans modifier Google Tag Manager.

Principe

À chaque construction d'un événement e-commerce, Kixell Tag exécute le hook et vous transmet les items concernés. Votre module modifie les items sur place en leur ajoutant des propriétés publiques. Kixell Tag enregistre automatiquement tout champ ajouté (non nul) pour qu'il se retrouve dans l'item GA4 final ; les champs laissés à null sont ignorés.

Le contrat du hook

Kixell Tag appelle :

Hook::exec('actionKixellTagEnrichItems', [
    'items'    => $items,   // KDataLayerItem[] — à enrichir (mutation sur place)
    'event'    => $event,   // string — événement GA4 (view_item, add_to_cart, purchase, ...)
    'id_shop'  => $id_shop, // int
    'id_cart'  => $id_cart, // int|null
    'id_order' => $id_order,// string|null — renseigné uniquement sur purchase
]);
Paramètre Type Description
items KDataLayerItem[] Les items à enrichir. Mutez-les sur place (propriétés publiques).
event string L'événement GA4 courant (voir ci-dessous). Permet d'enrichir sélectivement.
id_shop int Boutique courante (multiboutique).
id_cart int|null Panier courant le cas échéant.
id_order string|null Identifiant(s) de commande, uniquement sur purchase.

Événements transmis

view_item_list, select_item, view_item, add_to_cart, remove_from_cart, view_cart, begin_checkout, checkout_address, checkout_shipping, checkout_payment, purchase.

Comment les champs ajoutés remontent dans GA4

  • Ajoutez une propriété publique à chaque item (ex. $item->margin = 12.5;).
  • Tout champ non nul ajouté pendant le hook est auto-enregistré (dans dyn_fields) et se retrouve dans l'item GA4.
  • Un champ laissé à null est ignoré (nettoyé avant l'envoi).
  • Les items exposent déjà des identifiants utiles, par exemple item_id_product et item_id_variant.

Bonnes pratiques

  • Sortez tôt (return) pour les événements que vous ne traitez pas : le hook n'itère alors aucun item, le coût est nul.
  • Entourez votre code d'un try/catch : une exception ne doit jamais casser la construction du dataLayer.
  • L'enrichissement est serveur : il s'exécute indépendamment du navigateur, mais les données n'atteignent vos balises qu'au travers du dataLayer, dans le respect du consentement.

Un module de démonstration prêt à l'emploi est fourni — voir Module d'exemple (kixenrichdemo).

Aller plus loin