Theme Modifications for JSv2 / OS1 (Debut)

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

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.

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.

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

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>

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

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.

 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

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>

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

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

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

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.

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.

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

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>

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 -->

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

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

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).

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

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 -->

{% 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.

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.

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.

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

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>

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).