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

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

```
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](https://datatracker.ietf.org/doc/html/rfc6750#section-2.2)), not the `Authorization` header.

In browsers and apps, use a **publishable key** ([API keys](https://solenya.ai/docs/auth.md#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

| Field | Required | Value |
|-------|----------|-------|
| `access_token` | Yes | A publishable key, or another token |
| `solenya_user_uuid` | Yes | The [shopper ID](https://solenya.ai/docs/search.md#shopper-ids), the same one sent as `Solenya-User-UUID` on item queries |
| `events` | Yes | A JSON-encoded list of one or more events |
| `solenya_index_uuid` | When the token isn't tied to one index | The index the events belong to. Ignored when the token is tied to one index. |

## Sending events

From the browser:

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

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

| `type` | Records |
|--------|---------|
| `search` | The shopper ran a search |
| `view_item_list` | A list of products was shown |
| `view_item` | The shopper opened a product |
| `click_element` | The shopper clicked something on the page, such as a filter |
| `add_to_cart` | A product went into the cart |
| `add_to_wishlist` | A product went onto the wishlist |
| `begin_checkout` | Checkout started |
| `purchase_item` | A product was bought |
| `return_item` | A bought unit was returned |
| `view_experiment` | The 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.

### search

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

| Field | Limit |
|-------|-------|
| `item.in_` | Up to 50 ids |
| `quantity` (`add_to_cart`) | 1 to 1000 |
| `search_term` | Up to 10,000 characters |
| `image_count` | 0 to 10 |
| `filters` | Up to 4096 characters |
| `list_id`, `list_name` | Up to 128 and 256 characters |
| `element`, `value`, `context` | Up to 128, 512 and 256 characters |
| `reason`, `transaction_id` (`return_item`), `checkout_id` | Up 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.

| Field | Value |
|-------|-------|
| `query_uuid` | `page_info.query_uuid` from the results. It names one page, not a search session: the next page has a different value. |
| `position` | The 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.

```graphql
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](https://api.solenya.ai/v1/track/docs).
