All Collections
Product recommendation engine
NPM PACKAGE. Implementation of the QuarticOn recommendation system on the front side of the application
NPM PACKAGE. Implementation of the QuarticOn recommendation system on the front side of the application
M
Written by Martyna Woźniszczuk
Updated over a week ago

In response to the expectations of our clients, we provide a solution that enables the independent implementation of the QuarticOn Recommendation System in an e‑shop, using NPM – https://www.npmjs.com/ (Node Package Manager).

This package, written in JavaScript, enables the implementation of the QuarticOn Recommendation System on the front side of the application in libraries such as React, Vue, Angular, by using them directly in the application code.

Similar to the API implementation (https://docs.quarticon.com/storeapi/documentation/#tag-Recommendation), this solution is entirely done on the client's side. The difference is that the API implementation must take place on the backend side due to the secret access keys.

As we wrote above, the implementation through the NPM package takes place on the front side of the application while loading the page view in applications based on React, Vue, Angular frameworks. Of course, it can also be used in other frameworks, it is important that they support NPM.

The technical documentation for this plugin can be found here:

https://docs.quarticon.com/quarticTs/index.html.

The plugin itself is located here:

https://www.npmjs.com/package/qon-connection.

What you need before starting the implementation

  • To be able to start the implementation, you need a prepared account in the QuarticOn system. For this purpose, contact our Sales Department at sales@quarticon.com.

  • The account must have:

  • For the initial configuration of the qon-connection module, you need two variables at the beginning:

    • CUSTOMER_SYMBOL – a string of characters identifying your account in the QuarticOn system

    • HOST_URL – API address that is needed to call all the methods available in the application

You will receive CUSTOMER_SYMBOL and HOST_URL from your sales advisor in QON. If you do not have an account in our system or you just have questions, please contact our sales team.

The main assumptions required for the proper operation of the QuarticOn Recommendation System

  1. The product catalogue is necessary to display recommendations. By default, the catalogue is refreshed every 24 hours (the most common type of catalogue is the one in XML format, compatible with Google Merchant).

  2. The product IDs provided to us must match those in the product catalogue.

  3. In order for the system to learn, we need information about user's all types of behaviour:

    1. product card display (implementation process described below)

    2. clicks on our recommendation frames (in the case of using our links, the process will take place automatically)

    3. products purchased by the customer (implementation process described below)

An example of a user behaviour path on the e-shop's website

  1. The user enters the home page

    1. on the home page, the user sees a recommendation frame with the title Recommended for you

  2. The user enters the product page

    1. information about the product display is sent to the QON system

  3. The user clicks on the QON recommendation frame displaying similar products

    1. information about a click on the product is sent to the QON system

  4. The user adds the product clicked from the QON frame to the shopping cart

  5. The user purchases this product

    1. The QON system receives information about the transaction made

If the purchase was made after clicking on the recommendation frame, this product will be treated as a purchase thanks to QON. Each purchase made within 24 hours from the moment of clicking is treated as a recommendation purchase.

Step-by-step implementation process

A. Prepare recommendation widgets

You can read about which recommendations will work on which pages in the article Recommendation strategies – introduction. For a description of individual strategies, see the section Recommendation strategies.

To add a new recommendation widget, go to the Recommendations tab and select the Add widget button. You will be redirected to the editor which consists of five steps:

  1. Select a placement for the recommendation frame

  2. Widget settings

  3. Select a product recommendation strategy

  4. Drag&drop editor

  5. Summary

1. Select a placement for the recommendation widget

The structure of placements for widgets is predefined by our system and looks like this:

The above arrangement was developed by us on the basis of many years of working with clients and methods that we have tested. Widget placements can be modified by the user, however, we recommend that you stick to a specific hierarchy of designated recommendation places from the beginning of managing recommendations.

The names of the pages and placements on the pages indicate the predetermined position where the recommendation widget will be triggered. For example, if your goal is to add a widget on the product page under the short description of the product, but before the section of additional information about the product, we recommend using the PRODUCT PAGE -> Middle.

Attention!

You can define many recommendation widgets within one placement. The system will then randomly select widgets each time the placement they are pinned to is invoked. In the Select a placement for the recommendation frame tab, select the place in the defined structure where the widget is to appear.

2. Widget settings

In this tab you can match a widget with a defined group of users (user segments). If you created some of them before, you can pick them from the list. If not, add a new user segment (Add an audience).

3. Select a product recommendation strategy

In this tab 12 predefined recommendation strategies are available. When you hover your cursor over a strategy, a short description of it will appear. Choose one of them and decide what products are to be displayed to the user.

Our best practice recommendation strategy is outlined below:

Remember!

The practices described above do not have to apply to every client, because each industry is different. It may turn out that the correct operation of the recommendation engine in your online shop will require testing different settings. The above diagram is only a proposal, we are open to your suggestions.

4. Drag&drop editor

In the case of implementation via NPM, the editor will not be used, because you decide on the appearance of your recommendations. Name your widget so that you know where it is located and proceed to the next step by clicking Next.

5. Summary

Check the summary and save the widget.

Repeat the above steps for all the widgets you want to include on your website. Widgets can be edited, moved, deactivated, etc. For more details on how to edit them, see the article titled Editing recommendation widgets: drag&drop editor.

B. Implement the sending of information about product page visits

Following the package instructions (https://www.npmjs.com/package/qon-connection), implement the code.

The information about visiting the website should be sent to us when the user visits the product card.

Create an instance of the package using the CUSTOMER_SYMBOL and HOST_URL we gave you:

const CUSTOMER_SYMBOL = 'YOUR_CUSTOMER_SYMBOL'
const HOST_URL = 'YOUR_HOST_URL'

const CUSTOMER_CONFIGURATION = new Config.Config({ customerSymbol: CUSTOMER_SYMBOL, host: HOST_URl})

Pass the object with the product id as below:

const productTracker = new Track.Tracker(CUSTOMER_CONFIGURATION)
productTracker.sendProductView({ id:'PRODUCT_ID' })

Example of use in VUE code:

export default Vue.extend({
  name: 'demopage1',
  data(): DataParams {
    return {
      hostUrl: 'quartic.test',
      customerSymbol: 'yourcustomerSymbol',',
      customerConfiguration: new Config.Config({ customerSymbol: 'this.customerSymbol', host: 'this.hostUrl' }),
      productViewId: '115310',
    }
  },
  mounted() {
      this.sendProductPageView()
  },
  methods: {
    sendProductPageView() {
      const tracker = new Track.Tracker(this.customerConfiguration)
      tracker.sendProductView({ id: this.productViewId })
    },
  },
})

C. Implement sending information about purchases

Send us information about products that were purchsed by the user of your e-shop.

It is important to send all transactions to the QuarticOn system. Our system, based on clicks on our recommendations, will automatically mark the purchased products as those of our recommendations. Send the transaction on the website, the so-called Summaries/Thank You Page.

As before, create an instance of the application:

const CUSTOMER_SYMBOL = 'YOUR_CUSTOMER_SYMBOL'
const HOST_URL = 'YOUR_HOST_URL'

const CUSTOMER_CONFIGURATION = new Config.Config({ customerSymbol: CUSTOMER_SYMBOL, host: HOST_URl})

Then prepare information about the purchased products (example for 2 products):

const transaction = {
    transactionId: 'TRANSACTION_ID',
    basket: [{
        productId: 'PRODUCT_ID_1',
        price: 'PRODUCT_PRICE_1',
        quantity: 'PRODUCT_QUANTITY_1'
    }, {
        productId: 'PRODUCT_ID_2',
        price: 'PRODUCT_PRICE_2',
        quantity: 'PRODUCT_QUANTITY_2'
    }]
}

Remember that the productId provided in the transaction should match the one provided in the product catalogue.

Send transaction:

// configure tracker
const transactionTracker = new Tracker(CUSTOMER_CONFIGURATION)
// send transaction
transactionTracker.sendTransaction(transaction)

Example of use in VUE:

export default Vue.extend({
    name: 'demopage1',
    data(): DataParams {
        return {
            hostUrl: 'quartic.test',
            customerSymbol: 'yourcustomerSymbol', ',
            customerConfiguration: new Config.Config({ customerSymbol: 'this.customerSymbol', host: 'this.hostUrl' }),
        }
    },
    mounted() {
        this.sendProductPageView()
    },
    methods: {

        sendTransaction() {
            const transactionTracker = new Track.Tracker(this.customerConfiguration)

            const transaction = {
                transactionId: 'TRANSACTION_ID',
                basket: [{
                    productId: 'PRODUCT_ID_1',
                    price: 'PRODUCT_PRICE_1',
                    quantity: 'PRODUCT_QUANTITY_1'
                }, {
                    productId: 'PRODUCT_ID_2',
                    price: 'PRODUCT_PRICE_2',
                    quantity: 'PRODUCT_QUANTITY_2'
                }]
            }
            transactionTracker.sendTransaction(transaction)
        },
    },
})

D. Implement recommendation frames on your website

To start the implementation process, you need to select a widget to implement and have its placementID.

PlacementId is our unique widget ID. You can find it in the Recommendations -> Widgets tab (https://cp.quarticon.com/upseller/myPlacements).

We will describe the implementation process on the example of the Recommended for you widget on the home page:

We have marked its placementId with a colour – this is what we need for implementation. Our placementId is: _qS_2tj3o.

We will put the widget on the home page, so we will not use the filtering options available in the package (more about the available options here).

As before, we create an instance of the application:

const CUSTOMER_SYMBOL = 'YOUR_CUSTOMER_SYMBOL'
const HOST_URL = 'YOUR_HOST_URL'

const CUSTOMER_CONFIGURATION = new Config.Config({ customerSymbol: CUSTOMER_SYMBOL, host: HOST_URl})

and then an instance of the recommendation engine by passing CUSTOMER_CONFIGURATION:

const recommendationEngine = new Recommendation.Recommendation(CUSTOMER_CONFIGURATION )

Now we will prepare the configuration of the widget itself:

const homePageWidget1= {
    placementId: '_qS_2tj3o',// here we used our placementId
    filters: []
}

Since we are not filtering the frame, we pass an empty table.

Now we need to call the engine to return the products to us. Note that this is an async function, requiring the use of await.

const homePageRecomendations =  await recommendationEngine.getRecommendation(homePageWidget1)

constole.log (homePageRecomendations)

Console.log used here will show us the products recommended for the user. Now it is enough for these products to be wrapped in html and placed on the page. In response, our API returns a set of data about the product:

  • _id – product ID

  • _pageUrl – link to the product with the QuarticOn tracking code

  • _imageUrl – link to the product photo

  • _price – current product price (downloaded from the product catalogue uploaded to QuarticOn)

  • _priceOld – old product price (taken from the product catalogue uploaded to QuarticOn)

  • _title – product name

  • _custom.name – the name of the additional product field

  • _custom.value – value of the additional product field

Remember! When creating a recommendation frame based on the returned data, be sure to insert _pageUrl as a link to a given product from the response. Otherwise, the recommendation system will not register clicks on the frame and – thus – report their effectiveness in the panel and teach AI algorithms. This has a huge impact on the quality and effectiveness of your actions!

Remember that when integrating through an NPM package, it is up to you how the wigdets will look like. You can choose to make each widget look different or, by mapping your widgets on the page, map them in such a way that they will be no different from the native widgets on the page. The titles of your frames are also up to you, so when you implement via NPM, you have the greatest freedom.

E. Implement recommendation frames on the remaining pages

The implementation on other pages is the same as in the example above. There are differences in the filtering used. We recommend the following implementation method:

  • Category, subcategory, brand page

    • pass to the configuration of the Category Filter widget:

      • filters: [Recommendation.FilterApi.category('categoryid')] – to narrow down the products displayed to one category

      • filters: [Recommendation.FilterApi.category('categoryid1'), Recommendation.FilterApi.category('categoryid2')] – to narrow down the products displayed to more than one category

  • Product, cart page

    • provide the ID of the viewed product/products that are in the cart to the widget configuration

      • filters: [Recommendation.FilterApi.product('PRODUCT_VIEWED_ID')] – example for the product page

      • filters: [Recommendation.FilterApi.product('PRODUCT_IN_CART_ID1)'), Recommendation.FilterApi.product('PRODUCT_IN_CART_ID2')] – example for a shopping cart and two products

  • Optionally, you can add a price filter

    • Recommendation.FilterApi.minPrice('30') – e.g. if you want to display products not cheaper than 30

    • Recommendation.FilterApi.maxPrice('70') – e.g. if you want to display products that do not cost more than 70

Did this answer your question?