Skip to content

Area: Developers

Send events from the browser

Custom events from the browser travel in the events array of the page push the JavaScript SDK already makes, Releva.push(). Nothing else changes on the page.

Use it when the action happens in the browser: a product added to a comparison, a size guide opened, a video played. It is the easiest way to send events and it works for anonymous visitors. When the action happens in your backend, or you want to attach it to a customer by email or phone number, use Send custom events instead.

The push uses your shop’s public Access Token, the key that ships in your page source; never the Secret Key. Find it under Settings › Shop & Integration (Find your Access Token and Secret Key). The SDK sends it in the path, POST /api/v0/push/{accessToken}. The error messages are in Endpoints the Releva SDKs call: Authentication.

Add an events array to the context you already push:

Releva.push(accessToken, {
page: { /* as usual */ },
profile: { /* as usual */ },
cart: { /* as usual */ },
events: [
{
action: 'compareAdd',
tags: ['compare'],
products: [{ id: 'DEMO-1001' }],
timestamp: '2026-10-21T09:15:00Z',
custom: {
string: [{ key: 'source', values: ['product-page'] }],
numeric: [],
date: []
}
}
]
}, cb, errorCb, options);

When events is sent it must hold at least one event.

Field Type Required Notes
action string yes The event name. You can use it to build segments and trigger campaigns based on custom events.
products array of objects no id (required), variantId, price, currency, quantity. No custom on products.
custom object no string, numeric and date lists of { key, values }.
value, currency number, string no A monetary value for the event. Derived from the products when left out.
tags array of strings no Default: the page’s tags. You can use them to build segments and trigger campaigns.
timestamp string no ISO-8601 with seconds and a zone. Default: now.
locale string no Accepted, but replaced by page.locale.
orderId string no For events that belong to an order.
eventId string no A deduplication id passed to Meta and TikTok. Not stored.

Behaviour to know:

  • The event belongs to the visitor who pushes it, so there are no identifier fields: email on an event is rejected.
  • Events are stored only when the push carries a device id, which the SDK always sends. The stored event also has the page url, the visitor’s ip and the A/B groupAssignment.
  • Known issue: when your shop has a Google Tag Manager container connected, the SDK pushes every custom event to the dataLayer and reads all three custom lists without checking that they exist. Until this is fixed, send custom with all three lists, even empty ones, as in the example.

The raw call, without the SDK. It also records a page view, so do not run it in a loop:

curl -X POST "https://releva.ai/api/v0/push/$RELEVA_ACCESS_TOKEN" \
-H 'content-type: application/json' \
-d '{
"context": {
"deviceId": "demo-device-1001",
"cart": { "products": [] },
"events": [
{
"action": "compareAdd",
"products": [{ "id": "DEMO-1001" }],
"custom": { "string": [], "numeric": [], "date": [] }
}
]
}
}'

200 with the usual push answer: the product blocks, banners and stories for the page. The callback cb receives it. The event is usually readable within seconds under Data Platform › Events.

The SDK passes errors to errorCb. From the raw endpoint, POST /api/v0/push/{accessToken}:

Status When Message
400 Body without context context is missing from request body
400 email on an event The object 'events[0]' contains forbidden keys: 'email'.
400 custom on an event’s product The object 'events[0].products[0]' contains forbidden keys: 'custom'.
400 events: [] The 'events' field must contain at least 1 items.
400 Access token problems See Endpoints the Releva SDKs call: Authentication
402 Your shop is disabled, or value delivery is paused See Endpoints the Releva SDKs call: Authentication
  • Body size: 800 KB for a JSON body. The SDK sends a form body, which is limited to 2048 KB.
  • Rate limits: none.