for

Frequently Asked Questions

Most common issues and how to fix them.


Where to ask for Help?

Please ask your question on our brand new Shopify forum https://discourse.algolia.com/c/shopify .

This way, anybody with the same question will be able to find the solution in the future and you'll get access to other great minds using our integration!

Questions & Answers

Will this plugin be compatible with my Shopify theme?

Our aim is to make our integration work with as much themes as possible.
However, we can't guarantee that this will be the case.

If you're having CSS issues with the autocomplete, please reach out to us on our forum so that we can try to improve the autocomplete to be fully theme-independent.

However, if you want to use as a replacement for your search page, there are too many factors that we won't be able to fully cover.
You should expect having some CSS to do in order to have it fully integrated in your theme.

To help you debug front-end issues in a theme that isn't your live one, we'll need to see this specific theme in action. We'll hence ask you to share with us a preview link to the theme you're installing us in.

Getting it is easy:

Facets list screenshot

Also, if your store isn't live yet, you might be using a password to block users. If you feel like this is sensitive, feel free to send it to us via email with a link to the associated question on our forum.

Do I have to use the bundled front-end?

No! The application is really split in two tasks: data indexing and front-end implementation. You can definitely only use the app to index data.

This can be useful in multiple cases:

  • You want to use those indices elsewhere than Shopify
  • The implementation you want to do is too far from ours to use it as a base

Can I customize the Autocomplete dropdown look & feel?

Yes. You can find some detailed explanations on this page.

My data is out of sync with Algolia

This is expected to happen from time to time. There are multiple points in the data duplication chain that could explain some records being out of sync.

In that case, head to the Settings tab of the application and click the Reindex button of the faulty data type. This will trigger a full reindex (which can take up to 24 hours), after which your data should be updated as expected.

If your data keeps getting out of sync, this might be a sign of an indexing error on our side. Please report it to us so that we can investigate what could be the cause.

More information in the Indexing introduction section of the documentation.

My indexing is slow

Indexing with the app works in two steps:

  • Complete reindexing: This consists in creating a completely new index by listing all of your products / collections / blog posts / pages.
  • Real-time updating: This relies on Shopify webhooks to keep your index up to date

Complete reindexing

When doing a complete reindexing, we'll browse through your list of products and save them in a temporary index. When complete, this index then replaces your live index with a fully up to date index.

This step can be slow, especially when using Metafields, as we'll need to run a Shopify API request for each product to retrieve them. See our Metafields section for more information.

Blog posts and Pages do not have update webhooks, so we provide a periodic complete reindexing instead.

Real-time indexing

Here's the full lifecycle of a product update:

Shopify When you save a product in Shopify, it's added to a Shopify internal queue, where it waits for previous jobs to be executed before being itself processed. When this job is processed, Shopify will now have an updated product for your store, and loading it in your store should show it up to date. When the job has finished processing, this job will then be sent to our Algolia for Shopify app with a webhook.

Algolia for Shopify app We'll receive this webhook call, and add an indexing job to our app's internal queue. When the job processes, it forwards this update to the Algolia API.

Algolia API The Algolia API itself also has an indexing queue in which those jobs will be added. Once processed, search results will have the up to date version of your product.

Both the Shopify API and the Algolia API can be bottlenecks if they're heavily loaded. However, this should be fairly rare, as those two are heavily optimized.

The main bottleneck will often be our app, which, since it's provided for free, has limited resources. We've done a lot of optimizations since our first release as you can see in our ChangeLog, but if your frequency of updates is too big, we might process updates slower than you're sending them to Shopify.

Using metafields will not slow down this step, as Shopify allows to ask for metafields to be included within webhooks.

If you believe that your indexing is stuck, please first check that you have no error when opening the app. If you don't, don't hesitate to contact us to investigate.

Can I use one Algolia account for multiple Shopify stores?

Definitely! You'll find at the bottom of the Credentials tab a field to change the index prefix used in Algolia.

Just set up each of your stores with a different prefix, and you're good to go!

Can I use Algolia to search inside a specific collection?

This is unfortunately not possible for technical reasons, at least for now. We explain why in greater details in this discourse post: https://discourse.algolia.com/t/usage-on-collection-pages/595

How can I use this with my external theme management service (git, svn, hg, ...)

If you're using an external system to manage your theme files, you should have an exclusion on one of our files, assets/algolia_config.js.liquid. Indeed, this file contains the front-end settings that you configure in our admin interface.

An example of this would be when you change the amount of products displayed on the search page. Our front-end code needs to have this updated information. The way we do this is by updating the algolia_config.js.liquid file on every change you make in the admin interface.

An issue arises if you:

  • copy all of our files in your theme to an external system
  • do modifications in our admin interface which modifies the live algolia_config.js.liquid file
  • do code changes in this system
  • then deploy your code with the old version of the file which will override the new one

The easy solution is that most of those systems allow you to add an ignore rule. Just add a rule for this file, and everything should work fine!

I have a webhook warning, what does it mean?

To keep your data up to date between Shopify and Algolia, we're registering to webhooks provided by Shopify.

You should never have this warning, but it happens that we're not able to register correctly to those webhooks (e.g. a network error for instance).

In that case, you'll need to :

  1. Restore the webhooks by clicking the button in the warning
  2. Optionally reindex everything from the Settings tab

What impact does this have on my website performance

When opening your layout file, you might be concerned about the performance impacts of our app. Indeed, we're installing and loading quite a few files.

Installed files

There are multiple things to be aware of there:

  • The first part are snippets, which will be rendered, in JavaScript, using Hogan
  • The second part are assets, which contain some JavaScript and CSS. Some of them are loaded from an external CDN, and those are JavaScript libraries The rest are scripts which can be found in your theme files.

How is all of this impacting your page load time? Snippets are loaded while your page is rendered and executing liquid. They're all small, so their impact is negligible. Assets are loaded using external requests for each of them. Libraries take some time to be fetched (<1M total) and the scripts are really small, but the big bottleneck is on the HTTP requests needed to fetch them.

Fetching

Fetching them will be required only once, which on the first load of your page by a customer. Furthermore, they're all hosted on a CDN, which is distributed around the globe to send those page faster (jsdelivr for the libraries, Shopify themselves for the scripts). Finally, most browsers will actually run 5 or 6 HTTP requests in parallel, so we're actually talking about two or three round-trips only.

Execution

Then the JavaScript will need to be executed by your browser. This action is blocking, which is why Google PageSpeed will tell you to:

Eliminate render-blocking JavaScript and CSS in above-the-fold content

This is a valid suggestion, and there is an easy way to do so.

  • Open your layout file (often layouts/theme.liquid)
  • Identify the block delimited by <!-- Algolia head --> and <!-- /Algolia head -->
  • Move it just before your closing </body> tag, which should be at the very end of the file

The reason we're not doing this by default is because almost all of the Shopify scripts we've seen are added inside the <head> tag. This allows our users to clearly see that there was code appended.

Optimizing

jQuery
Most themes already include jQuery, but since some don't, or include an old version, we need to include it everytime. However, if you're using a recent version of jQuery, you might want to remove ours. Simply remove the line including it from the block. You'll also need to edit one file, algolia_init.js.liquid:

// Replace
algolia.$ = algolia.jQuery = $.noConflict(true);
// By
algolia.$ = algolia.jQuery = $;

Not using the autocomplete?
You can remove:

  • The autocomplete.js library
  • algolia_autocomplete.js.liquid

Not using the instant search page?
You can remove:

  • The instantsearch.js library (both the CSS and JS file)
  • algolia_facets.js.liquid
  • algolia_sort_orders.js.liquid
  • algolia_instant_search.js.liquid

Minification
Our JavaScript code is really small, and minifying it wouldn't bring much benefits. We've deliberately chose to keep it unminified, so that you could modify its behavior easily. Feel free however to replace them with a minified version.

How to display as a list by default

If you want to change the default display to the list style by default, you only need to do small changes to snippets/algolia_instant_search.hogan.liquid:

@@ -24,15 +24,15 @@
     <div class="ais-search-header">
       <div class="ais-stats-container"></div>
       <div class="ais-change-display">
-        <span class="ais-change-display-block ais-change-display-selected"><i class="fa fa-th-large"></i></span>
-        <span class="ais-change-display-list"><i class="fa fa-th-list"></i></span>
+        <span class="ais-change-display-block"><i class="fa fa-th-large"></i></span>
+        <span class="ais-change-display-list ais-change-display-selected"><i class="fa fa-th-list"></i></span>
       </div>
       <div class="ais-sort">
         Sort by
         <span class="ais-sort-orders-container"></span>
       </div>
     </div>
-    <div class="ais-hits-container ais-results-as-block"></div>
+    <div class="ais-hits-container ais-results-as-list"></div>
   </div>
   <div class="ais-pagination-container"></div>
 </div>

How to use the instant search on other pages

A front-end developer is required for this step.

You'll first obviously want to disable the autocomplete in the Store Configuration tab.
Then the most important thing here is to have a CSS selector which matches on every page one single element.

For the rest, a diff is sometimes better than a long speech.
In assets/algolia_instant_search.js.liquid:

@@ -1,5 +1,6 @@
 (function (algolia, instantsearch) {
-  if (!algolia.full_results || !algolia.config.instant_search_enabled) return;
+  var everywhere = true;
+  if (!algolia.config.instant_search_enabled || !(algolia.full_results || everywhere)) return;

   var _ = algolia._,
       $ = algolia.jQuery;
@@ -21,7 +22,21 @@
       appId: algolia.config.app_id,
       apiKey: algolia.config.search_api_key,
       indexName: '' + algolia.config.index_prefix + 'products',
-      urlSync: {}
+      urlSync: {},
+      searchFunction: function (helper) {
+        if (!everywhere) {
+          helper.search();
+          return;
+        }
+        if (helper.state.query) {
+          helper.search();
+          instant.$results.show();
+          instant.$otherContent.hide();
+          return;
+        }
+        instant.$results.hide();
+        instant.$otherContent.show();
+      }
     }),
     selector: algolia.config.results_selector + ', .algolia-shopify-instantsearch',
     sortOrders: algolia.sortOrders,
@@ -68,6 +83,11 @@

   $(document).ready(function () {
     instant.$results = $(instant.selector);
+    if (everywhere) {
+      instant.$otherContent = instant.$results;
+      instant.$results = instant.$results.clone()
+      instant.$results.insertBefore(instant.$otherContent);
+    }

     instant.$results.html(algolia.render(instant.templates.page, {
       facets: instant.facets.list,
@@ -110,13 +130,19 @@
     });

     // Search input
-    instant.search.addWidget(
-      instantsearch.widgets.searchBox({
-        container: '.ais-search-box-container',
-        placeholder: 'Search for products',
-        poweredBy: false
-      })
-    );
+    var searchSelector = '.ais-search-box-container';
+    if (everywhere) {
+      searchSelector += ', form[action="/search"] input[type=text], form[action="/search"] input[type=search]'; // You can put the same CSS selector than for your autocomplete here
+    }
+    $(searchSelector).each(function () {
+      instant.search.addWidget(
+        instantsearch.widgets.searchBox({
+          container: $(this)[0],
+          placeholder: 'Search for products',
+          poweredBy: false
+        })
+      );
+    });

     // Logo & clear
     instant.search.addWidget({

Those changes are definitely not guaranteed to work on your website, but should give you a good starting point.