Server Side Integration

Updated on October 2, 2024

The Push API #

The Releva API is designed for simplicity and speed. One of the primary design goals was to limit the number of calls that a client needs to perform in order to push data to Releva, and obtain personalized content for display.

If you would like to do a client-side integration, please see the Client-side Integration section which explains how to use our JavaScript SDK. It makes the integration process much easier than calling the API directly.

You may perform requests to the API using the following curl equivalent:

curl -H 'X-Forwarded-For: <clientIp>' -H 'Content-Type: application/json' -H 'Authorization: Bearer <accessToken>' -XPOST https://releva.ai/api/v0/push -d'{
  context: {...},
  options: {...}
}'
  • Please note that you should only invoke Releva’s API on behalf of clients who have given you consent to do so under GDPR.
  • It’s important to set the x-forwarded-for header in order for Releva’s geolocation to work properly.

Request Parameters #

The context Object #

The Context Object has the following structure. All fields are required unless stated otherwise.

FieldTypeDescription
profileIdStringA unique profile ID identifying the visior (e.g. visitor’s cookie.) Only send this if user has not given consent for their data to be collected and used for marketing or analytics purposes. Sending this for users who have not given given consent may be a violation of GDPR / CCPA / or other relevant legislation.
mergeProfileIdString (Optional)An existing profile ID to merge into the profile’s history.
profileIdChangedBooleanThis flag should be set if profileId has been changed (e.g. a new profile id has been generated)
impersonateProfileIdString (Optional)This field essentially allows you to implement impersonation – you can use it to obtain a response for a different profile ID without associating any data with it.
sessionIdStringA unique session ID identifying the visior (e.g. visitor’s cookie with session scope.) Only send this if user has not given consent for their data to be collected and used for marketing or analytics purposes. Sending this for users who have not given given consent may be a violation of GDPR / CCPA / or other relevant legislation.
isFirstSessionStringTrue if this is the first session for this profile id, false otherwise
pageObjectThe page context of the currently visited page See context.page.
groupIntegerA random integer between 0 and 9,999. It must never change for a given profile id. Only send this if user has not given consent for their data to be collected and used for marketing or analytics purposes. Sending this for users who have not given given consent may be a violation of GDPR / CCPA / or other relevant legislation.
ridStringThe value of the rlv_rid URL parameter. If the URL parameter is not set, it should be omitted.
rposIntegerThe value of the rlv_rpos URL paramter. If the URL parameter is not set, it should be omitted.
rpidStringThe value of the rlv_rpid URL parameter. If the URL parameter is not set, it should be omitted.
bidStringThe value of the rlv_bid URL parameter. If the URL parameter is not set, it should be omitted. 
modeString (Optional)You may set this to debug to see more debug information, and preview results from recommenders which are not turned on.
productObjectA description of the product, if the visitor is on a product page. If not – it should be omitted. See the context.product for details.
profileObjectVisitor’s personal information, if they are logged in and have accepted the cookie policy. See the context.profile for exact description.
profileChangedBooleanThis flag should be set if any of the information in the profile has changed. For example, after a user changes their name or email. 
cartObjectA description of the visitor’s cart. If the cart is empty, the cart object should contain a “products” key with the value of an empty array.
cartChangedBooleanThis flag should be set if any of the information in the cart has changed. 
wishlistObjectA description of the visitor’s wishlist. If the wishlist is empty, the wishlist object should contain an empty “products” array.
wishlistChangedBooleanThis flag should be set if any of the information in the wishlist has changed. 

The context.page Object #

The Context Object descrbes the page the user is currently viewing. All fields are required unless stated otherwise.

FieldTypeDescription
tokenString (Optional)The page token of the currently visited page (e.g. home page, product page, cart page, etc.) Consult with your admin panel to find the right token to use. If you do not wish to obtain personalized content, you may omit this.
urlURL StringThe full URL string of the web page which triggered this request
localeISO 639-1 String (Optional)The page locale.
currencyISO-4217 String (Optional)The page currency.
idsArray[String]If the user is visiting a listing page, set this to the list of product ids currently displayed. Othersise, it should be omitted. Note that if you have a multi-locale shop ( you sell in multiple languages / currencies), each id will need to be unique across all locales.
categoriesArray[String]If the user is visiting a listing page, set this to the current categories selected.
customObject (Optional)The custom field filters associated with the currently viewed product listing (for instance – shoe sizes 42, 43, 44). See custom for details.

The context.product Object #

This object describes the currently viewed product if the visitor is on a product page. In all other cases, it should not be set.

FieldTypeDescription
idStringA unique product ID identifying your product. Note that if you have a multi-locale shop ( you sell in multiple languages / currencies), this id will need to be unique across all locales.
customObject (Optional)The custom fields associated with the currently viewed product, for example the currently selected shoe size. See custom for details.

The context.cart Object #

This object describes current state of the visitor’s cart. It should be set whenever a visitor’s cart is not empty.

FieldTypeDescription
productsArray[Object]A list of products in the cart.
products[].idStringA unique product id. Should be identical to context.product.id for a given product. Note that if you have a multi-locale shop ( you sell in multiple languages / currencies), this id will need to be unique across all locales.
products[].priceFloatThe unit price at which this product was purchased.
products[].currencyISO-4217 String (Optional)The product currency. This field is required if you sell products in multiple currencies.
products[].quantityIntegerThe quantity purchased.
products[].customObject (Optional)The custom fields associated with the product. See custom for details.

The context.profile Object #

This object describes the currently logged in visitor. It should be set whenever a visitor is logged in.

FieldTypeDescription
firstNameString (Optional)Visitor’s first name.
lastNameString (Optional)Visitor’s last name.
emailString (Optional)Visitor’s email address.
phoneNumberString (Optional)Visitor’s phones number. Phone numbers must start with “+” followed by a sequence of numbers. Valid phone number: +49875345976.
consentString (Optional)Visitor’s consent, may be one of these:
– legitimateInterest – this is the default one, and every user has this consent by default
– privacyPolicy
– mandatoryCookies
– cookiesPolicy
customObject (Optional)The custom fields associated with the profile. See custom for details.

The context.wishlist Object #

This object describes the currently logged in visitor. It should be set whenever a visitor is logged in.

FieldTypeDescription
products[].idStringThe product id of a product in the wishlist
products[].customObject (Optional)The custom fields associated with the specific product variation – e.g. chosen size and color

The custom Object #

You may use the custom object in product,cart.products[], or profile to send custom attributes for the corresponding entity and make it searchable. Product custom fields will then be available in recommenders as boosts and filters. Cart and profile custom fields will be available as segment filters and recommenders in email campaigns.

FieldType
stringArray[Object]
string[].keyString
string[].valuesArray[String]
numericArray[Object]
numeric[].keyString
numeric[].valuesArray[Float]
dateArray[Object]
date[].keyString
date[].valuesArray[ISO-8601 String]

An example of custom field of type string follows:

"custom": {
  "string": [
      {"key": "tags", "values": ["shoes","mountain","running"]]},
      {"key": "variant_colors", "values": ["red","blue","pink"]},
  ]
}

As depicted in the table above, custom fields support date, numeric and string arrays.

Response Format #

A successful response will return HTTP Status 200 and have the following structure:

{
  "recommenders": [
    {
      "token": "916c829e-c1eb-4f49-81ec-106ab8471f3b",
      "name": "Trending from This Category",
      "meta": {
        "algorithm": "hot"
      },
      "tags": ["t1", "t2"],
      "cssSelector": "body",
      "displayStrategy": "befeoreend",
      "template": {"id": 123, "body": "..."},
      "response": [
        {
          "available": true,
          "categories": [
            "cat1"
          ],
          "createdAt": "2019-08-18T05:48:42.419Z",
          "currency": "BGN",
          "custom": {
            "string": [
              {
                "values": [
                  "bar"
                ],
                "key": "f"
              }
            ]
          },
          "data": {
            "foo": "bar"
          },
          "description": "Some Description",
          "discount": 0,
          "discountPercent": 0,
          "discountPrice": 0,
          "id": "3847012384816",
          "imageUrl": "https://cdn.shopify.com/s/files/1/0263/8328/6320/products/yes-me-me-me-me_286x381.jpg?v=1565038619",
          "listPrice": 2500,
          "locale": "bg",
          "mergeContext": {
            "rid": "...",
            "rpid": "..."
          }
          "name": "Test Product",
          "price": 2500,
          "publishedAt": "2019-12-25T12:41:30.457Z",
          "updatedAt": "2019-12-25T12:41:30.457Z",
          "url": "https://releva-dev.myshopify.com/products/test-product?rlv_rid=916c829e-c1eb-4f49-81ec-106ab8471f3b",
        }
      ]
    },
    ...
  ],
  "banners": [
    {
      "token": "9f4625ea-4ef1-4503-b55c-f11c13e25a60",
      "name": "Test Banner",
      "html": "<html>\n  Hello World!\n</html>",
      "tags": ["t1", "t2"],
      "mergeContext": {
        "bid": "..."
      },
      "displayType": "popup",
      "delaySeconds": 123,
      "scrollPercentage": 23,
      "cssSelector": "body",
      "trigger": null
    },
    ...
  ]
}

Please note that the recommenders and banners arrays in the response would only contain elements which are enabled in the admin panel. If you wish to test how the rendered responses would look like without affecting your existing customers, you can add rlv_mode=debug to your shop URL. This will switch Releva to debug mode and will return responses for all content elements even if they are turned off. This effect will last for the duration of your browser session.

You may use tags to cutomize your rendering behavior (for example render banner in a popover if tags.indexOf('popover') !== -1and set tag popover in admin panel for some of the banners).

For recommenders, you may need to handle rendering differently depending on the algorithm used and your use case. For example, if using a reranker recommender, you will probably want to replace your product listing with the order returned by the recommender. For all other cases, you would probably want to add content – on product pages – below the product description. On the home page – towards the first 30% of the height. If in doubt – please get in touch for some free advice!

An error response will return a HTTP 4xx or 5xx status code and have the following structure:

{
  "message": "A description of the error and how to fix it, if it's a client error."
}

If you are using the JavaScript SDK, the error callback will be called with this response as an Error object.