Open navigation

Integration Troubleshooting and FAQs

How Do I…

Update Klevu Initialisation Settings?

Klevu core JS is initialised after the page has finished its initial rendering, meaning settings can be configured at any point prior to the "DOMContentLoaded" event firing.
Settings should be added to the "klevuSettings" global JavaScript object (with a check and declaration if the object does not yet exist) via a Custom Liquid block (if using Theme Editor) or within a template file (if editing the code directly).

Example

<script>

    if (typeof klevuSettings === "undefined") {

var klevuSettings = {};
}

    if (typeof klevuSettings.search === "undefined") {

klevuSettings.search = {};
}
klevuSettings.search.minChars = 3;
</script>
// OR
<script>

    if (typeof klevuSettings === "undefined") {

var klevuSettings = {};
}
klevuSettings.search ??= {};

    klevuSettings.search.minChars = 3;

</script>


Embed Search Results on a CMS Page?

First, create a new Page template via the Theme Editor.

Next, create a new CMS page and assign the template you just added.

CMS Pages are not associated with a specific theme in Shopify, but can only have a single Theme template. As such, you will need to ensure that the new template you have created is available in all themes on which you are integrating Klevu (including live and development). This is especially important as when a page is made visible, it is made visible in all themes - including your production storefront.

This is especially important as when a page is made visible, it is made visible in all themes - including your production storefront.
Finally, inject the Klevu Search Results block into the new template

Remember to enable the Klevu Javascript embed and set the Search Results Landing Page to the appropriate value (eg “/pages/search-results”).

Embed Search Results on a Custom Route?

Klevu Search Results blocks can only be added to Search or Page templates via the Theme Editor; for any other route, please consult with your developers.

They will need to include the following HTML on the desired page

<div class="klevuLanding"></div>

Remember to enable the Klevu Javascript embed and set the Search Results Landing Page to the appropriate value.

Selectively Enable Smart Category Merchandising by Collection?

First, create a new Collection template via the Theme Editor

Next, replace the native Product grid with a Klevu Collection Results block in any templates which should be powered by Klevu.

Finally, assign collections to the relevant templates accordingly.

Collections are not associated with a specific theme in Shopify, but can only have a single Theme template. As such, you will need to ensure that the new template you have created is available in all themes on which you are integrating Klevu (including live and development).

This is especially important as when a collection is made visible, it is made visible in all themes - including your production storefront. 

Override global Klevu configuration for different markets?

Select the market on which you wish to add overrides in the Theme Editor

Add a Custom Liquid block to the page containing your overrides (see “How Do I Update Klevu Initialisation Settings?”)

As you must add overrides for each market independently, if you are making a change which applies to the majority of markets, it may be more efficient to make the change to the base template and remove the customization selectively.

Override solution settings/layout for different markets?

Navigate to the relevant templat1e in the Theme Editor and select the market on which you wish to add overrides

Update the template and save; modified blocks and sections will be highlighted in the editor

Integrate Smart Category Merchandising using Preserved Layout?

Preserve Shopify Layout is not available to integrate via the Theme Editor as the solution requires modifications within templates themselves. 

If you would like to enable this solution, please follow the Smart Category Merchandising - Preserve Shopify Theme section of our manual integration guide.

You will also need to contact our support team to enable the Preserve Layout service, which will periodically update the product sort order within your collections.

If you decide to disable Preserve Layout in the future, this service can be disabled via the Integration screen.

Disable Native Shopify Search Autocomplete (Quick Search)?

You may need to disable your theme’s native search autocomplete results from showing if using the Klevu Quick Search feature.

The implementation of this will vary depending on your theme, though it is commonly found in the Theme Editor under Header > Theme Settings > Enable search suggestions

Troubleshooting

JavaScript Error: klevu is not defined

If you add customizations to your storefront which reference the Klevu library via the global klevu variable, you must ensure that the Klevu JavaScript asset has loaded before use.

Unlike earlier integration methods, Shopify requires that all JavaScript files added by Apps must be render blocking via either the "defer" or "async" attributes. The Klevu app uses "defer" and listens for the "DOMContentLoaded" event before initializing klevu

<script src="https://js.klevu.com/core/v2/klevu.js" defer></script>
<!--- Code ommitted -->
<script>
   document.addEventListener('DOMContentLoaded', () => klevu(klevuSettings));
</script>

Recommendations banners loaded via ajax do not render

Recommendations banners added by App Blocks are evaluated by Klevu during initialisation. If your site loads content containing Recommendations banners after page load, these will not be processed automatically.

Please reach out to us via our Community Forum for assistance.

I have enabled Smart Category Merchandising / Smart Recommendations on my Klevu account but solutions are not available in Theme Editor or my store front

Shopify will restrict solution blocks (Collection Results; Recommendations Banners) in both the Theme Editor and storefront based upon permissions provided by the Klevu App.

These permissions are evaluated and sent to Shopify from the Integration page.

Therefore, if you have enabled a solution, you must access the Integrate section of the Klevu App before it will be available to your store

Due to caching, please leave up to 30 minutes between a solution being enabled on your account and it being available to use in Shopify.

Submitting a search takes me to the wrong results URL

If you have not integrated the Klevu Search Results block on the default Search template, but are showing results on a CMS page or other route, you must update the Search Results Landing Page setting in the Klevu Javascript App Embed, so that our library knows where to redirect search requests.

Frequently Asked Questions

Can I integrate Klevu on an unpublished theme?

Yes, Klevu can be integrated on any theme regardless of publication status.

Please note, some integration aspects are global, however. These include

  • Updating product ordering when using Preserve Shopify Layout for Smart Category Merchandising
  • Theme template and visibility selections when using CMS pages for search results
  • Theme template and visibility selections of collections for Smart Category Merchandising

Are Klevu blocks and settings retained if I duplicate my theme?

Yes, a duplicated theme within the same store will contain the blocks and configuration defined at time of duplication.

Are Klevu blocks and settings retained if I export and import my theme into another store?

Yes, albeit with caveats. The exported theme will contain the same blocks and configuration as the original, however

  • The Klevu API Key used on the storefront will change to the one entered when installing the app on the new store
  • Blocks belonging to solutions not available on the Klevu account associated with the new store will be inaccessible in either the Theme Editor or storefront
  • Configuration set at record level (for example, theme templates for collections or CMS pages) will not be imported

Why am I seeing a warning about Legacy Integration for my theme instead of integration options?

If your theme already contains Klevu integration code, either added by our App (before January 9th, 2024) or manually (following our integration guides), then integrating via the Theme Editor may cause conflicts in the JavaScript on the frontend.

As such, we do not support injection of App Blocks or Embeds while legacy code is present.

Why are Klevu Solution Blocks options not available on my theme?

Block visibility in either the Theme Editor or Storefront may be restricted for a variety of reasons

  • You have uninstalled the Klevu App
  • You are trying to add a block to an unsupported template

    For example, Search Results blocks may only be embedded on Search and Page templates; Collection Results blocks may only be embedded on Collection templates

  • You are trying to add a block for a solution not available on your account
    For example, Collection Results blocks require a subscription to Smart Category Merchandising; Recommendations blocks require a subscription to Smart Recommendations

If you have recently subscribed to a solution but cannot see the associated blocks in the Shopify Theme Editor, please visit the Integration section in the Klevu App to refresh the permissions within Shopify.

Will Klevu continue to work on my storefront if I uninstall the Klevu App?

No, if you have integrated through the Theme Editor; yes for legacy integrations.

Due to the way Klevu had to interact with your theme prior to App Blocks, it was not possible to remove integration code from stores which had uninstalled the Klevu App. 

For integrations using App Blocks, Shopify will perform clean-up automatically if you uninstall the Klevu App.

If you reinstall the Klevu App on your store, Shopify will automatically reinstate any Klevu App Blocks and configuration from the point of uninstallation.

Did you find it helpful? Yes No

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