Search the Documentations
Categories

Server Side Integration

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.) If you are using the JS SDK, you should not set this.
mergeProfileIdString (Optional)An existing profile ID to merge into the profile’s history. If you are using the JS SDK, you should not set this.
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.) If you are using the JS SDK, you should not set this.
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. If you are using the JS SDK, you should not set this.
ridStringThe value of the rlv_rid URL parameter. If the URL parameter is not set, it should be omitted. If you are using the JS SDK, you should not set this.
rnameStringThe value of the rlv_rname URL paramter. If the URL parameter is not set, it should be omitted. If you are using the JS SDK, you should not set this.
rposIntegerThe value of the rlv_rpos URL paramter. If the URL parameter is not set, it should be omitted. If you are using the JS SDK, you should not set this.
rpidStringThe value of the rlv_rpid URL parameter. If the URL parameter is not set, it should be omitted. If you are using the JS SDK, you should not set this.
bidStringThe value of the rlv_bid URL parameter. If the URL parameter is not set, it should be omitted. If you are using the JS SDK, you should not set this.
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. If you are using the JS SDK, you should not set this.
cartObjectA description of the visitor’s cart. If the cart is empty, it should be omitted. See the context.cart for more info.
cartChangedBooleanThis flag should be set if any of the information in the cart has changed. If you are using the JS SDK, you should not set this.

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.
localeISO 639-1 StringThe product locale (e.g. enbg, etc.)
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 StringThe product currency.
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.
emailStringVisitor’s email address.
phoneNumberString (Optional)Visitor’s phones number. Phone numbers must start with “+” followed by a sequence of numbers. Valid phone number: +49875345976.
registeredAtISO-8601 String (Optional)The date and time when this visitor created their account.
customObject (Optional)The custom fields associated with the profile. See custom for details.

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"],
      "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": "..."
      }
    },
    ...
  ]
}

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.

Previous Front End Integration
Table of Contents