Items enrichment

The actionKixellTagEnrichItems hook lets a third-party module add your own data to the items of the e-commerce dataLayer, server-side, and per GA4 event. You can thus inject business information (margin, stock, supplier, custom attributes, customer score…) that is not available on the browser side — without modifying Google Tag Manager.

Principle

On each build of an e-commerce event, Kixell Tag runs the hook and passes you the items concerned. Your module mutates the items in place by adding public properties to them. Kixell Tag automatically records any added (non-null) field so that it ends up in the final GA4 item; fields left at null are ignored.

The hook contract

Kixell Tag calls:

Hook::exec('actionKixellTagEnrichItems', [
    'items'    => $items,   // KDataLayerItem[] — to enrich (mutate in place)
    'event'    => $event,   // string — GA4 event (view_item, add_to_cart, purchase, ...)
    'id_shop'  => $id_shop, // int
    'id_cart'  => $id_cart, // int|null
    'id_order' => $id_order,// string|null — set only on purchase
]);
Parameter Type Description
items KDataLayerItem[] The items to enrich. Mutate them in place (public properties).
event string The current GA4 event (see below). Lets you enrich selectively.
id_shop int Current store (multistore).
id_cart int|null Current cart where applicable.
id_order string|null Order identifier(s), only on purchase.

Events passed

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

How added fields reach GA4

  • Add a public property to each item (e.g. $item->margin = 12.5;).
  • Any non-null field added during the hook is auto-recorded (in dyn_fields) and ends up in the GA4 item.
  • A field left at null is ignored (cleaned before sending).
  • Items already expose useful identifiers, for example item_id_product and item_id_variant.

Best practices

  • Return early (return) for events you do not handle: the hook then iterates no item, the cost is zero.
  • Wrap your code in a try/catch: an exception must never break the dataLayer build.
  • Enrichment is server-side: it runs independently of the browser, but the data only reaches your tags through the dataLayer, while respecting consent.

A ready-to-use demonstration module is provided — see Example module (kixenrichdemo).

Going further