Search the Documentations
Categories

Front End Integration

Web Frontend Integration

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: leave this as it is for now - will implement in a later step
    console.log(results);
  }, function (error) {
    // TODO: handle error (arg is Error object)
  });
});

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.
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 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-1StringThe 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. 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": [],
  "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-1StringThe product locale (e.g. enbg, etc.)
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: Custom events

Find the Releva.push(...) invocation you added in Step 1. Then, add an events array with event objects. You may send more than one event in each call.

        "events": [
            {
                "action": "surveyInteraction",
                "products": [
                    {
                        "id": "4578199044236"
                    },
                    {
                        "id": "4578197799052"
                    },
                    {
                        "id": "4578197831820"
                    }
                ],
                "custom": {
                    "string": [
                        {
                            "key": "q1",
                            "values": [
                                "answer1"
                            ]
                        },
                        {
                            "key": "q2",
                            "values": [
                                "answer2"
                            ]
                        }
                    ]
                }
            },
            {
                "action": "formInteraction",
                "products": [],
                "custom": {
                    "string": [
                        {
                            "key": "type",
                            "values": [
                                "Sign Up For Demo"
                            ]
                        }
                    ]
                }
            }
        ],
...

Note that the events object is an array and Releva will create all events added to it. Taking the example above, Releva will create surveyInteraction and formInteraction events.

Each event Object describes action, timestamp, products and custom properties of the custom event. All fields are required unless stated otherwise.

actionStringName of the custom event.
timestampISO-8601 String (Optional)The date and time when this event happened.
productsArray[Object] (Optional)Products identifiers associated with this event.
customObject (Optional)The custom field filters associated with the currently viewed product listing (for instance – shoe sizes 42, 43, 44).

Step 6: Render personalization results

Now it’s time to replace the dummy callback which we added earlier with a real function to render the results:

...
}, function(results) {
  // TODO: leave this as it is for now - will implement in a later step
  console.log(results);
});
...

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 customize 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.

Step 7: Handle errors

Now we replace the dummy callback which we added earlier with a real function to catch errors:

...
, function (error) {
  // TODO: handle error (arg is Error object)
});
...

Step 8: Register service worker

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

See Cart Paid API for implementation details.

Step 11: Implement the periodical fallback 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 12: 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