Click Tracking
Markup a storefront needs so Malachyte can measure clicks on recommendations
To measure clickthrough rate, every product result set Malachyte returns informs which component and which product were clicked. This applies across recommendations, search results, and product listing page (PLP) call surfaces, with the exception of autocomplete results. This page is for developers building or updating a storefront that shows Malachyte results.
A product tile is the card that shows a single product in a Malachyte result (a recommendation, search result, or PLP item). It usually contains the product image, title, and price, all inside one link to the product page.
Requirements
1. Add a name to Each Tile's Link
Each product tile's link (<a>) needs this name attribute:
name="ml-rec:{component_id}:{product_id}:{category_id}:{strategy_name}"| Part | What to use |
|---|---|
{component_id} | The ID of the Malachyte component that returns the products (recommendation, search, or PLP). |
{product_id} | The product's ID. |
{category_id} | The collection ID of the listing page the recommendations are on. Only used on product listing pages. |
{strategy_name} | The strategy name. Always included. |
Everywhere other than a product listing page (for example, product pages, search, or the homepage), leave {category_id} empty but keep the colons:
name="ml-rec:{component_id}:{product_id}::{strategy_name}"Use name, not id
Themes often use id on product links for styling and scripts, and id must be unique on the page. name is rarely used on product links, so it's safe to add.
2. Keep the Product href
Leave the product link's href (for example, /products/{handle}) on that same <a>. It's needed for navigation and is used as a backup to identify the product.
3. Make the Whole Tile Click as the Link
If a shopper clicks the image or title inside a tile, the click must be reported as the link itself. Set pointer-events: none on the elements inside the link (image, title, price, and so on), and keep pointer-events: auto on the link.
Leave genuinely interactive elements inside the tile, like a quick-add button, clickable.
How to Check It Works
- Open the storefront, then open DevTools → Network and turn on Preserve log.
- Click a product's image in a Malachyte recommendation, search result, or PLP tile (not just the text).
- Find the pixel request and check that:
event_nameisclickeddata.element.nameis theml-rec:…valuedata.element.hrefis the product URL
If data.element.name is empty, or the request shows an image or heading instead of the link, the click isn't reaching the link yet.