Open navigation

Theme Modifications for JSv1 / OS1 (Debut)

These instructions are for stores using the legacy version of our JavaScript library (v1) and a legacy Shopify theme.
To determine which version of the Klevu library your store is using, please log into your KMC account and check the JS Theme Version value on the Store Info page
You can check whether your Shopify theme is an older version by clicking Edit Code under the Actions dropdown for you active theme and looking under the Templates heading.
If your theme contains collection.liquid and product.liquid instead of collection.json and product.json files, then you are using a Shopify 1 theme.

Smart Search

The Smart Search integration hooks into your site’s existing search field to provide Klevu-driven quick search suggestions as your customers type, as well as adding a new search results page powered by our JavaScript library. Note that we do not offer an option to preserve your Shopify layout for search results at this time.

The Klevu app attempts to make the following changes automatically when enabling Smart Search via the Settings page. If you are installing Klevu on an unpublished theme, or encounter any errors during installation, you can follow the below instructions to ensure all the templates in your theme have been updated accordingly.

Search Results Landing Page

Create the Search Results Page

Under Online Store > Pages, create a new page with the title “Search Results” using the “Default page” Theme template

Add the following page content as HTML by clicking the View Code button and pasting the markup directly.  Page Content: search-results
Ensure that the page is visible.

Template Changes

Update Your Theme Files

layout/theme.liquid

Within your overall theme file, we need to inject the Klevu JS library.
Add the following snippet within the <head> section of your code.


<script src="//js.klevu.com/klevu-js-v1/js/klevuScript.js?klevuapi=klevu-1234567890&lang=en"></script>
</head>

You will need to replace the klevuapi value in the above snippet with the JS API Key value found in your KMC account on the Store Info page.
You will also need to replace the lang value with the two-character language code for your store (for example, “EN”)

Note: during automatic installation, you will not find this script injected into a template file directly, though it will be output by Shopify on your storefront.
You should only add this to the template if you have not used our automatic integration, or if an error was encountered when adding this asset.

Additional Actions

Disable Native Quick Search Autocomplete

Depending on which theme you are using, you may already be outputting search suggestions in the quick search input.
Different themes will control this functionality in different ways, and your developers should be able to help you disable this either through configuration settings or template changes.

For the native Shopify Online Store 1.0 theme (Debut), the easiest way to disable these suggestions is vcia the Customize option for your Current theme (under Online Store > Themes).
This will take you to visual editor, where you should select the Theme Settings section and then deselect the “Enable product suggestions” option under Search

Smart Category Merchandising - Klevu Theme

When using Klevu Theme for the Smart Category Merchandising integration, the native Shopify collection page is replaced by our JavaScript-powered template, which injects the HTML and CSS required to display relevant products and filters to your customers.

The Klevu app attempts to make the following changes automatically when enabling Smart Category Merchandising via the Settings page, and selecting the “Use Klevu theme” option. If you are installing Klevu on an unpublished theme, or encounter any errors during installation, you can follow the below instructions to ensure all the templates in your theme have been updated accordingly.

Please note, you must also integrate Smart Search in order for Smart Category Merchandising using Klevu Theme to work with the legacy Klevu theme.

Template Changes

Update Your Theme Files

templates/collection.liquid

We replace the existing collection template’s content with our own markup, containing the HTML markup into which the Klevu JavaScript will inject product listings.
You should not need to make any changes to the content of this file, though you may want to implement your own changes to better suit your site style. Your developers will be able to assist with this.

Open Templates > collection.liquid and replace the entire contents with the following

<div class='kuContainer' id='kuMainContainer'><div id='ku-search-form' class='ku-search-block-full' style='display:none;'><form action='/pages/search-results' method='get' role='search'><input type='search' name='q' id='ku-search-field' class='ku-searchfield' placeholder='Search text'><input type='button' title='Search' id='ku-search-btn' value='' class='ku-search-btn'></form></div><div class='klevu-clear-both'></div><div id='loader' style='text-align:center'><img src='https://js.klevu.com/klevu-js-v1/img-1-1/ku-loader.gif' alt='Loading...'/></div><div class='kuNoRecordFound' id='kuNoRecordFound' style='display:none;'><p>No matching products found.</p></div><div class='kuProListing' id='kuProListing' style='display: none;'><div class='kuFilterHead kufilter-label' id='klevuNarrowByLabel'>Narrow By</div><div class='kuFilters' id='kuFilters'></div><div id='ku-search-filter-tags'></div><div class='kuResultList' id='kuResultListBlock'><div class='kuResultInfo'><div class='kuTotalResultsTab' id='kuTotResults'><div class='kuTabs' id='kuTabs'></div></div><div class='kuPagination' id='kuPagination1'></div><div class='kuPagination' id='kuPagination3' style='display:none;'></div><div class='kuClearBoth'></div></div><div class='kuProductContent' id='kuProductContent'><div class='kuSortHeader'><div class='kuSortingOpt'><div class='kuSortby'><label id='klevuSortLbl'>Sort by:</label><select name='kuSortby' id='kuSortby' onchange='klevu_changeSortingOptionsForLandigPage(this.value);'><option value='rel' id='klevuRelSort'>Relevance</option><option value='lth' id='klevuLthSort'>Price: Low to high</option><option value='htl' id='klevuHtlSort'>Price: High to low</option></select></div><div class='kuPerPage'><label id='klevuItemsPerPage'>Items per page:</label><select onchange='klevu_changeItemsPerPage(this.value);' id='noOfRecords1'><option>24</option><option>36</option>
            <option>48</option></select></div><div class='kuView'><a class='kuGridviewBtn kuCurrent' href='#' id='gridViewBtn' onclick='setKuViewGrid()'><span class='icon-gridview'></span></a><a class='kuListviewBtn' href='#' id='listViewBtn' onclick='setKuViewList()'><span class='icon-listview'></span></a></div><div class='kuClearLeft'></div></div></div><div class='kuGridView' id='kuResultsView'></div><div class='kuBottomPagi'><div class='kuPerPage'><label id='klevuItemsPerPageFooter'>Items per page:</label><select onchange='klevu_changeItemsPerPage(this.value);' id='noOfRecords2'><option>24</option><option>36</option><option>48</option></select></div><div class='kuPagination' id='kuPagination2'></div><div class='kuClearBoth'></div></div></div><div class='kuOtherContent' id='kuOtherContent'><div class='kuSortHeader'><div class='kuSortingOpt'><div class='kuPerPage'><label id='klevuItemsPerPageCms'>Items per page:</label><select onchange='klevu_changeCmsItemsPerPage(this.value);' id='noOfRecords3'><option>24</option><option>36</option><option>48</option>
            </select></div><div class='kuClearLeft'></div></div></div><div class='kuListView kuOtherContentView' id='kuOtherContentView'></div><div class='kuSortHeader'> <div class='kuSortingOpt'><div class='kuPerPage'><label id='klevuItemsPerPageCmsFooter'>Items per page:</label><select onchange='klevu_changeCmsItemsPerPage(this.value);' id='noOfRecords4'><option>24</option><option>36</option>
            <option>48</option></select></div><div class='kuPagination' id='kuPagination4'></div><div class='kuClearLeft'></div></div></div></div></div><div class='kuClearBoth'></div></div></div><input id='noOfRecords' type='hidden' name='noOfRecords' value='24' /><input type='hidden' name='startPos' id='startPos' value='0'/><input type='hidden' name='totalResultsFound' id='totalResultsFound' value='0'/><input type='hidden' name='searchedKeyword' id='searchedKeyword' value=''/><input type='hidden' name='totalPages' id='totalPages' value='0'/><script type='text/javascript' src='https://js.klevu.com/klevu-js-v1/js-1-1/klevu-landing.js'></script><script> var klevu_collectionProductPath = '{{ collection.url | escape }}'; </script><script>function GetURLParameter(sParam){var sPageURL = window . location . search . substring(1);var sURLVariables = sPageURL . split('&');for (var i = 0; i < sURLVariables . length; i++){var sParameterName = sURLVariables[i] . split('=');if (sParameterName[0] == sParam) { return decodeURIComponent(sParameterName[1]);}}} var q = GetURLParameter('q'); </script><script>var klevu_pageCategory;var klevuquery='';var klevucountslash;if(q==''||q==null){klevu_pageCategory='{{ collection.title | escape }}';klevucountslash=window.location.pathname.split('/').length;if(klevucountslash==4){var klevutags=window.location.pathname.split('/').pop().split('+');for(i=0;i<klevutags.length;i++){klevuquery+='tags:';klevuquery+=klevutags[i]+';;'}if(klevuquery!==''){var klevu_userLandingFilterResults=klevuquery.slice(0,-2)}}}else{klevu_pageCategory='';var attribute_key=window.location.pathname.split('/').pop();if(attribute_key=='vendors'){attribute_key='brand'}if(attribute_key=='types'){attribute_key='type'}var klevu_userLandingFilterResults=attribute_key+':'+q }</script>
templates/collection_klevubackup.liquid
This file is generated during automatic integration and contains the content of the collection.liquidtemplate at the point of being replaced. This allows the application to revert our changes if Theme layout is disabled.

Smart Category Merchandising - Preserve Shopify Theme

Integrating Smart Category Merchandising using the Preserve Shopify Theme option retains the look and feel of your own theme. While there are no frontend display changes to implement, we need to include some code to ensure the necessary analytics calls are sent to Klevu.

The Klevu app attempts to make the following changes automatically when enabling Smart Category Merchandising via the Settings page, and selecting the “Preserve Shopify theme” option. If you are installing Klevu on an unpublished theme, or encounter any errors during installation, you can follow the below instructions to ensure all the templates in your theme have been updated accordingly.

Template Changes

Create the Klevu Snippets Files

We need to create four new templates under Snippets > Add a new snippet

klevu-pl-analytics.liquid

The first template should be called klevu-pl-analytics.liquid and contain the content found here: snippets/klevu-pl-analytics.liquid
This file contains analytics functions and the necessary JSv2 power-up calls to initiate tracking functionality.
You will need to replace some values in this file to connect to your Klevu account correctly

  • First, replace all references to “your Klevu JS API Key” (klevu-1234567890 in the boilerplate code) with the JS API Key value found in your KMC account on the Store Info page.
  • Second, check that the Analytics URL value in your KMC account (on the Store Info page) is one of stats.klevu.com or stats.ksearchnet.com. If it is not, please replace the analytics and analyticsCat domains with the value in KMC

klevu-pl-collection.liquid

Next create klevu-pl-collection.liquid using the code here: snippets/klevu-pl-collection.liquid
This template is store and send data about visited categories.
You should not need to make any changes to the content of this template.

klevu-pl-collection-product.liquid

Create klevu-pl-collection-product.liquid from the following snippet: snippets/klevu-pl-collection-product.liquid
This short JavaScript code is injected to each product card, and allows us to track which products were viewed on a page.
You should not need to make any changes to the content of this template.

klevu-pl-product.liquid

Finally, create klevu-pl-product.liquid with the content here: snippets/klevu-pl-product.liquid
This snippet will be injected into a product display page in order to track product clicks.
You should not need to make any changes to the content of this template.

Update Your Theme Files

Layout > theme.liquid

Within your main theme file, we inject the core Klevu JS library. 

Add the following snippet within the <head> section of your code.

<script src="//js.klevu.com/core/v2/klevu.js"></script>
</head>
You should ensure that the klevu.js script is only included once, and that it appears before any injected snippets.
If any Klevu snippets are already present (ie, as a result of other integrations), do not remove these.
Templates > collection.liquid

We add the following to the bottom of this template, so we can detect when a customer is browsing a category and send the necessary analytics calls to Klevu.

<!-- Start klevu-pl-collection -->
{% section 'klevu-pl-collection' %}
<!-- End klevu-pl-collection -->

<!-- Start klevu-pl-analytics -->
{% section 'klevu-pl-analytics' %}
<!-- End klevu-pl-analytics -->
Templates > product.liquid

We add the following to the bottom of this template, so we can detect when a product has been clicked on from a category page, and send the necessary analytics calls to Klevu.

{% render 'klevu-pl-product', product: product %}
{% render 'klevu-pl-analytics' %}
Update the Product Card Snippet
This is the most technically complex integration step, and you may need your developers to advise you.

Example(s) in Debut: snippets/product-card-grid.liquid and snippets/product-card-list.liquid

Finally, we need to add a snippet to the file(s) responsible for rendering product cards in your category page.
Different themes use different names for these files, and there may be more than one responsible depending on the different layouts available in your theme. You can usually recognise these files when scanning the entries in the Snippets section, and looking for names containing the words “product” and “card”. Some examples used by Shopify themselves include

  • Snippets > card-product.liquid
  • Snippets > product-card.liquid
  • Snippets > product-card-grid.liquid
  • Snippets > product-card-list.liquid

Locating the Correct File
If the template is not obvious, you may need to look at other templates' code to help you identify the correct file.

Open the Templates > collection.liquid file and locate the section of code which loops over and outputs the individual products. 
You may find your collection.liquid file includes other templates to handle the rendering. In which case, open the relevant template(s).

  • If you see {% section '...' %}, then you need to look for the template in the Sections area
  • If you see {% include ‘...' %} or {% render '...' %}, then you need to look in the Snippets area

In the native Debut theme, we see the following

{% comment %}
  The contents of the collection.liquid template can be found in /sections/collection-template.liquid
{% endcomment %}
{% section 'collection-template' %}

When you have the correct template, you should find a snippet similar to

{% for product in collection.products %}
    <li class="grid__item grid__item--{{section.id}} {{ grid_item_width }}">
        {% include 'product-card-grid', max_height: max_height, product: product, show_vendor: section.settings.show_vendor %}
    </li>

The string after include (or render - see not above) tells us which snippet template we need to modify. In the example above, that would be Snippets > product-card-grid.liquid

You may find multiple instances where a card is rendered within the same loop, for example for grid and list views. You will need to make the following changes in all these templates.
In Debut, for example, you will find both product-card-grid and product-card-list used.
Important: make a note of the product: product assignment in the {% render ... code - we need to know the name of the variable being passed to the snippet so we can use this in our code.
The variable name is the part before : product - in this case, product
Update the Product Card Code

Finally, we open product card template itself and add the following lines at the end of the file


    <!-- Start klevu-pl-collection-product -->
{% render 'klevu-pl-collection-product', product: product %}
<!-- End klevu-pl-collection-product -->
If the variable name above is not product then make the applicable change in the code snippet.
For example, in older versions of Dawn the line should be
{% render 'klevu-pl-collection-product', product: product_card_product %}

Additional Actions

Enable Preserve Layout Service

In order to display products in the correct order, our backend services will periodically update your collection order. To do this, we need to be notified that your site’s collections should be managed in this manner.

When using the automated integration through our app, this service will be enabled or disabled automatically as applicable. If you are integrating manually, however, please contact our support team to make the required change.

For more information about this service, please see our guide here.

Smart Recommendations

The Smart Recommendations integration updates your theme to allow rendering of Klevu-powered recommendations banners configured in the Merchant Center.
Note that the following changes will not output any content to your site until you embed one or more HTML snippets (provided within the KMC) into your site. These snippets can be dropped into any template, and will not render output unless the steps below are in place.

The Klevu app attempts to make the following changes automatically when enabling Smart Search via the Settings page. If you are installing Klevu on an unpublished theme, or encounter any errors during installation, you can follow the below instructions to ensure all the templates in your theme have been updated accordingly.

Template Changes

Create the Klevu Snippets Files

We need to create two new templates under Snippets > Add a new snippet.

klevu-add-to-cart.liquid

The first template we create should be called klevu-add-to-cart.liquid and contain the content found here: snippets/klevu-add-to-cart.liquid
This file will ensure that the JavaScript functionality required for Add To Cart buttons in your search results works as expected.
You should not need to make any changes to the content of this template.

klevu-metadata.liquid

Next we create the klevu-metadata.liquid file using the content here: snippets/klevu-metadata.liquid
This file will output some JavaScript variables on different pages which are used to provide context when generating recommendations results. 
You should not need to make any changes to the content of this template.

klevu-recommendations.liquid

Finally, create the klevu-recommendations.liquid file from the content here: snippets/klevu-recommendations.liquid 
This file will power-up the recommendations module, which retrieves and renders your banners.
You will need to replace some values in this file

  • Replace all references to “your Klevu JS API Key” (klevu-1234567890 in the boilerplate code) with the JS API Key value found in your KMC account on the Store Info page.

If you need to make any customisations to your quick search or search results page behaviour, this should be included in this file.

A reference to some common changes can be found in this guide.

Update Your Theme Files

layout/theme.liquid

Within your overall theme file, we need to inject both the Klevu JS Library and include the templates created above. In Layout > theme.liquid, add the following code immediately before the closing </head> tag (included for reference)

<script src="//js.klevu.com/core/v2/klevu.js"></script>
    <!-- Start klevu-snippets DO NOT EDIT -->
    {% include 'klevu-add-to-cart' %}
    {% include 'klevu-metadata' %}
    {% include 'klevu-recommendations' %}
    <!-- End klevu-snippets DO NOT EDIT -->
</head>
You should ensure that the klevu.js script is only included once, and that it appears before any injected snippets.
If any other Klevu snippets are present (ie, as a result of other integrations), do not remove these, but ensure you do not include the same snippet multiple times.

Additional Actions

Embed Your Recommendations Banners

First locate the embed code from KMC, which can be found under Recommendations > Recommendations and clicking on the “code” icon. This will provide an HTML snippet in the form

<div class="klevu-recs" id="ABC-123"></div>

or

<div class="klevu-recs" klevu-data-id="ABC-123"></div>

You can then inject this snippet anywhere that HTML is permitted in your store, including theme templates; pages; or product description (remember to switch to code view first).

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.