Skip to content

Area: Developers

POST

Report a banner, story or page engagement event

Path
/push/events/{accessToken}
Auth
Access token · in the URL path
POST
/push/events/{accessToken}
curl --request POST \
--url https://releva.ai/api/v0/push/events/YOUR_ACCESS_TOKEN \
--header 'Content-Type: application/json' \
--data '{ "deviceId": "demo-device-pb-1", "sessionId": "demo-session-pb-1", "action": "bannerClick", "attributions": { "bannerBlockId": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b", "bannerId": "1" }, "page": { "url": "https://demo-store.example.com/" } }'

Records one storefront event per request: a banner click or close, a story event, or page engagement (scroll depth and active time). The JavaScript SDK and the mobile SDKs call it for the blocks they draw; call it yourself only for banners and stories you render from the push response. Send the access token in the path, or as authorization: Bearer <accessToken> on POST /push/events.

bannerClick and bannerClose with attributions.bannerId set the banner’s Show until click memory for the device; bannerClick also attributes later cart adds and orders to the banner block, and is de-duplicated with the click Releva detects when the visitor lands on an rlv_bid link. storySlideClick and storyClose with attributions.storyId mark the story as seen for the device, and storySlideClick also attributes later cart adds and orders to the story. A pageEngagement event with activeTimeMs under 1000, or on a page that is not a Releva page, answers 202 and is not stored.

The JavaScript SDK sends the same body as a form field formPayload, like the page push.

accessToken
required
string format: uuid

The shop’s access token.

Example

YOUR_ACCESS_TOKEN
Media typeapplication/json
object
deviceId
required

The visitor’s device id, the same value as context.deviceId on the push. One of deviceId or profileId must be non-empty.

string
sessionId
required

The visitor’s session id.

string
action
required

bannerClick, bannerClose, storyImpression, storySlideView, storySlideClick, storyComplete, storyClose or pageEngagement. Any other string is stored as an event of that name.

string
profileId

The known profile id

string | null
attributions
object
bannerBlockId

The banner block token from the push response.

string
bannerId

The bannerId from the push response

string
storyId

The story token from the push response.

string
page
object
url
string
token
string
maxScrollPercent

For pageEngagement.

integer
<= 100
activeTimeMs

For pageEngagement. Under 1000 is not stored.

integer
<= 4294967295
group

The browser’s A/B test bucket (the SDK’s rlv_g cookie). An empty string or null counts as absent.

integer
<= 9999

Example

{
"deviceId": "demo-device-pb-1",
"sessionId": "demo-session-pb-1",
"action": "bannerClick",
"attributions": {
"bannerBlockId": "7e5c8e4b-1f2d-4c3a-9b8e-2a1d3f4e5c6b",
"bannerId": "1"
},
"page": {
"url": "https://demo-store.example.com/"
}
}

Accepted. The event is stored asynchronously.

Media typeapplication/json
object

Example

{}

Authentication or validation error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Examples

{
"message": "The access token you provided is invalid."
}

The domain is disabled.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "Domain is disabled. Please reach out to support@releva.ai to enable it."
}

Unexpected server error.

Media typeapplication/json
object
message
required

Human-readable error. Several validation errors are joined with a space.

string

Example

{
"message": "An internal error occurred."
}