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:
The plugin itself is located here:
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:
set and verified product catalogue; more about preparing the catalogue can be found in the article Product catalogue in the XML file format
prepared widgets with preset recommendation logics; you can read more about the recommendation logics and strategies in:
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 systemHOST_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
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).
The product IDs provided to us must match those in the product catalogue.
In order for the system to learn, we need information about user's all types of behaviour:
An example of a user behaviour path on the e-shop's website
The user enters the home page
on the home page, the user sees a recommendation frame with the title Recommended for you
The user enters the product page
information about the product display is sent to the QON system
The user clicks on the QON recommendation frame displaying similar products
information about a click on the product is sent to the QON system
The user adds the product clicked from the QON frame to the shopping cart
The user purchases this product
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 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 categoryfilters: [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 pagefilters: [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 30Recommendation.FilterApi.maxPrice('70')– e.g. if you want to display products that do not cost more than 70