Smart Search – self-implementation

Find out how to implement Smart Search by yourself in your online shop.

The first step necessary to implement the services provided by QuarticOn is access to the Customer Panel. You can create an account yourself or contact us to provide login credentials.

1. Insert the QuarticOn script

Attach the main personalised script to the page code. This script, in a non-personalised form, looks like this:

<script type="text/javascript">
(function() {
var _qS = document.createElement('script');
_qS.type = 'text/javascript';
_qS.async = true;
_qS.src = '//qjs.quartic.pl/qjs/Customer_ID.js';
(document.getElementsByTagName('head')[0]||
document.getElementsByTagName('body')[0]).appendChild(_qS);
})();
</script>

The correct code, generated especially for you, can be downloaded from the Customer Panel. You can find instructions on how to do this here.

2. Share with us your products

We need to collect all information about your products for the search to work properly.

The easiest and recommended way is to provide us with an XML file (so-called feed) containing the full catalog of products from the shop. The second way is to use a crawler that will retrieve information from product pages in the shop.

Attention! After choosing how to share your product catalog, contact QuarticOn. Thanks to this information we will be able to configure the system accordingly.

a. Add product feed

We currently support feed in the popular Google Merchant standard. If your shop allows you to generate such a file, download its URL and insert it in the QuarticOn administration panel.

Detailed information on entering the feed into the system can be found here

Attention! Remember to select Quartic XML (AWS S3 / Lambda) as the directory format.

If you do not have a Google Merchant file, you can create your own XML with the structure below:

Name

Description

Comments

Requiredness / optionality

id

Product ID

Unique product identifier used in the shop, also in orders.

required

title

Title

Product name displayed in search.

required

status

Availability

Product available: status = 1, unavailable: status = 0.

required

price

Product price

Price should not include the  thousands separator.

required

price_old

Old price

Price should not contain a thousands separator, it should be higher than the current price. Leave it blank if it is missing.

optional

link

Product URL 

Link to the product page that will be displayed.

required

image

Image URL

Image URL that presents the product (usually the main product image).

required

categories

Product category path

Full path of the product category

We start numbering from 1.

Note #1: Categories must be ordered from the most general to the specific one, example of the category tree below.

Accessories -> Handbags -> Messenger bag

Note #2: Please skip the category "All products".

Note #3: Please attach only 1 category tree.

required

Example of implementation

<product>
<id>1234</id>
<title>My product name</title>
<status>1</status>
<price>12.99</price>
<price_old>20.49</price_old>
<link>https://mydomain.com/my-product-link/</link>
<image>https://static.mydomain.com/my-product-image.png</image>
<categories>Category 1 / Category 1.1 / Category 1.1.1</categories>
</product>

b. Describe your product

If you do not have access to the feed (the previous section contains information on its topic), we can collect information about the products using an automatic crawler.

Attention! Using a crawler does not guarantee that all products from your shop will be collected.

Crawler automatically downloads product data such as:

  • ID,
  • name,
  • availability,
  • price,
  • old price (before discount),
  • link to the product page,
  • image link,
  • categories,
  • additional attributes.

In order for crawler to automatically retrieve data from the site, add a container with id="qON_product" which contains product information provided using attributes. Attributes should be supplemented with values ​​adequate for the name, referring to a given product.

Description of attributes

Name

Description

Comments

Requiredness / optionality

data-qon-id

Product ID

Unique product identifier used in the shop, also in orders.

required

data-qon-title

Title

Product name displayed in search.

required

data-qon-status

Availability

Product available: status = 1, unavailable: status = 0.

required

data-qon-price

Product price

Price should not include the  thousands separator.

required

data-qon-old-price

Old price

Price should not contain a thousands separator, it should be higher than the current price. Leave it blank if it is missing.

optional

data-qon-link

Product URL 

Link to the product page that will be displayed.

required

data-qon-image

Image URL

Image URL that presents the product (usually the main product image).

required

data-qon-category-{Ordinal number}-id

Product category ID

Category ID (most often number or slug)

We start numbering from 1.

optional

data-qon-category-{Ordinal number}-title

Product category name

Full name of the product category

We start numbering from 1.

Note #1: Categories must be ordered from the most general to the specific one, example of the category tree below.

Accessories -> Handbags -> Messenger bag

Note #2: Please skip the category "All products".

Note #3: Please attach only 1 category tree.

optional

data-qon-attribute-{parameter name}

Additional parameter to search 

Parameter names may be different for different products (e.g. one product may have the parameter "colour", another "size" and another both).

optional

Example of implementation

<div class="qON_product" style="display:none"
data-qon-id="14645"
data-qon-title="Washing powder"
data-qon-status="1"
data-qon-price="19.99"
data-qon-old-price="24.99"
data-qon-link="http://strona.eu/washing-powder"
data-qon-image="http://strona.eu/powder.jpg"
data-qon-category-1-id="1"
data-qon-category-1-title="Detergent"
data-qon-category-2-id="11"
data-qon-category-2-title="Washing powder"
data-qon-attribute-size="S,M,L"
data-qon-attribute-color="red"
data-qon-attribute-producer="Henkel"
>
</div>

Important!

The above element must be available with JavaScript disabled, i.e. directly in the source of the page.

The category page should also include the following in the page code:

  • Option nr 1: container with id = "qON_category", which contains containers (.qON_product) with information about products in a given category. This information should be provided in the appropriate attributes:

Date Attribute

Value

Example 

data-qon-id

Product ID

data-qon-id="abc12345"

data-qon-link

Product URL

data-qon-link="https://www.shopslink.com/productslink"

Example of implementation

<div id="qON_category" style="display:none">
<div class="qON_product" style="display:none"
data-qon-id="abc12345"
data-qon-link="https://www.shopslink.com/productslink1">
</div>
<div class="qON_product" style="display:none"
data-qon-id="abc56789"
data-qon-link="https://www.shopslink.com/productslink2">
</div>
</div>
  • Option nr 2: the appropriate ID, class and attributes should be added to the existing product listing on the category page.

    Add id = "qON_category" to the container in which the products are located. 

    Add .qON_product and the completed data-qon-id and data-qon-link attributes to the container for each individual product.

Unlock the QuarticOn crawler

Our servers download the content of your shop pages and read product information from them. For the process to be effective, we need to be sure that your shop will not block the crawler.

We recommend contacting the administrators and unblocking (whitelisting) traffic from the addresses and userAgents given below.

Remember that our system will make as many calls to your e-shop per day as the number of products you have in your offer. In case you have more than 20,000 SKU – this may be relevant to your system. By default, we will make requests so that each product is loaded once a day: for 20,000 products – this is, on average, one pageview / 4 seconds.

Crawler name (userAgent)

userAgent: QuarticON.com (recommendation engine for e-shops) Crawler

IP addresses

The current IP address pool is available in the Help Center: https://help.quarticon.com/crawler

3. Enter transaction tracking (recommended)

Thanks to transaction tracking, you get additional information on the effectiveness of website search. In the customer panel we will show you which phrases and which products generate:

  • best conversion,
  • the most numerous sales,
  • top sales

from search.

On the thank you page, add the following script to the page code. We add changes at the end of the <body> </body> section:

<script type="text/javascript">
var upsParams = upsParams || [];
upsParams.push(['transaction', 'SCRIPT_TRANSACTION_ID']);
upsParams.push(['user','SCRIPT_USER_ID']);
/* SCRIPT_LOOP_START*/
upsParams.push(['action','purchase']);
upsParams.push(['product','SCRIPT_PRODUCT_ID']);
upsParams.push(['price','SCRIPT_PRICE']);
upsParams.push(['quantity','SCRIPT_QUANTITY']);
upsParams.push(['execute']);
/* SCRIPT_LOOP_END */
</script>

The script collects and processes the following dynamic variables:

  • transaction – the unique ID of the transaction registered in the shop,
  • user – the ID of the user who made a purchase; if the user is not logged in, pass the empty value (upsParams.push(['user', '']);),
  • product – a unique product ID that matches the ID provided in the product tag,
  • price – the price of the product,
  • quantity – the number of product pieces.

To ensure the script works correctly, the appropriate variables must be passed:

  1. SCRIPT_TRANSACTION_ID – unique transaction ID
  2. SCRIPT_USER_ID – specifying the variable is optional; if user_id is available after logging into the shop as a customer, insert it here, if not, leave the string empty
  3. /* SCRIPT_LOOP_START */ – here you need to create a loop that will jump over all purchased products and extract the following data from them:
    1. SCRIPT_PRODUCT_ID – unique product ID, must match the catalog data
    2. SCRIPT_PRICE – unit price of the product
    3. SCRIPT_QUANTITY – the number of purchased pieces of a given product
  4. /* SCRIPT_LOOP_END */ – end of the loop

Important!

The consistency of product ID throughout the shop is the foundation of analytics quality. Therefore, the product ID should be unambiguous and unique, assigned to only one product. The product should appear in the entire system under the same ID.

Product variant support

By product variants we mean the same product in different versions, e.g. Viksta cabinet in different colours. White and black cabinet are two different variants of the same product.

  • If the choice of variant entails a change of product ID and URL, then each variant is treated as a separate product.
  • If the selection doesn’t change the product ID, all variants are treated as one product, regardless of the chosen variant.

4. Add search engine to the site

When you don't have a search engine

Where you want the search box to appear, add the code:

<div class="qon-tiny-smart-search" />

When you want to change the search engine

In this case, delete the current search box and add an item:

<div class="qon-tiny-smart-search" />

Then it can be styled according to the guidelines from the section Customise visualisation (optional).

5. See search engine preview

Contact QuarticOn and tell us that the place for the search engine is ready. Then, we will provide you with information on how to test the search engine and you will be able, for example, to adapt its visualisation to your needs. 

6. Customise visualisation (optional)

Our search engine goes to you along with the default template. However, if you want, you can customise the appearance of individual elements to your needs.

To do this, override CSS styles for selected classes describing search engine pieces. Below, for your convenience, you will find a list of elements forming individual parts of the search engine together with HTML code.

Main elements

The search engine consists of two basic elements that are divided into smaller parts.

  • Autocomplete container – so-called small search engine which we usually place in the page header. Consists of:
    1. search box with button,
    2. loader,
    3. handy search results.

  • Search result container (SERP – search engine result page). Consists of:
    1. a headline with information about the searched phrase and the number of results,
    2. a sidebar to narrow down your search results,
    3. search result lists with pagination options.

Customising the look

Below you will find the HTML code with a description of the elements and classes used in the templates listed above.

Autocomplete container

<div class="qon-tiny-smart-search">
<div class="autocomplete-search-container">
<input type="search" autocomplete="off" placeholder="
Enter the search phrase" class="autocomplete-search-input">
<button type="button" class="autocomplete-search-button">Search</button>
</div>

<div class="loader-container">
<div class="loader"></div>
</div>
<div class="results-container">
<div class="results-element">
<article class="single-search-result">
<a href="${product.link}" class="link qon-click-link">
<div class="card">
<div class="card-image">
<img src="${image}" class="image" alt="${product.title}">
</div>
<div class="card-content">
<h1 class="title">${product.title}</h1>
<p class="price">${product.price} ${product.currency}</p>
</div>
</div>
</a>
</article>
<div class="card">
<a class="more-results-link">See more search results</a>
</div>
</div>
</div>
</div>

Class

Description

.qon-tiny-smart-search

Main container of the small auto-complete search engine.

.autocomplete-search-container

Parent container containing elements that allow searching for a phrase, i.e. input and button.

.autocomplete-search-input

Input class for entering the search phrase.

.autocomplete-search-button

Class of the button used to invoke the search action.

.loader-container

Loader class that shows when search results are loading.

.results-container

Main result container which contains elements found after entering the phrase. Visible after the small search engine finds products that match the query.

.results-element

Parent container entwining the search results.

.single-search-result

Product container with search details.

.link .qon-click-link

Element that allows you to move to the selected product page after clicking.

.card

Container entwining product details.

.card-image

Container class in which the product image will be located.

.image

Class of the main element of the image in which the link to the specific product image will be placed.

.card-content

Product detail container.

.title

Class of the element containing the product title.

.price

Class of the element containing the price of the product.

.more-results-link

Class of the element that moves to the advanced search page.

SERP container

<section class="qon-smart-search">
<h1 class="result-header">
<span class="search-label">Search results for</span>
<span class="qon-smart-search-result search-phrase">suitcase</span>
<span class="result-count search-result">(351 results)</span>
</h1>
<header class="serp-search-container">
<input type="search" autocomplete="off" placeholder="what are you looking for" class="serp-search-input">
<button type="button" class="serp-search-button">Search</button>
</header>
<aside class="qon-filters-wrapper" style="display: flex;">
<div class="qon-filters-header-container">
<h2 class="qon-filters-header">Filter</h2>
</div>
<button class="show-filters active">Filter</button>
<button class="hide-filters">×</button>
<button class="show-results">Show products</button>
<button class="remove-filters" style="display: none;">
<span>Clear filters</span>
</button>
<nav class="qon-filters-container">
<div class="filter-group category0-group">
<h2 class="filter-group-title">Category</h2>
<ul class="qon-filters-list">
<ul class="filters-list">
<li class="filters-item">
<label class="qon-smartsearch-checkmark-container">
<input type="checkbox" class="single-filter">
<span class="qon-smartsearch-checkmark"></span>
<span class="text">Luggage</span>
<span class="filters-item-count">(351)</span>
</label>
</li>
</ul>
</ul>
</div>
<div class="filter-group price-group">
<h2 class="filter-group-title">Cena</h2>
<form class="qon-price-filters-form">
<input type="text" class="qon-filters-item-min" placeholder="From" value="">
<input type="text" class="qon-filters-item-max" placeholder="To" value="">
<button style="display: none" type="submit">Submit</button>
</form>
</div>
</nav>
</aside>
<div class="results-container">
<div class="sort-container" style="display: flex;">
<label class="sort-label">Sort:</label>
<div class="sort-element-wrapper">
<select class="sort-element ">
<option value="default">By default</option>
<option value="titleAsc">Alphabetically - From A to Z</option>
<option value="titleDesc">Alphabetically - From Z to A</option>
<option value="priceAsc">Price going up</option>
<option value="priceDesc">Price going down</option>
</select>
</div>
</div>
<div class="results-element">
<article class="single-search-result">
<a href="${product.link}" class="link qon-click-link">
<div class="card">
<div class="card-image">
<img src="${image}" class="image" alt="${product.title}">
</div>
<div class="card-content">
<h1 class="title">${product.title}</h1>
<p class="price">${product.price} ${product.currency}</p>
</div>
</div>
</a>
</article>
</div>
<div class="pagination-container">
<a href="#" class="single-page active single-page-number" data-page="0">1</a>
<a href="#" class="single-page single-page-number" data-page="1">2</a>
<a href="#" class="single-page next-page">&gt;</a>
</div>
</div>
</section>

 

Class

Description 

.qon-smart-search

Main container of a large search engine, placed inside a pop-up showing all search results.

.result-header

Container containing details for the search phrase.

.search-label

Class of the element containing the message content before the search phrase.

.qon-smart-search-result.search-phrase

Class of the element in which the search phrase is placed.

.result-count.search-result

Class of the element that contains the number of results found.

.serp-search-container

Additional search engine container.

.serp-search-input

Additional search engine input class.

.serp-search-button

Additional browser button class.

.qon-filters-wrapper

Advanced filter container.

.qon-filters-header-container

Main filter header container.

.qon-filters-header

Class of the main element of the filter header.

.show-filters.active

Button class showing filters. Visible only on the mobile version, after clicking on the element it will take the .active class and show a pop-up with a filter container.

.hide-filters

Class of the button closing pop-up filters on the mobile version.

.show-results

Button class that hides the pop-up window and applies the selected filters.

.remove-filters

Button class that resets the set of selected filters. Hidden by default if none of the filters has been selected.

.qon-filters-container

Container of advanced filters, where filter groups are found. 

.filter-group

Container wrapping a group of filters.

.filter-group-title

Filter group header element class.

.qon-filters-list

Filter list container.

.filters-list

Filter container with first nesting level.

.filters-item

Container entwining a single filter.

.qon-smartsearch-checkmark-container

Container of the element entwining the filter input.

.single-filter

Class of the input element that applies the filter after it is clicked.

.text

Class of the element containing the filter content.

.filters-item-count

Class of the element containing the number of filter instances in a given search.

.qon-price-filters-form

Form class that allows filtering by price.

.qon-filters-item-min

Input class with a minimum price.

.qon-filters-item-max

Input class with a maximum price.

.results-container

Main container of search results.

.sort-container

Main container containing sorting items.

.sort-label

Header class containing the sort message content. 

.sort-element-wrapper

Container containing a sorting element.

.sort-element

Class of the select element that accepts sorting values. 

.results-element

Parent container entwining the search results.

.single-search-result

Product container with search details.

.link .qon-click-link

Element that allows you to move to the selected product page after clicking.

.card

Container entwining product details.

.card-image

Container class in which the product image will be located.

.image

Class of the main element of the image in which the link to the specific product image will be placed.

.card-content

Product detail container.

.title

Class of the element containing the product title.

.price

Class of the element containing the price of the product.

.pagination-container

Container containing pagination elements.

.single-page

Pagination element class applied to all elements that relate to individual pages.

The default template style sheet can be found here: 

https://cdn.quartic.com.pl/search/css/base.css

The template structure is fixed for the mobile and desktop versions, and adaptation to different sizes of devices is based on @media queries. 

7. Start off!

At this stage, we are ready to start. Contact QuarticOn and confirm that we can enable Smart Search for all users of your e-shop.

8. Go to the panel: analyse the results, add synonyms

Log in to: https://cp.quarticon.com/qonpanel/login/?selectLang=en 

Analytics

In the Customer Panel, you can not only track search engine results, e.g. the number of searches, the most popular phrases and products. Thanks to CTR, conversion and sales data, you can easily draw conclusions and optimise the marketing activities of your shop (e.g. advertising campaigns, remarketing).

Data are presented broken down into searches with autocomplete and SERP in any time range.

  • On the desktop, you will find charts:
    • number of searches;
    • most popular phrases;
    • autocomplete vs SERP;
    • phrases with the highest sales;
    • phrases without results;
    • phrases with the most sales;
    • most frequently clicked phrases.

Zrzut ekranu 2020-04-02 o 14.05.13

  • In the phrase report, you will find:
    • phrase CTR,
    • conversion,
    • number of performed transactions, as well as the volume and value of search sales.

Zrzut ekranu 2020-04-02 o 14.05.32

  • The product report includes:
    • the number of views, clicks, CTR and conversion of each product that was found in the search results,
    • the number of transactions carried out, as well as the volume and value of product sales.

Zrzut ekranu 2020-04-02 o 14.05.47

Synonyms

Thanks to the phrase synonymisation function, you will quickly increase the search efficiency in your shop.

How to use it? If you see frequent repetitive phrases in search statistics that have no results, add a synonym for them. E.g. users search for the phrase "pendant", meanwhile, all pendants in your shop have the professional name "necklace" in the product name. "Pendant" gives zero results in the search engine. Just add a new synonym, enter "pendant" as the base word and "necklace" as a synonym.

From now on typing "pendant" in the search engine will return search results for "necklace" revealing the full range of your products to users.

8. Start Search

The user searches and you view their activities in the Customer Panel and optimise your shop based on this data.