Developer docs

Event tracking

Send searches, views, cart adds, purchases and returns from the browser or app, and tie them to the results that led to them.

View as Markdown

Events tell Solenya what shoppers did after seeing results. On indexes whose tracking_mechanism is event_based, view_item events build each shopper's preferences. Solenya also uses events to measure how results perform.

Endpoint#

Text
POST https://api.solenya.ai/v1/track/event

Unlike the rest of the API, this is a plain form post (application/x-www-form-urlencoded), not GraphQL. That lets the browser send it with navigator.sendBeacon, which still delivers when the shopper leaves the page, and it works from any website without extra setup.

Authentication#

The token goes in an access_token form field (RFC 6750 ยง2.2), not the Authorization header.

In browsers and apps, use a publishable key (API keys). It belongs to one index, so events land on that index. Any other token, such as a secret key used from your backend, must also send solenya_index_uuid.

Request fields#

FieldRequiredValue
access_tokenYesA publishable key, or another token
solenya_user_uuidYesThe shopper ID, the same one sent as Solenya-User-UUID on item queries
eventsYesA JSON-encoded list of one or more events
solenya_index_uuidWhen the token isn't tied to one indexThe index the events belong to. Ignored when the token is tied to one index.

Sending events#

From the browser:

JavaScript
const body = new URLSearchParams({
  access_token: SOLENYA_PUBLISHABLE_KEY,
  solenya_user_uuid: getShopperId(),
  events: JSON.stringify([
    { type: "view_item", item: { selector: "id", eq: "SKU-001" } },
  ]),
});
navigator.sendBeacon("https://api.solenya.ai/v1/track/event", body);

With curl, which also shows you the response:

curl -X POST https://api.solenya.ai/v1/track/event \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "access_token=<publishable_key>" \
  -d "solenya_user_uuid=<user_uuid>" \
  --data-urlencode 'events=[{"type":"view_item","item":{"selector":"id","eq":"SKU-001"}}]'

A valid request returns 202 Accepted:

JSON
{
  "success": true,
  "message": "Tracked 1 event(s).",
  "events_tracked": 1,
  "events_failed": 0
}

A request with an invalid event returns 422 with the reason, and none of its events are tracked. sendBeacon never shows you the response, and a browser fetch from your site can't read it either. While you build, send the same body with curl or from your server to see any 422.

Event types#

typeRecords
searchThe shopper ran a search
view_item_listA list of products was shown
view_itemThe shopper opened a product
click_elementThe shopper clicked something on the page, such as a filter
add_to_cartA product went into the cart
add_to_wishlistA product went onto the wishlist
begin_checkoutCheckout started
purchase_itemA product was bought
return_itemA bought unit was returned
view_experimentThe shopper saw a variant of an A/B test you run yourself

There is also an update_size_profile event for size-based ranking, which Solenya sets up with you. Ask Solenya before sending it.

Naming products#

Events about products carry an item with a selector (id or item_group_id) and exactly one of eq (one value) or in_ (a list of up to 50):

JSON
{ "selector": "id", "eq": "SKU-001" }
JSON
{ "selector": "id", "in_": ["SKU-001", "SKU-002"] }

In event JSON the list key is in_, with an underscore. GraphQL item queries spell it in. An item with its list under "in", without a selector, or with both eq and in_ fails validation.

JSON
{
  "type": "search",
  "search_term": "red running shoes",
  "image_count": 0,
  "filters": "size:9,colour:red",
  "result_count": 128
}

filters is your own summary of the filters applied.

view_item_list#

JSON
{
  "type": "view_item_list",
  "item": { "selector": "id", "in_": ["SKU-123", "SKU-456", "SKU-901"] },
  "list_id": "search-results",
  "list_name": "Search results",
  "query_uuid": "6f1c2b8e-4d3a-4e5f-9a7b-1c2d3e4f5a6b",
  "position": 1
}

in_ is in display order: the product at index i was shown at rank position + i. Send a page of more than 50 products as several view_item_list events in one request, each with its own position (1, 51, ...).

view_item#

JSON
{
  "type": "view_item",
  "item": { "selector": "id", "eq": "SKU-456" },
  "query_uuid": "6f1c2b8e-4d3a-4e5f-9a7b-1c2d3e4f5a6b",
  "position": 2
}

click_element#

JSON
{
  "type": "click_element",
  "element": "size_filter",
  "value": "9",
  "context": "facet_sidebar"
}

add_to_cart, add_to_wishlist, begin_checkout#

These record intent, not revenue. quantity defaults to 1.

JSON
{
  "type": "add_to_cart",
  "item": { "selector": "id", "eq": "SKU-901" },
  "quantity": 1,
  "cart_value": "89.99 USD"
}
JSON
{
  "type": "add_to_wishlist",
  "item": { "selector": "id", "eq": "SKU-901" },
  "wishlist_value": "89.99 USD"
}
JSON
{
  "type": "begin_checkout",
  "item": { "selector": "id", "in_": ["SKU-901", "SKU-123"] },
  "checkout_id": "CART-42",
  "checkout_value": "139.98 USD"
}

purchase_item#

price is an amount with at most two decimals, a space, and an upper-case currency code, such as "10.99 USD".

JSON
{
  "type": "purchase_item",
  "transaction_id": "TXN-001",
  "price": "99.99 USD",
  "item": { "selector": "item_group_id", "eq": "ADI_GN2901_BLANK" }
}

return_item#

Send one event per returned unit. item must name the unit with selector: "id" and eq. reason is your own reason code, and transaction_id links the return to the purchase when you know it.

JSON
{
  "type": "return_item",
  "item": { "selector": "id", "eq": "SKU-001" },
  "reason": "too_small",
  "transaction_id": "TXN-001"
}

view_experiment#

For an A/B test you run yourself, send this whenever a shopper sees a variant.

JSON
{
  "type": "view_experiment",
  "name": "checkout_v2",
  "variant": "treatment"
}

Field limits#

FieldLimit
item.in_Up to 50 ids
quantity (add_to_cart)1 to 1000
search_termUp to 10,000 characters
image_count0 to 10
filtersUp to 4096 characters
list_id, list_nameUp to 128 and 256 characters
element, value, contextUp to 128, 512 and 256 characters
reason, transaction_id (return_item), checkout_idUp to 128 characters
Prices (price, cart_value, wishlist_value, checkout_value)At most two decimals, then a space and an upper-case currency code

Attribution#

Every event type except return_item takes two optional fields that tie the event to the result page that led to it. Send them whenever the shopper got there from Solenya results: Solenya's click-through figures count only events that carry them.

FieldValue
query_uuidpage_info.query_uuid from the results. It names one page, not a search session: the next page has a different value.
positionThe product's 1-based rank in those results. On view_item_list, the rank of the first product in in_.

Device metadata (optional)#

Every event takes an optional device object:

JSON
{
  "type": "view_item",
  "item": { "selector": "id", "eq": "SKU-001" },
  "device": {
    "category": "mobile",
    "language": "en-US",
    "screen_resolution": "1280x2856",
    "operating_system": "Android",
    "operating_system_version": "14",
    "model": "Pixel 9 Pro",
    "brand": "Google",
    "browser": "Chrome",
    "browser_version": "136.0.7103.60"
  }
}

Check that events arrive#

users returns a shopper's latest events. It needs the user:read:* scope, which secret API keys have. A shopper appears only after an item query with their ID, or, on an event_based index, a view_item event.

query ShopperEvents {
  users(filter_term: { where: { record: { uuid: { eq: { value: "<user_uuid>" } } } } }) {
    page(page_size: 1) {
      rows {
        record {
          uuid
          events(limit: 20) {
            event_type
            timestamp
            item_selector
            item_eq
            query_uuid
            position
          }
        }
      }
    }
  }
}

The full reference, with every field, is at api.solenya.ai/v1/track/docs.