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.

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

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>

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.

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?”)

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.

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

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

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.