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.
When to use it
Section titled “When to use it”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.
Authentication
Section titled “Authentication”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.
Request
Section titled “Request”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:
emailon 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’sipand the A/BgroupAssignment. - Known issue: when your shop has a Google Tag Manager container connected, the SDK pushes every custom event to the
dataLayerand reads all threecustomlists without checking that they exist. Until this is fixed, sendcustomwith 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": [] } } ] } }'Response
Section titled “Response”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.
Errors
Section titled “Errors”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 |
Limits
Section titled “Limits”- Body size: 800 KB for a JSON body. The SDK sends a form body, which is limited to 2048 KB.
- Rate limits: none.