The storefront kit (`/_public/kit.js`, loaded on every storefront) records searches, impressions, clicks and add-to-cart actions from search results, search suggestions and category pages. Your storefront code makes no tracking calls: it marks the lists in its HTML with `data-yns-*` attributes, and the kit reads them. The storefront template ships with these attributes; keep them when you restyle these pages.

## Lists

Put these attributes on the element that wraps the list:

| Attribute | Value |
|---|---|
| `data-yns-list` | `search` (results page), `autocomplete` (search suggestions) or `category` (category page) |
| `data-yns-query` | The search words. Not used on category pages |
| `data-yns-results` | The total number of results, not just the ones on this page |
| `data-yns-page` | The page number, starting at 1 |
| `data-yns-sort` | The sort order, for example `price-asc` |
| `data-yns-filters` | Active filters as JSON: `{"brand":["acme"],"priceMax":["100"]}` |
| `data-yns-list-key` | On a category page: the category id |

The kit records a search when the list appears, and again whenever the query, results count, filters, sort or page change. A results page with no products still counts as a search: render the list element with `data-yns-results="0"`.

## Products

Put these on each product in the list, usually the card's link:

| Attribute | Value |
|---|---|
| `data-yns-item` | The product id |
| `data-yns-position` | The product's place in the list, starting at 1 and counting across pages |

A product counts as seen once at least half of it is on screen. A click on it is recorded straight away.

## Add to cart

Put these on add-to-cart buttons, in a list (a quick-add button on a card) and on the product page:

| Attribute | Value |
|---|---|
| `data-yns-add-to-cart` | The product id |
| `data-yns-variant` | The variant id, when one is chosen |

On the product page, the add to cart is credited to the list the shopper clicked the product in.

## Examples

Search results page (Server Component):

```tsx
<div
	data-yns-list="search"
	data-yns-query={query}
	data-yns-results={result.meta.count}
	data-yns-page={currentPage}
	data-yns-sort={sort}
>
	{result.data.map((product, index) => (
		<a
			key={product.id}
			href={`/product/${product.slug}`}
			data-yns-item={product.id}
			data-yns-position={(currentPage - 1) * PAGE_SIZE + index + 1}
		>
			{product.name}
		</a>
	))}
</div>
```

Search suggestions: mark the list only once the suggestions for the typed words are on screen, so a half-typed query isn't recorded as a search:

```tsx
<div
	role="listbox"
	{...(loaded && query
		? { "data-yns-list": "autocomplete", "data-yns-query": query, "data-yns-results": suggestions.length }
		: {})}
>
	{suggestions.map((item, index) => (
		<button key={item.id} type="button" data-yns-item={item.id} data-yns-position={index + 1}>
			{item.name}
		</button>
	))}
</div>
```

Category page:

```tsx
<div data-yns-list="category" data-yns-list-key={category.id} data-yns-results={count} data-yns-page={currentPage}>
	{/* product cards with data-yns-item and data-yns-position */}
</div>
```

## Sessions and consent

The kit links searches to orders with two first-party cookies: `yns_sid` (the visit, 30 minutes after the last action) and `yns_did` (the device, 1 year). Checkout copies them onto the order. When the store shows the cookie banner, they are set only after the shopper accepts analytics. Do Not Track, Global Privacy Control or a declined banner stop tracking entirely.