Skip to content

Area: Developers

Connect your custom website

A shop on a custom stack connects to Releva in two places. In the browser, the Releva JavaScript SDK sends one Releva.push() call per page with what the visitor is looking at, and renders the product blocks, banners and stories Releva answers with. On your server, a few HTTP calls keep Releva’s copy of your catalog current and report paid orders. This page covers the whole setup and the check at the end. The full list of SDK options, context fields and cookies is in the JavaScript SDK reference.

If you run Shopify, WooCommerce, Magento, PrestaShop, OpenCart, CS-Cart, CloudCart or Gombashop, install Releva’s app or plugin for your platform instead. It loads the same SDK for you, and adding the snippet a second time double-counts every visit.

  • Your shop exists in Releva with Platform set to Other / Custom. The platform is chosen when the shop is created and is read-only on Settings › Shop & Integration › General. A custom shop gets the default catalog sync URL {shopUrl}/api/releva/products (change it under Catalog Sync) and no sync schedule.
  • You can edit the HTML of every page of your storefront, or the template that renders it.
  • Your storefront runs on HTTPS. The SDK’s cookies are marked Secure on HTTPS pages, and Releva rejects plain HTTP requests from your server.
  • You have a Releva page for each page type you want to personalize (home, category, product, search, cart). The token of each page goes into the snippet. See How product blocks work.
  • Your product ids are stable and the same everywhere: in the catalog you send to Releva, in product.id on product pages and in cart.products[].id. That is what ties browsing behaviour to the catalog.

The minimum that makes Releva useful is four things: the base Releva.push() call on every page, product.id on product pages, products sent to the catalog API, and paid orders sent to the orders API. Everything else on this page improves results but is not needed to go live.

Add the SDK to every page of your storefront, near the end of <body>. The script tag loads the SDK asynchronously; the onload attribute dispatches relevaSdkLoaded, and your code calls Releva.push() once that event fires. Any other way of making sure Releva.push runs after the script has loaded is fine too.

<script>
document.addEventListener('relevaSdkLoaded', function () {
Releva.push('<yourAccessToken>', {
cart: {
products: [
{ id: 'DEMO-1001', price: 39.9, currency: 'EUR', quantity: 1 }
]
},
profile: { id: 'CUST-1001' }
}, function (results) {
// Personalized content the SDK did not render itself.
}, function (error) {
console.error(error);
});
});
</script>
<script async type="text/javascript"
src="https://releva.ai/sdk/v0/js/releva-sdk-js.min.js"
onload="document.dispatchEvent(new Event('relevaSdkLoaded'));"></script>

What to know about the script:

  • There is one URL and no version pinning. Releva publishes new SDK versions to the same path with a one-hour cache, so every shop runs the current version within about an hour of a release. Releva.version() in the browser console prints the version your page loaded.
  • The bundle exposes one global, Releva. It is compiled for browsers with more than 0.5% usage share; there is no documented minimum browser version.
  • Send cart on every page, with products: [] when the cart is empty. price and quantity are required numbers on every cart line; a price sent as a string ("39.90") is rejected.
  • Send profile only when you know who the visitor is. Anonymous visitors are tracked under a device id that the SDK keeps in a cookie, and their history is merged into the profile when they log in and your push sends profile.id or profile.email.
  • Single-page application: call Releva.push() again on every route change and pass { clearRelevaElements: true } as the fifth argument so the previous page’s blocks are removed first.

Nothing is configured in Releva for the SDK itself. You copy two kinds of values out of the admin and put them in your snippet.

Open Settings › Shop & Integration. On the General tab, copy Access Token with the copy icon next to the field. It is the first argument of Releva.push(). It is public by design and ships in your page source. Guide: Find your Access Token and Secret Key.

The Secret Key below it is for your server only: it authenticates the catalog, order and profile calls as authorization: Bearer <secretKey>. Never put it in front-end code. Both keys are UUIDs, so the format does not tell them apart; a push with the secret key answers 400 with Domain with the provided access token cannot be found.

Open Personalization › Product Blocks and pick a page in the page list. Its token is shown as Token: at the top, with a copy icon. Send that token as page.token on every URL of that page type: the product page’s token on every product URL, the category page’s token on every category URL, and so on. If a page type has no Releva page yet, create one with New Page.

A page token is optional. Open Page Settings (the settings icon next to the token) and set URL Path to the pathname of the page, without the trailing slash, and Releva matches a push that carries no token by the pathname of the page URL instead. That works for pages with a fixed path, such as a home page or a landing page, not for a page type with many URLs.

The same Releva.push() call takes a few extra fields depending on the page type. The field-by-field reference is in the JavaScript SDK reference.

Page type Add to the context
Every page cart, and profile when the visitor is known (wishlist if you have one)
Product page page.token, product.id
Category or listing page page.token, page.ids (the product ids shown), page.categories, optionally page.filter
Search results page.token, page.query, page.ids, optionally page.filter
Cart page page.token of your cart page, and cart.products with every line in the cart
Checkout success cart.cartPaid: true, cart.orderId, cart.products as the lines of the order, and profile.email or profile.phoneNumber

Product page:

{
"cart": { "products": [] },
"page": { "token": "<yourProductPageToken>", "locale": "en", "categories": ["women/shirts"] },
"product": { "id": "DEMO-1001" }
}

Category or listing page:

{
"cart": { "products": [] },
"page": {
"token": "<yourCategoryPageToken>",
"locale": "en",
"categories": ["women/shirts"],
"ids": ["DEMO-1001", "DEMO-1002", "DEMO-1003"],
"filter": {
"operator": "and",
"nested": [
{ "key": "price", "operator": "gte,lte", "value": "10,50", "action": "include" },
{ "key": "custom.string.size", "operator": "eq", "value": "M", "action": "include" }
]
}
}
}

page.ids lists the products shown on the page. Send page.filter only when the visitor applied filters; the syntax is in Filter syntax.

Search results:

{
"cart": { "products": [] },
"page": { "token": "<yourSearchPageToken>", "query": "linen shirt", "ids": ["DEMO-1001", "DEMO-1002"] }
}

Cart page:

{
"cart": {
"products": [
{ "id": "DEMO-1001", "price": 39.9, "currency": "EUR", "quantity": 1 },
{ "id": "DEMO-1002", "variantId": "DEMO-1002-M", "price": 24.5, "currency": "EUR", "quantity": 2 }
]
},
"page": { "token": "<yourCartPageToken>", "locale": "en", "currency": "EUR" }
}

The cart page has its own page in Personalization › Product Blocks, so its token is not the product or home page token. Copy it from that page. The token makes the push count as a Viewed Page on the cart page and returns the product blocks you set up on the cart page. The cart lines are the same lines you send on every other page. When the visitor changes a quantity or removes a line on the cart page without a page reload, call Releva.push() again with the new cart.products, so Releva records the change.

Logged-in visitor, on any page:

{
"cart": { "products": [] },
"page": { "token": "<yourHomePageToken>", "locale": "en" },
"profile": {
"id": "CUST-1001",
"email": "maria@example.com",
"firstName": "Maria",
"addCustom": {
"string": [{ "key": "preferredStore", "values": ["sofia-center"] }]
}
}
}

Use addCustom, not custom, for profile custom fields in the push. custom replaces all custom fields of the profile. If your server sets other custom fields through the profiles API, such as loyaltyTier, a push with custom deletes them. addCustom changes only the keys it names and keeps the others. The push does not accept tags: addTags in profile answers 400 with a forbidden-key error. Set tags from your server with addTags and removeTags in the profiles API.

Checkout success:

{
"cart": {
"cartPaid": true,
"orderId": "DEMO-ORDER-1001",
"products": [{ "id": "DEMO-1001", "price": 39.9, "currency": "EUR", "quantity": 1 }]
},
"profile": { "email": "maria@example.com" }
}

The checkout push is a fallback, not the record of the sale. Releva holds it for 90 seconds so that the order your server reports with the orders API wins the deduplication on orderId. Without cartPaid the push only records a cart change; without orderId the order cannot be deduplicated against the one your server reports, so always send both.

cart.orderId must be exactly the same string your server sends as orderId to POST /api/v0/carts. Releva treats a different id as a second order and counts the revenue twice. Send it as a string ("100012345", not 100012345): a numeric orderId fails validation and the push answers 400.

If data protection law applies to your shop, pass a hasConsent function in the options (the fifth argument). The SDK calls it on every push and sends profile.consent as cookiesPolicy when it returns true and mandatoryCookies otherwise.

Releva.push('<yourAccessToken>', context,
function (results) {},
function (error) { console.error(error); },
{
hasConsent: function () {
return Releva.getCookie('cookielaw') === '1'; // your consent banner's cookie
}
});

hasConsent only labels the profile. It does not stop the SDK from setting its cookies or from sending the push, and Releva still records the visit. If visitors must not be tracked before they consent, do not load the SDK, or do not call Releva.push(), until your consent banner says yes.

These calls run on your server with the Secret Key and keep Releva’s data complete. Each answers 202 with an empty body when accepted.

Call When Needed?
Create or update products Whenever a product changes: price, stock, name, custom fields Required
Report paid orders When an order is paid Required
The catalog pull-sync endpoint you build An endpoint on your side that Releva calls on a schedule to walk the whole catalog. Set its URL and a schedule on Settings › Shop & Integration › Catalog Sync Strongly recommended
Report refunds When an order is refunded If you take refunds
Delete a product When a product is gone for good. For out of stock, send available: false instead Optional
Record a registration When a customer creates an account Optional
Subscribe and unsubscribe When a customer opts in or out of marketing messages. For a sign-up form on the storefront, Releva.requestSubscribe() in the SDK is simpler If you send messages with Releva

Guide for the pull sync: Schedule a full catalog sync.

To send web push notifications, host the SDK’s service worker on your own origin and pass its URL as serviceWorkerUrl in the options. Download https://releva.ai/sdk/v0/js/service-worker.min.js and serve it from the root of your site. After each successful push the SDK asks the visitor for notification permission if they have not decided yet, registers the worker and sends the subscription to Releva.

Releva.push('<yourAccessToken>', context,
function (results) {},
function (error) { console.error(error); },
{ serviceWorkerUrl: '/service-worker.min.js' });

The worker shows a notification only for payloads that come from Releva and opens the notification’s link on click. Guide: Create a web push notification.

In the browser, open a page of your shop with DevTools on the Network tab, filtered to push. One POST to https://releva.ai/api/v0/push/<yourAccessToken> with status 200 per page means the snippet runs and the token is right. The request body is a base64 form field, not readable JSON; to see the context the SDK sent, open the page with ?rlv_mode=debug in the URL, and the SDK logs every request to the console for the rest of the tab session.

Then check in the Releva admin that the pushes were stored. The screens are the same for every integration, so follow Check that your store data arrives: Data Platform › Events filtered by Viewed Page and Viewed Product, then Data Platform › Products and Data Platform › Profiles. In Raw Data, url and pageToken are the page URL and page token from your push.

Three things are specific to a custom integration:

  • A visitor who is not logged in is listed under their device id, so select Include Anonymous Profiles on Data Platform › Profiles to see them. They become named profiles when your push sends profile.id or an email address.
  • Every product.id and cart.products[].id your pushes send must match an Id on Data Platform › Products.
  • A product you send with the catalog API usually appears in that list within about ten seconds. A test order appears in your analytics about a minute after the orders call.

The push answers 400 with Domain with the provided access token cannot be found. The first argument is not your shop’s Access Token. Usually it is the Secret Key or a token copied from another shop. The access token you provided is invalid. means the value is not a UUID at all.

The push answers 400 with The object '...' contains forbidden keys: '...'. The context is validated strictly. Remove the named key: the message names the object (page, events[0], cart.products[0]) and the key. Likewise, The 'cart.products[0].price' field must be a number. means a price or quantity was sent as a string.

The push answers 200, but there is no Viewed Page event. A page view is stored only when the push resolves to a Releva page, by page.token or by the URL Path of a page. A push with neither still records product views, cart changes, searches and custom events, but no Viewed Page row and no product blocks. Check that the token is a page token from Personalization › Product Blocks, not the access token, and that it belongs to this shop.

Viewed Page rows arrive but product blocks do not render. The page’s blocks are switched off, out of schedule, or limited to a segment the visitor is not in. Open the page with ?rlv_mode=debug to see blocks that are off or scheduled, and read Why a block is not shown.

The push answers 402. Domain is disabled. Please reach out to support@releva.ai to enable it. means the shop is switched off. Value delivery is paused for this domain because usage exceeded the plan limit. means the shop is over its plan; until it is lifted, the push route answers 402 and no browser events are recorded either.

A profile named undefined appears under Profiles. Your snippet sent profile.id as the string "undefined" for a visitor who is not logged in. Omit profile or profile.id instead of passing an empty variable.

Every visit creates a new anonymous profile. The device id lives in the rlv_p cookie. A consent tool or a cookie-cleaning script that deletes rlv_* cookies resets the visitor. The cookies are first-party, path=/ and SameSite=Lax; on a plain HTTP page they are set without Secure.

Your custom events do not reach the callback, and blocks stop rendering on that page. When your shop has a Google Tag Manager container connected under Settings › Google, the SDK pushes every custom event to the dataLayer and reads all three custom lists of the event without checking that they exist. Send custom with string, numeric and date arrays, even empty ones.

Visitors are asked for notification permission on every page. With serviceWorkerUrl set, the SDK calls Notification.requestPermission() after each push while the permission is undecided. Pass serviceWorkerUrl only on pages where you want the prompt, or only after a visitor interaction.

Data Direction Endpoint When
Page views, product views, cart changes, wishlist changes, searches, custom events Storefront (SDK) POST /api/v0/push/{accessToken} On every Releva.push(). A Viewed Page event needs a resolved page; a Viewed Product event needs product.id; cart and wishlist events are recorded when their contents changed since the last push; a Search event needs page.query or a filter; one custom event per item in events[]. The response carries the product blocks, banners and stories for the page.
Visitor profiles Storefront (SDK) same push The profile is created or updated from profile.* on the first push of a device and whenever the profile fields change. Anonymous visitors are keyed by device id; the SDK sends profile.consent on every push.
Paid orders (fallback) Storefront (SDK) same push, with cart.cartPaid and cart.orderId Queued 90 seconds after the push so the server-side order wins the deduplication.
Block and banner impressions Storefront (SDK) POST /api/v0/impressions/{accessToken} When a rendered block or banner becomes visible, once per block per page load.
Page engagement, banner clicks, story interactions Storefront (SDK) POST /api/v0/push/events/{accessToken} When the visitor leaves the page or hides the tab (scroll depth and active time), and on banner and story interactions.
Web push subscriptions Storefront (SDK) POST /api/v0/pushSubscriptions/{accessToken} After a push, when serviceWorkerUrl is set and the visitor granted permission.
Storefront newsletter sign-up Storefront (SDK) POST /api/v0/subscribe/request When your code calls Releva.requestSubscribe(). What happens next depends on Subscription Request Behavaior in Settings › Messaging.
Products Your server POST /api/v0/products, POST /api/v0/products/availability, DELETE /api/v0/products/{id} Whenever a product changes.
Products (full catalog) Releva pulls from your server GET <your sync URL>?page=&cursor= with authorization: Bearer <secretKey> On Sync Now, and on the Catalog Sync Schedule once you set one. About two minutes after a complete pass, products the pass did not return are deleted.
Orders and refunds Your server POST /api/v0/carts, refunds endpoint When an order is paid or refunded. The record of the sale.
Registrations, marketing consent Your server POST /api/v0/register, POST /api/v0/subscribe, POST /api/v0/unsubscribe On account creation and on opt-in or opt-out.

Releva calls your server only for the catalog pull sync and, if you set them up, the subscriber sync and webhooks. A catalog pull runs only when you select Sync Now or on a Catalog Sync Schedule you set.

API

  • Catalog API overview

    The catalog calls, one page each, and the authentication, request format, responses and limits they share.

  • Events API overview

    The events calls, one page each, and the authentication, request format, responses and limits they share.

  • Orders and refunds API overview

    The order calls, one page each, and the authentication, request format, responses and limits they share.

  • Profiles API overview

    The profile calls of the Releva API, one page each (create or update, get, delete, export, register, the subscriber sync and the loyalty link), plus how profiles are identified.

  • Consent API overview

    The consent and subscription calls of the Releva API, one page each - subscribe from your server or the browser, double opt-in, unsubscribe, unsubscribe links and one-click, and consent history.

  • Push notifications API overview

    How a browser or mobile app registers for Releva push notifications: the web SDK setup, the two registration endpoints, authentication with the access token, errors and limits.