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.

The context.page Object

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

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.

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.

The context.profile Object

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

The context.wishlist Object

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

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.

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.