docs

SCAYLE Analytics events

The route refuses any event_name that the contract in @scayle/storefront-api doesn't define. For how the events reach the Storefront API, consent, and setup, see SCAYLE Analytics.

Event overview

EventFires on
view_pageEvery change of the page URL
view_product_listA list with products renders or first becomes visible
view_product_tileA product tile first becomes visible
select_productA product tile click, and the plus button of a gift promotion reward
view_product_detailThe product detail page
apply_filterA single filter value added or removed
searchThe outcome of a submitted search
view_search_suggestionA suggestion rendered in the search dropdown
select_search_suggestionA suggestion click, or Enter on the active suggestion
view_promotionA deal banner or the layout ribbon first becomes visible
select_promotionA click on a deal that carries a link
add_to_basketA successful add, a quantity increase, and the new variant of a size change
remove_from_basketA confirmed removal, a quantity decrease, and the old variant of a size change
view_basketThe basket page mounts
add_to_wishlistA confirmed wishlist add

Each event below follows the same order: when it fires, its own properties, and an example. The shared context is not repeated in the examples. The values are illustrative, and the price and discount amounts are in cents.

Shared context

Every event also carries the page and session context the dispatcher adds and the customer fields the server adds. Who sets which field lists them.

Product properties

Every product event flattens the product onto the event. The product carries these properties, and ? marks an optional one:

  • product_id, price, and brand_id?, variant_id?, discount?, campaign_id?, promotion_ids?.
  • The surface fields product_list_type?, product_list_id?, position?, and total?. See product_list_type, position, and total.

Only view_basket carries a products array instead of flattened fields.

Page view events

view_page

Trigger: Every change of the page URL, query string included: regular visits, pagination, filters and sorting on a listing, the registration view of the sign-in page, and browser back and forward. The dispatcher fires it itself. A change of only the hash or of the imageView parameter fires nothing, and neither does a reload of deferred data that keeps the URL.

view_page is the navigation marker. Every event reports the page of the view_page before the current one as previous_page_path and previous_page_type. The Tracking page_view fires on the same rule, a change of the page path or query except a change of the imageView key alone.

Properties: None.

Example:

Product events

view_product_list

Trigger: Once per list with products: grid mount, category switch, a new search term, first visibility of a slider or of the single product spotlight, first visibility of a gift promotion's reward panel, and every open of the add-to-basket confirmation.

Properties: Type, id, and total only, no products.

Example:

view_product_tile

Trigger: Once per product tile, with its position across all pages and the list total. Each tile fires once, when half of the card is on screen, on grids, sliders, and the wishlist alike. The single product spotlight waits for 30% of itself.

Properties: The product, see Product properties.

Example:

select_product

Trigger: A product tile click, and the plus button of a gift promotion reward.

Properties: The product, see Product properties.

Example:

view_product_detail

Trigger: The product detail page.

Properties: The product, see Product properties. The main product reports product_list_type: null.

Example:

Filter events

apply_filter

Trigger: A single filter value added or removed, once the filter reload succeeded. A reset reports one remove per cleared value, with active_filters and result_count taken after the whole reset. Sorting is not reported, and neither is a filter a page opens with, which has no add.

Properties:

  • filter_slug: The machine-readable slug of the filter, for example size.
  • filter_value: The selected value, as a string.
  • filter_action: add or remove.
  • product_list_type and product_list_id?: The grid the filter was applied on. product_list_id is a category id or a search term.
  • active_filters: The number of filter options active after the change.
  • result_count: The number of products after the change.

Example:

Search events

Trigger: The outcome of a submitted search: the search results page once on mount, and a resolved category, product, or navigation item before the search field navigates there.

A search the server resolves itself goes unreported. When the browser requests a search URL directly, for example from a bookmark, a link on another site, or a typed URL, and the term resolves to a category or product page, the server redirects there. Neither the search field nor the search results page runs, so neither fires the event. A term that doesn't resolve renders the search results page, which fires search on mount.

Properties:

  • search_term: The raw query entered.
  • search_destination_type?: term, category, product, or navigation_item.
  • search_destination_url?: The path the search resolved to, including the query string.
  • search_destination_id?: The id of the destination, a number. Only for category, product, and navigation_item.
  • search_destination_filter_groups?: The filter groups of the destination. Only for category.
  • search_result_count?: The number of results on the search results page. Only when the search resolved to a term.

Example:

view_search_suggestion

Trigger: Once per suggestion when the search dropdown renders it. "Show all results" is not a suggestion.

Properties:

  • position and total: The 1-based position in the dropdown and the number of suggestions rendered.
  • search_term: The query typed when the dropdown rendered.
  • suggestion_type: category, product, or navigation_item.
  • suggestion_id and suggestion_url: The id and the path of the suggested object, the path including the query string.
  • suggestion_filter_groups?: The filter groups of the suggestion. Only for category.

Example:

select_search_suggestion

Trigger: A suggestion click, or Enter on the active suggestion. "Show all results" is excluded.

Properties: Same properties as view_search_suggestion.

Example:

Promotion events

view_promotion

Trigger: A deal banner or the layout ribbon first becoming visible, once per deal until the page path changes. Pagination and filter changes don't report it again.

Properties:

  • promotion_id: The id of the deal.
  • promotion_type: promotion or campaign.
  • component_type: ribbon, pdp_banner, basket_banner, or deals_overview_banner.
  • position and total: The 1-based position of the component within its set, for example the deals overview, and the number of components in that set.

Example:

select_promotion

Trigger: A click on a deal that carries a link.

Properties: Same properties as view_promotion.

Example:

Basket events

add_to_basket

Trigger: A successful add from the product detail page or the gift selection pop-up, a quantity increase on the basket page, and the new variant of a size change.

Properties: The product, see Product properties, with quantity as the delta. The contract marks it optional, and the Storefront Application always sends it. See quantity.

Example:

remove_from_basket

Trigger: A confirmed removal on the basket page, a quantity decrease, and the old variant after a size change.

Properties: The product, see Product properties, with quantity as the delta. See quantity.

Example:

view_basket

Trigger: Once when the basket page mounts, with the basket totals and every basket item, up to 200 entries or the 32 KiB body cap.

Properties:

  • total_price, total_sale_discount, total_campaign_discount, and total_promotions_discount: The basket totals.
  • products: The basket items, each with its quantity.

Example:

Wishlist events

add_to_wishlist

Trigger: A confirmed wishlist add, from any surface.

Properties: The product, see Product properties, with product_list_type required and null allowed.

Example:

Property reference

quantity

On add_to_basket and remove_from_basket, quantity is the delta of the interaction, not the resulting basket item quantity. Raising a basket item from two to three units reports 1, and a full removal reports the whole basket item.

If the Storefront API caps an add at the available stock and the page had already loaded the basket, the event reports the units the basket gained, read from the reloaded basket. Without a loaded basket to compare against, it reports the requested quantity.

On view_basket, quantity is the basket item quantity. View and select events carry no quantity.

product_list_type, position, and total

product_list_type is a closed union in the contract, AnalyticsProductListType in @scayle/storefront-api:

ValueSurfaceproduct_list_id carries
categoryProduct listing page gridThe category id
brandBrand product listingThe brand id
search_resultsSearch results gridThe search term
product_sliderAny product slider, including the add-to-basket confirmation's recommendations and the single product spotlightThe slider id, for example trending, or nothing for a slider without an id
gift_selectionGift selection of a promotionThe promotion id
basketBasket pagenull on add_to_basket and remove_from_basket, omitted on add_to_wishlist from the basket card
wishlistWishlist pageNothing, omitted

Reporting a surface you add explains how a new surface maps to one of these values. The product detail page's main product reports product_list_type: null, since the union has no product detail surface. brand is part of the contract for a brand listing you add.

position is 1-based and counts across the whole list, including products on other pages. total is the full result count of the list across every page, so a listing of 4 pages of 24 products reports 96. The GA4 index stays page-relative, so the two can differ.

page_type

page_type comes from the Inertia page component the page renders, through the same page type map and the same resolveTrackingPageType function Tracking uses. In both pipelines the shop's start page reports homepage, and every account page reports account.

Page componentpage_type
The page at the shop's home routehomepage
ProductListingproduct_listing
ProductDetailproduct_detail
Searchsearch
Wishlistwishlist
Basketbasket
Checkoutcheckout
OrderSuccessorder_success
SignInsign_in
AccountProfile, AccountOrders, AccountOrderDetail, AccountSubscriptionsaccount
CmsPagecms_page
NotFound, SubscriptionCancellationnot_found, subscription_cancellation, passed through as free-form values

The Error page sends no events. It renders without shared props, so it has no storefront prop, and the dispatcher drops every event there, view_page included.

TypeScript requires a map entry in src/shared/types/Tracking.ts for every page component registered in Components in src/shared/types/global.d.ts, so the dispatcher never sends an empty page_type.

device_type is ios, android, or desktop, classified from navigator.userAgent with the same classifier Tracking uses.