Releva has completed an $870,000 financial round led by New Vision Fund 3 with participation by HR Capital AD, Verto Invest and the investment arm of private investors.
Search the Documentations
Categories

Standard Integration

Integrate Releva in 9 easy steps.

This page will guide you through a full integration of your shop with Releva using our JavaScript library and a few backend calls. 

The Releva JavaScript SDK needs to set cookies in order to function. To ensure GDPR compliance, please only call Releva for visitors who have agreed to your cookie policy.

Step 1: On each page

Just add the following towards the end of the body element in HTML.

<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 document.addEventListener(..) wrapper are necessary to ensure that the Releva.push call is attempted after the SDK has finished loading. You are free to use alternative methods for ensuring the proper execution sequence is followed.

Then, whenever your page has loaded, make the following request. Please make sure to replace all values in the snippet below with the actual values!

document.addEventListener('relevaSdkLoaded', function() {
  Releva.push("<yourAccessToken>", {
      "products": [
        {
          "id": "",
          "price": 0,
          "currency": "",
          "quantity": 0,
        }
      ]
    },
    "profile": {
      "firstName": "",
      "lastName": "",
      "email": "",
      "registeredAt": "YYYY-mm-ddT00:00:00.000Z",
    }
  }, function(results) {
    // TODO: callback to implement rendering of custom recommenders and banners
  }, function (error) {
    console.error(error);
  });
});

Hint: If a user removes the last item from their cart, and their cart is deleted, please send a request with an empty products list. Example below:

...
"cart": {
  "products": []
},
...

The context.cart Object

This object describes the 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 are associated with the product.

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.
registeredAtISO-8601 String (Optional)The date and time when this visitor created their account.
customObject (Optional)The custom fields are associated with the profile.

Step 2: On product pages

Find the Releva.push(...) invocation you added in Step 1. Then, add the following to the second parameter:

"page": {
  "token": "<yourProductPageToken>"
},
"product": {
  "id": "",
}

The context.page Object

The Context Object describes 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 page locale (e.g. enbg, etc.)
currencyISO-4217 String (Optional)The page currency. This field is required if you sell products in multiple currencies.
idsArray[String]If the user is visiting a listing page, set this to the list of product ids currently displayed. Otherwise, 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 are associated with the currently viewed product listing (for instance – shoe sizes 42, 43, 44).

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.

Step 3: On the product listing page (e.g. category page)

Find the Releva.push(...) invocation you added in Step 1. Then, add the following to the second paramter:

"page": {
  "token": "<yourProductListingPageToken>",
  "ids": [],
  "categories": ["men/shoes/sport"],
  "locale": "en"
}

The context.page Object

The Context Object describes 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.)
currencyISO-4217 String (Optional)The page currency. This field is required if you sell products in multiple currencies.
idsArray[String] (Optional)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.
queryString (Optional)The user query.
categoriesArray[String] (Optional)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).

Step 4: On search and search result pages

Find the Releva.push(...) invocation you added in Step 1. Then, make sure that your page object contains the ids property that will show the result from a search and a query object that defines the query of the user:

"page": {
  "token": "<tokenOfAnyPageWithSearchCapability>",
  "query": "my simple query",
  "ids": ["productId_id1", "productId_2", "productId_3"],
  "locale": "en"
},
...

Note that if you add the optional query parameter, the system will also add a search event. We highly recommend adding the ids field that must represent the result of the search query. The locale must represent both the page and query locale. In the rare event when they differ you shall describe search locale as a custom property.

Step 5: Register service worker (Optional)

If you do not plan on using Releva to send push notifications, you may skip this step.

First, download service-worker.min.js and save it to the root of your site. You may change the name, but make sure you also change the name when you register it below.

Then we need to add the following object to the end of each Releva.push call:

document.addEventListener('relevaSdkLoaded', function() {
  Releva.push("<yourAccessToken>", {
  ...
  }, function(results) {
    ...
  }, function (error) {
    ...
  },
  // add this to register the service worker
  // please make sure you use the correct name here if you renamed the file
  // keep in mind this needs to point to the root of your domain
  {
    serviceWorkerUrl: '/service-worker.min.js'
  });
});

Step 6: Call the poduct update API call when changes in your catalogue occur

This is necessary for ensuring that changes in your catalogue are reflected in Releva in a timely manner. See Product Update for implementation details.

Step 7: Call the cart paid API when a customer places an order

See Cart Paid API for implementation details.

Step 8: Implement the periodical product sync API

This ensures that Releva will learn about changes in your catalogue even if your Product Update call does not work. It is highly recommended to implement this fallback mechanism. See Periodical Product Sync for implementation details.

Step 9: Send subscribes and unsubscribes to Releva

If you do not plan on using Releva to send emails or text messages, you may skip this step.

  1. When a user wishes to unsubscribe from receiving email or other marketing communication through Releva, you need to call the Unsubscribe API to notify Releva.
  2. When a user wishes to subscribe to receiving email or other marketing communication through Releva, you need to call the Subscribe API to notify Releva.

All Set!

Congratulations! This concludes the integration of your shop. Releva offers some advanced features that will help you achieve even better results. Feel free to explore the API Specification for information about how to send custom product and profile data, which can later be used in personalization. Also, feel free to look into the Data Deletion API and the Retrieve Tracked Data API which is designed to help you fulfill GDPR-related requests automatically.

Previous Integration Guide
Next Server Side Integration
Table of Contents