Integrate Releva in 12 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. 

Step 1: On each page #

Just add the following towards the end of the body element in HTML. Please make sure to replace all values in the snippet below with the actual values! In the products.custom field, please out the specific values of any configurable product attributes that the user has selected before adding each product to their cart. A detailed description of all fields is available below.

<script>
document.addEventListener('relevaSdkLoaded', function() {
  Releva.push("<yourAccessToken>", {
     "cart": {
        "products":  [
          {
            "id": "",
            "price": 0,
            "currency": "",
            "quantity": 0,
            "custom": {
              "string": [
                {"key": "color", "values": ["red"]}
              ],
              "numeric": [
                {"key": "size", "values": [18]}
              ]
            }
          }
       ]
    },
    "profile": {
      "firstName": "",
      "lastName": "",
      "email": "",
      "registeredAt": "YYYY-mm-ddT00:00:00.000Z",
      "location": {"lat": 39.9352959, "lon": 23.5825895}
    },
    "wishlist": {
      "products": [
        {"id": "...}
      ]
    }
  }, function(results) {
    // TODO: callback to implement rendering of custom recommenders and banners
  }, 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 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.

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.

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 products currently in the user’s wishlist

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>",
  "categories": ["men/shoes/sport"]
},
"product": {
  "id": ""
}

The context.page Object #

The Context Object describes 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.

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

The context.page Object #

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

The context.page.filter object #

This is an object with the following properties:

The context.page.filter.nested array #

This is an array of conditions used for the filter with the following properties:

Step 4: On search and search result pages #

Find the Releva.push(...) invocation you added in Step 1. Then, ensure that your page object contains the ids property that will show the result from a search and a query string that defines the text searched by the user. Also, include the filter object (see the previous step for detailed specification).

"page": {
  "token": "<tokenOfAnyPageWithSearchCapability>",
  "query": "my simple query",
  "ids": ["productId_id1", "productId_2", "productId_3"],
  "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"},
        ]
      }
    ]
  }
},
...

Note that if you add the optional query parameter, the system will also add a search event. If you want to add search event even if the query is empty but you have filter, just pass null to query like that "query": null. 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: On checkout success pages #

Find the Releva.push(...) invocation you added in Step 1. Then, change your cart[].products to contain not the list of products in the user’s cart, but the list of products that were part of the newly placed order.
Include the profile object with email and phoneNumber, if you have them (at least one is required, send both if you have both). Please ensure that the profile object is passed even if the order was placed via guest checkout and not by a registered user.

Note that you need to convert the phone number to a valid international format (e.g. if your shop operates in the U.S., you need to change 585-766-1234 to +15857661234; if the phone number cannot be converted in this way, do not include it in the request).

document.addEventListener('relevaSdkLoaded', function() {
  Releva.push("<yourAccessToken>", {
     "cart": {
        "products":  [
          {
            "id": "id_of_ordered_product",
            "price": 1,
            "currency": "USD",
            "quantity": 2,
            "custom": {
              "string": [
                {"key": "color", "values": ["red"]}
              ],
              "numeric": [
                {"key": "size", "values": [18]}
              ]
            }
          }
       ]
    },
    "profile": {
      "firstName": "",
      "lastName": "",
      "email": "",
      "phoneNumber": "+15857661234",
      "registeredAt": "YYYY-mm-ddT00:00:00.000Z",
    }
  }, function(results) {
    // TODO: callback to implement rendering of custom recommenders and banners
  }, function (error) {
    console.error(error);
  });
});

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 6: 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 7: Ensure data protection compliance #

If you operate in countries where data protection laws such as GDPR, CCPA apply, you must implement an additional function which tells Releva if behavioral tracking for first-party marketing and analaytics is allowed.

In the last argument to Releva.push, you need to pass a function called hasConsent which returns true if behavioral tracking for first-party marketing and analaytics is allowed, or false otherwise.

document.addEventListener('relevaSdkLoaded', function() {
  Releva.push("<yourAccessToken>", {
  ...
  }, function(results) {
    ...
  }, function (error) {
    ...
  },
  // for example
  // if you have a cookie dialog which sets a cookie called 'cookielaw' with value '1' when the cooke is accepted
  // you need to implement the logic below for Releva to respect this setting
  {
    ....
    hasConsent: function() {
      return Releva.getCookie('cookielaw') === '1';
    }
  });
});

Step 8: 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 9: Call the cart paid API when a customer places an order #

See Cart Paid API for implementation details.

Step 10: 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 11: 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.

Step 12: Send newly registered users to Releva. #

When a new user registers on your shop, you need to call the Profile Register 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.