Open navigation

Theme Modifications for JSv2 / OS1 (Debut)

These instructions are for stores using the latest version of our JavaScript library (v2) 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 Page Template

First create the SRLP template by clicking Add a new template under the Templates heading, with the following details

Create a new template for

page

Template type

liquid

File name

page.klevu-search-results.liquid

Add the following code to this template

<div class="page-width">
  <h1>{{ page.title }}</h1>
  <div class="klevuLanding"></div>
</div>

Create the Search Results Page

Under Online Store > Pages, create a new page with the title “Search Results” using the Theme template you just created (klevu-search-results)

The content of this page should be empty, and the page should be visible.

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-quick-search-theme.liquid

Then we create the klevu-quick-search-theme.liquid file using the content here: snippets/klevu-quick-search-theme.liquid 

This file will attach Klevu functionality to the quick search input, and render output of the search results landing page created earlier.

You will need to replace some values in this file to connect to your Klevu account correctly.

  • First, replace the options.search.url value with the APIv2 Cloud Search URL found in your KMC account on the Store Info page.
  • Second, 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.
  • Finally, 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-quick-search-theme' %}
    <!-- 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

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 1 theme (Debut), the easiest way to disable these suggestions is via 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.

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 product cards works as expected.

You should not need to make any changes to the content of this template.

klevu-catnav-theme.liquid

 Then we create the klevu-catnav-theme.liquid file using the content here: snippets/klevu-catnav-theme.liquid

This file will include the JavaScript file (hosted by Klevu) responsible for rendering the collection page template, as well as defining the current category name for use in analytics.

You should not need to make any changes to the content of this template.

Update Your Theme Files

layout/theme.liquid

Within your overall theme file, we need to inject both the Klevu JS Library and include the snippet templates created above. In Layout > theme.liquid, add the following

<script src="//js.klevu.com/core/v2/klevu.js"></script>
    <!-- Start klevu-snippets DO NOT EDIT -->
    {% include 'klevu-add-to-cart' %}
    {% include 'klevu-catnav-theme' %}
    <!-- 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.
templates/collection.liquid

Next, we replace the existing collection template’s content with our own markup, consisting of a single empty div element into which the Klevu JavaScript will inject content.

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

<div class='klevuLanding'></div>

templates/collection_klevubackup.liquid

This file is generated during automatic integration and contains the content of the collection.liquid template at the point of being replaced. This allows the application to revert our changes if Theme layout is disabled.
This file is not required for manual integration, as Shopify’s change history will allow you to roll back to the previous version of the file.

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.