Custom Website

This guide integrates your shop with Releva using our JavaScript library and a few server-side calls. It is written for shops on a custom stack — if you run Shopify, WooCommerce, Magento, PrestaShop, OpenCart or CS-Cart, install the plugin for your platform instead and skip this entirely.

The work splits into three independent parts. They are usually done by different people, and only the first two are needed for Releva to start producing results:

The minimum viable integration #

If you do nothing else, do these four things. They are what the recommendation and personalization algorithms actually need, and together they are a day of work rather than a project:

1. The base Releva.push() call on every page (Part A) — who the visitor is and what is in their cart.
2. Product context on product pages (Part A) — two extra fields on the same call. This is the behavioural signal everything else is built on.
3. The Product Create / Update API (Part B) — without a catalogue there is nothing to recommend.
4. The Cart Paid API (Part B) — without orders there is no revenue, no attribution and no purchase history.

Everything after that — listing and search context, banners on more page types, subscriptions, the fallback sync — improves results but is not required to go live. One exception: if you operate where GDPR or CCPA applies, the consent function in Part C is a legal requirement, not an enhancement.

Before you begin: your credentials #

Three values appear in this guide. Two of them live on the same screen; the third is per-page. Getting these straight up front saves the most common support ticket we receive.

A page token identifies a kind of page (home, product, category, search, cart), not an individual product. Create one page in Releva per page type you want personalized content on, and reuse its token across every URL of that type. A push with no token is accepted and still records behaviour — you simply get no banners or recommenders back for that page.

Part A — Front-end tracking #

There is one call to learn. You make Releva.push() on every page with a context object describing what the visitor is looking at, and Releva answers with the personalized content configured for that page. On specific page types you add two or three fields to that same object — you are not writing a new integration per page type.

A1. The base call, on every page #

Add this towards the end of the body element. Replace every placeholder with real values — and send an empty products array when the cart is empty, rather than omitting the cart.

<script>
document.addEventListener('relevaSdkLoaded', function () {
  Releva.push('<yourAccessToken>', {
    cart: {
      products: [
        {
          id: 'productId1',
          price: 12.5,
          currency: 'USD',
          quantity: 2
        }
      ]
    },
    profile: {
      id: '<yourInternalCustomerId>'
    }
  }, function (results) {
    // Called with the personalized content for this page.
  }, 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>

The onload attribute and the relevaSdkLoaded listener exist only to make sure Releva.push runs after the library has loaded. Any other way of guaranteeing that order is fine.

Send profile only when you know who the visitor is. An anonymous visitor is tracked perfectly well without it, and Releva merges their history into their profile the moment they log in.

A2. Product pages #

Same call, two more fields:

{
  "page": {
    "token": "<yourProductPageToken>",
    "categories": ["men/shoes/sport"]
  },
  "product": {
    "id": "productId1"
  }
}

A3. Category and listing pages #

Tell Releva which products the visitor is actually looking at, and which filters they applied:

{
  "page": {
    "token": "<yourListingPageToken>",
    "ids": ["productId1", "productId2", "productId3"],
    "categories": ["men/shoes/sport"],
    "filter": {
      "operator": "and",
      "nested": [
        { "key": "price", "operator": "gte", "value": "10", "action": "include" },
        { "key": "price", "operator": "lte", "value": "50", "action": "include" },
        {
          "operator": "or",
          "nested": [
            { "key": "custom.string.size", "operator": "eq", "value": "42", "action": "include" },
            { "key": "custom.string.size", "operator": "eq", "value": "43", "action": "include" }
          ]
        }
      ]
    }
  }
}

A4. Search results #

Add the query the visitor typed and the ids it returned. Sending query also records a search event.

{
  "page": {
    "token": "<yourSearchPageToken>",
    "query": "running shoes",
    "ids": ["productId1", "productId2", "productId3"]
  }
}

To record a search that was driven purely by filters with no typed text, send "query": null together with the filter object. The locale you send should describe both the page and the query; in the rare case where they differ, put the query locale in a custom field.

A5. The checkout success page #

Here cart.products changes meaning: send the lines of the order that was just placed, not what is still in the basket. Include an email address or a phone number even for guest checkouts — without one the order cannot be attached to a person.

{
  "cart": {
    "products": [
      {
        "id": "productId1",
        "price": 12.5,
        "currency": "USD",
        "quantity": 2
      }
    ]
  },
  "profile": {
    "email": "customer@example.com",
    "phoneNumber": "+15857661234"
  }
}

Phone numbers must be in international format — 585-766-1234 in a US shop becomes +15857661234. If you cannot convert a number reliably, leave it out.

This front-end call is a convenience, not the record of the sale. The authoritative one is the Cart Paid API in Part B, which your backend calls with the same order. Both are deduplicated on orderId, so sending both is correct and expected.

How to confirm Part A works #

1. Load a page of your shop with DevTools open, on the Network tab, filtered to push.
2. You should see one POST to https://releva.ai/api/v0/push/<yourAccessToken> returning 200.
3. Open its response. A working call returns a JSON object containing a userId — that is Releva’s id for this visitor. Once you have configured content for the page, the same response carries the recommenders and banners for it.
4. Check the request payload: the context object is exactly what you sent. If a field you expected is missing here, it never reached us.

A 4xx response names the offending field in its message. The most common causes are a mistyped access token and a price sent as a string ("12.50") where a number is expected.

Custom fields, end to end #

Custom fields are how your own product attributes — size, colour, brand, material — reach Releva, and they are what filtering, segmentation and recommender rules operate on. They are worth ten minutes now because everything downstream depends on their shape.

There are exactly three types (string, numeric, date), and every field is written as a key with an array of values. Here is one field — a shoe size — followed all the way through.

1. You send it with the product (Part B, Product Create / Update):

{
  "id": "productId1",
  "name": "Trail Runner",
  "listPrice": 120,
  "categories": ["men/shoes/sport"],
  "available": true,
  "custom": {
    "string": [
      { "key": "size", "values": ["42", "43", "44"] },
      { "key": "color", "values": ["red"] }
    ],
    "numeric": [
      { "key": "weightGrams", "values": [310] }
    ]
  }
}

2. You send the visitor’s selection with the cart (Part A) — the same shape, describing what this shopper chose:

{
  "id": "productId1",
  "price": 120,
  "currency": "USD",
  "quantity": 1,
  "custom": {
    "string": [
      { "key": "size", "values": ["42"] }
    ]
  }
}

3. You filter on it by joining the type and the key with dots:

{ "key": "custom.string.size", "operator": "eq", "value": "42", "action": "include" }

The rule is custom.<type>.<yourKey>. Standard fields such as price, available and categories are filtered on by their own name, with no prefix.

Two things worth getting right the first time: keep a key in the same type forever (a size sent as string on some products and numeric on others produces two unrelated fields), and use the same spelling everywhere — size and Size are different fields.

Part B — Catalog & order sync #

These run on your server and authenticate with Authorization: Bearer <secretKey>. They are ordinary JSON over HTTPS; each one answers 202 with an empty body when accepted.

Start with Product Create / Update and Cart Paid. The product ids you send here must be the same ids you send in product.id and cart.products[].id in Part A — that is what ties browsing behaviour to the catalogue. If you sell in several languages or currencies, the id has to be unique per locale; the conventions are on the Product Create / Update page.

How to confirm Part B works #

1. Send one product and check for 202 with a body of {}. A 400 names the field at fault in its message; a 402 means the shop is disabled.
2. Find that product in the Products section of the admin panel — it appears within about ten seconds — and confirm the price, availability and custom fields look right.
3. Place a test order and confirm it appears in your revenue reporting. Orders are held for about thirty seconds before processing, so allow a minute.

Part C — Consent, subscriptions & lifecycle #

Implement the parts that apply to you.

Consent (required under GDPR / CCPA) #

If you operate where data protection law applies, pass a hasConsent function as the last argument to Releva.push. It must return true only when the visitor has accepted behavioural tracking for first-party marketing and analytics:

Releva.push('<yourAccessToken>', { /* context */ },
  function (results) { /* ... */ },
  function (error) { /* ... */ },
  {
    hasConsent: function () {
      // Example: a cookie banner that sets `cookielaw=1` on acceptance
      return Releva.getCookie('cookielaw') === '1';
    }
  });

Subscriptions #

• Call the Unsubscribe API when someone opts out of marketing messages, and the Subscribe API when they opt in. Skip this entirely if you do not use Releva for email or text messages.
• For a sign-up form on the storefront itself, the front-end subscribe event is simpler than the server-side call.

New registrations #

Call the Profile Register API when a user creates an account, so the welcome journey can start and the profile carries its registration date.

Web push notifications #

Skip this unless you plan to send web push. Download service-worker.min.js, save it at the root of your site, and point the SDK at it:

Releva.push('<yourAccessToken>', { /* context */ },
  function (results) { /* ... */ },
  function (error) { /* ... */ },
  {
    serviceWorkerUrl: '/service-worker.min.js',
    hasConsent: function () {
      return Releva.getCookie('cookielaw') === '1';
    }
  });

The file must be served from the root of your domain. You may rename it, as long as serviceWorkerUrl matches.

A complete example #

If you would rather assemble from one working file than from the sections above, this is every page type in a single snippet. Build the context for the page you are rendering and pass it to one call.

<script>
document.addEventListener('relevaSdkLoaded', function () {
  // 1. Always: who the visitor is and what is in their cart.
  var context = {
    cart: {
      products: window.myShop.cartLines.map(function (line) {
        return {
          id: line.productId,
          price: line.unitPrice,
          currency: window.myShop.currency,
          quantity: line.quantity,
          custom: {
            string: [{ key: 'size', values: [line.size] }]
          }
        };
      })
    }
  };

  if (window.myShop.customer) {
    context.profile = {
      id: window.myShop.customer.id,
      email: window.myShop.customer.email
    };
  }

  // 2. Page-specific fields.
  switch (window.myShop.pageType) {
    case 'product':
      context.page = { token: '<yourProductPageToken>', categories: window.myShop.categories };
      context.product = { id: window.myShop.productId };
      break;

    case 'listing':
      context.page = {
        token: '<yourListingPageToken>',
        ids: window.myShop.visibleProductIds,
        categories: window.myShop.categories
      };
      break;

    case 'search':
      context.page = {
        token: '<yourSearchPageToken>',
        query: window.myShop.searchQuery,
        ids: window.myShop.visibleProductIds
      };
      break;

    case 'checkoutSuccess':
      // cart.products is the ORDER, not the basket - set upstream.
      context.profile = context.profile || {};
      context.profile.email = window.myShop.order.email;
      break;
  }

  Releva.push('<yourAccessToken>', context,
    function (results) {
      // Render recommenders and banners.
    },
    function (error) {
      console.error(error);
    },
    {
      hasConsent: function () {
        return Releva.getCookie('cookielaw') === '1';
      }
    });
});
</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>

Full field reference #

Everything the context object accepts. You will not need most of it on day one.

Are you done? #

1. Every page of the shop fires one POST to /api/v0/push/<yourAccessToken> that returns 200.
2. A product page sends product.id, and the id matches one in your Releva catalogue.
3. Adding to and removing from the cart changes cart.products on the next push, and emptying it sends an empty array.
4. A test order appears in your revenue reporting, from the Cart Paid call.
5. Your catalogue in the admin panel matches your shop — prices, availability, custom fields.
6. If GDPR or CCPA applies to you, declining the cookie banner makes hasConsent return false.

All six passing means the algorithms have what they need. Everything else is refinement.

All set! #

Congratulations — this concludes the integration of your shop. From here, the Custom Event API lets you report anything specific to your business that the standard calls do not cover, and it is the usual next step once the basics are flowing.