Search Documentation

Search for a documentation page...

Search Analytics

Mark your storefront's search results, suggestions and category pages with data-yns attributes so the platform can record searches, clicks and the orders that follow.

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:

AttributeValue
data-yns-listsearch (results page), autocomplete (search suggestions) or category (category page)
data-yns-queryThe search words. Not used on category pages
data-yns-resultsThe total number of results, not just the ones on this page
data-yns-pageThe page number, starting at 1
data-yns-sortThe sort order, for example price-asc
data-yns-filtersActive filters as JSON: {"brand":["acme"],"priceMax":["100"]}
data-yns-list-keyOn 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:

AttributeValue
data-yns-itemThe product id
data-yns-positionThe 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:

AttributeValue
data-yns-add-to-cartThe product id
data-yns-variantThe 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):

<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:

<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:

<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>

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.