Event Cookbook

Purpose

Use this page as the implementation contract for sending Selwise events across all three platforms:

CDN (window.Selwise)
npm (widget instance)
React Native (sdk instance)

Currency rule: replace SITE_CURRENCY with your site's ISO-4217 uppercase currency code (for example EUR, USD, TRY).

Sender Adapters

Platform	Direct Event Sender	Structured Sender
CDN	`window.Selwise.track(name, args)`	`window.Selwise.pushDataLayer(payload)`
npm	`widget.track(name, args)`	`widget.pushDataLayer(payload)`
React Native	`sdk.track(name, args)`	`sdk.pushDataLayer(payload)` (local snapshot, not network sender)

RN note: use await sdk.flush() to force immediate network delivery.

Canonical `events/batch` Request Contract

POST /api/v1/public/sites/:siteKey/events/batch

{
  "sessionId": "sid_123",
  "visitorId": "vid_123",
  "siteUserId": "user_42",
  "journeyId": "journey_123",
  "pageUrl": "/products/sku-123",
  "referrer": "/home",
  "events": [
    {
      "eventId": "evt_123",
      "eventSchemaVersion": 1,
      "eventTs": 1730000000000,
      "name": "product_view",
      "entityType": "product",
      "entityId": "sku-123",
      "metadata": {
        "productItemCode": "sku-123"
      }
    }
  ]
}

Field Definitions

Field	Required	Description
`eventId`	Yes	Unique client event id.
`eventSchemaVersion`	Yes	Event schema version (current runtime: `1`).
`eventTs`	Yes	Event timestamp (epoch ms).
`name`	Yes	Canonical event name.
`entityType`	Yes	Event entity domain (`product`, `basket`, etc.).
`entityId`	No	Optional entity id.
`metadata`	No	Event-specific metadata object.
`sessionId`	Yes	Active session id.
`visitorId`	Yes	Stable visitor id.
`siteUserId`	No	Known identified user id.
`journeyId`	No	Active journey id.
`pageUrl`	No	Screen/page path.
`referrer`	No	Previous screen/page path.

Event Family Contracts

Events:

page_view
virtual_page_view
widget_view
category_view
scroll

Minimum payload signals:

page.path or page.type for page events
custom.params.widgetId for widget_view

CDN:

window.Selwise?.pushDataLayer?.({
  event: 'page_view',
  page: { type: 'home', path: '/', url: location.href, title: document.title },
});

npm:

widget.pushDataLayer({
  event: 'virtual_page_view',
  page: { path: '/category/shoes', url: location.href, title: document.title },
});

RN:

sdk.track('page_view', {
  entityType: 'page',
  entityId: '/category/shoes',
  metadata: { pageType: 'category' },
});
await sdk.flush();

B) Product and Merchandising

Events:

product_view
product_click
product_impression
product_dwell_time
popular_product_click
wishlist

Minimum payload signals:

product.sku or metadata.productItemCode

CDN:

window.Selwise?.track?.('product_view', {
  entityType: 'product',
  entityId: 'SKU-123',
  metadata: { productItemCode: 'SKU-123', title: 'Runner Pro', price: 149.9 },
});

npm:

widget.pushDataLayer({
  event: 'product_impression',
  product: { sku: 'SKU-123', id: 'SKU-123', title: 'Runner Pro' },
});

RN:

sdk.track('product_click', {
  entityType: 'product',
  entityId: 'SKU-123',
  metadata: { productItemCode: 'SKU-123', source: 'recommendation' },
});
await sdk.flush();

C) Cart and Basket

Events:

add_to_cart
remove_from_cart
update_cart
cart_abandon
cart_restore

Minimum payload signals:

basket.products[] for item-change events
basket.id for abandon/restore

CDN:

window.Selwise?.pushDataLayer?.({
  event: 'add_to_cart',
  basket: {
    id: 'cart_001',
    currency: 'SITE_CURRENCY',
    total: 149.9,
    products: [{ sku: 'SKU-123', quantity: 1, price: 149.9 }],
  },
});

npm:

widget.pushDataLayer({
  event: 'cart_restore',
  basket: { id: 'cart_001', total: 149.9, currency: 'SITE_CURRENCY' },
});

RN:

sdk.track('add_to_cart', {
  entityType: 'basket',
  entityId: 'cart_001',
  metadata: {
    basketId: 'cart_001',
    items: [{ productItemCode: 'SKU-123', quantity: 1, price: 149.9 }],
  },
});
await sdk.flush();

D) Checkout and Purchase

Events:

checkout_begin
checkout_progress
checkout_option
purchase

Minimum payload signals:

checkout.step for checkout events
order.id and order.total for purchase

CDN:

window.Selwise?.pushDataLayer?.({
  event: 'checkout_option',
  checkout: { step: 2, option: { type: 'shipping', value: 'express' }, basketId: 'cart_001' },
});

npm:

widget.pushDataLayer({
  event: 'purchase',
  order: {
    id: 'ORDER-1001',
    total: 299.8,
    currency: 'SITE_CURRENCY',
    products: [{ sku: 'SKU-123', quantity: 2, price: 149.9 }],
  },
});

RN:

sdk.track('checkout_begin', {
  entityType: 'checkout',
  entityId: 'cart_001',
  metadata: { step: 1, basketId: 'cart_001', total: 299.8, currency: 'SITE_CURRENCY' },
});
await sdk.flush();

E) User and Identity

Events:

identify
user_signup
user_login
user_logout
user_update

Minimum payload signals:

user.id or external user id

CDN:

await window.Selwise?.identify?.('user_42', { email: 'user@example.com' });
window.Selwise?.pushDataLayer?.({ event: 'user_login', user: { id: 'user_42' } });

npm:

await widget.identify('user_42', { email: 'user@example.com' });
widget.pushDataLayer({ event: 'user_update', user: { id: 'user_42', loyaltyTier: 'gold' } });

RN:

await sdk.identify('user_42', { email: 'user@example.com' });
sdk.track('user_login', { entityType: 'user', entityId: 'user_42' });
await sdk.flush();

F) Search

Events:

search_instant_open
search_query
search_filter
search_sort
search_page
search_results
search_zero_results
search_close
category_filter
recent_search_click
popular_search_click
popular_category_click

Minimum payload signals:

search.query for query/click events
search.results for result volume events

CDN:

window.Selwise?.pushDataLayer?.({
  event: 'search_query',
  search: { query: 'running shoes', results: 120 },
});

npm:

widget.pushDataLayer({
  event: 'search_filter',
  search: { query: 'running shoes', filters: [{ name: 'brand', value: 'Nike' }] },
});

RN:

sdk.track('search_query', {
  entityType: 'search',
  metadata: { query: 'running shoes', results: 120 },
});
await sdk.flush();

Events:

impression
click
close
view
hover
slider_navigate
slider_swipe
widget_impression
script_injected
script_error

Minimum payload signals:

Event-specific custom.params keys (widgetId, direction, scriptId, etc.)

CDN:

window.Selwise?.pushDataLayer?.({
  event: 'widget_impression',
  custom: { params: { widgetId: 'widget_home_1' } },
});

npm:

widget.pushDataLayer({
  event: 'script_error',
  custom: { params: { scriptId: 'custom_js_1', message: 'ReferenceError: x is not defined' } },
});

RN:

sdk.track('click', {
  entityType: 'ui',
  metadata: { target: 'home_hero_cta', placement: 'home_hero' },
});
await sdk.flush();

H) Custom Business Event

Event:

custom_event

Minimum payload signals:

custom.name (or equivalent metadata name)

CDN:

window.Selwise?.pushDataLayer?.({
  event: 'custom_event',
  custom: { name: 'newsletter_signup', params: { source: 'footer_form' } },
});

npm:

widget.pushDataLayer({
  event: 'custom_event',
  custom: { name: 'ab_test_exposure', params: { experimentId: 'exp_1', variantId: 'B' } },
});

RN:

sdk.track('custom_event', {
  entityType: 'custom',
  metadata: { name: 'newsletter_signup', source: 'mobile_modal' },
});
await sdk.flush();

`trackOrder` Contract

Endpoint

POST /api/v1/public/sites/:siteKey/orders

Field Table

Field	Required	Description
`orderId`	Yes	Unique order identifier (idempotency anchor).
`currency`	No	ISO currency code.
`total`	No	Order total amount.
`subtotal`	No	Amount before tax/shipping/discount.
`discountTotal`	No	Total discount amount.
`shippingTotal`	No	Shipping amount.
`taxTotal`	No	Tax amount.
`status`	No	Order status string.
`placedAt`	No	Timestamp string.
`visitorId`	No	Override visitor id.
`siteUserId`	No	Override identified user id.
`metadata`	No	Custom metadata object.
`items[]`	No	Order line items.
`items[].productItemCode`	Recommended	Stable product item code for attribution.
`items[].quantity`	Recommended	Quantity purchased.
`items[].unitPrice`	Recommended	Unit-level price.

Web Example

await widget.trackOrder({
  orderId: 'ORDER-2001',
  currency: 'SITE_CURRENCY',
  total: 249.9,
  items: [{ productItemCode: 'SKU-123', quantity: 1, unitPrice: 249.9 }],
});

RN Example

await sdk.trackOrder({
  orderId: 'ORDER-2001',
  currency: 'SITE_CURRENCY',
  total: 249.9,
  items: [{ productItemCode: 'SKU-123', quantity: 1, unitPrice: 249.9 }],
});

Idempotency Guidance

Keep orderId globally unique per completed order.
Retry only transient failures (429, 5xx).
Do not generate a new orderId for retries.

Validation Checklist

Event names are canonical.
Family-required minimum fields exist.
Product-related payloads include stable product identifiers.
trackOrder uses stable orderId.
RN network sending uses track + flush (not only pushDataLayer).

Event Cookbook

Purpose

Sender Adapters

Canonical `events/batch` Request Contract

Field Definitions

Event Family Contracts

A) Page and Navigation

B) Product and Merchandising

C) Cart and Basket

D) Checkout and Purchase

E) User and Identity

F) Search

G) Widget, UI, and Script Engagement

H) Custom Business Event

`trackOrder` Contract

Endpoint

Field Table

Web Example

RN Example

Idempotency Guidance

Validation Checklist

Purpose

Sender Adapters

Canonical events/batch Request Contract

Field Definitions

Event Family Contracts

A) Page and Navigation

B) Product and Merchandising

C) Cart and Basket

D) Checkout and Purchase

E) User and Identity

F) Search

G) Widget, UI, and Script Engagement

H) Custom Business Event

trackOrder Contract

Endpoint

Field Table

Web Example

RN Example

Idempotency Guidance

Validation Checklist

Related Docs

Canonical `events/batch` Request Contract

`trackOrder` Contract