🎉 Try the public beta of the new docs site at algolia.com/doc-beta! 🎉
Integrations / Shopify

Click and conversion events

The Algolia Search and Discovery app lets you track click and conversion events from your Shopify store.

Sending events enables you to use these features:

Before you begin

Algolia Search and Discovery supports the default widgets provided by the app. If you’re using custom widgets, see Sending events for more information.

If you’re not using the latest version of the InstantSearch widgets, see Widget updates on this page for more information.

To update the widgets to the latest version, go to the Search options tab in your Shopify store and re-enable Algolia for a particular theme. Re-enabling widgets in the theme removes all customizations you’ve done. After customizing the widget code, duplicate the theme first to avoid losing your changes.

User token strategy

Events represent an interaction of a user with your store. Algolia relates a user profile to an event through a user token.

You can choose how you want to set the user token:

userToken is set with a random alphanumeric string at every page refresh
This option doesn’t use cookies. Because every page refresh generates a new user token, you can’t identify user profiles across sessions.
userToken is set using cookies depending on the user’s approval
This option stores the user token in a cookie on the user’s device. You must use Shopify’s Customer Privacy API. If the user hasn’t consented or you don’t use the Customer Privacy API, a random alphanumeric string is used as user token. You need to add the same name parameter value for the Shopify.loadFeatures method in your cookie banner and in the algolia_analytics.js.liquid file (default: consent-tracking-api).

Choosing a user token strategy only works with the latest versions of the InstantSearch widgets. Older versions use the search-insights library version 1, which sets an anonymous token automatically and uses cookies by default.

User token for Personalization

To personalize your search experience, you need to provide a way to identify user profiles across sessions with a stable user token. For example, you can use the user’s account ID after they signed in to your shop.

To add a stable user token, edit the template file algolia_analytics.js.liquid:

Copy 
1

insightsClient('setUserToken', uniqueUserToken);

Send click events

Since January 2023, the Algolia Search and Discovery app sends click events by default. If you installed the app before January 2023, go to the Settings tab in your Shopify app and select Use click analytics.

With click analytics turned on, the app sends a click event to Algolia when a user clicks a product in the autocomplete menu or on the search results page.

Select your user token strategy and save your changes.

Send click events section in the Shopify admin

Send conversion events

To track conversions, follow these steps:

  1. Check that click analytics is turned on.
  2. In the template file algolia_instant_search.js.liquid, uncomment calls to the saveForConversionTracking method.

  3. If you’re using the newer template files with the html tagged templates, update the file algolia_autocomplete_product_plugin.js.liquid. If you’re using the older templates with the Hogan.js templating language, skip this step. To help you find out which template syntax you’re currently using, see How to tell if my Shopify theme uses the new Autocomplete HTML templates?

    Copy 
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

    templates: {
  header({ html, state }) {
    const resource = translations.products;
    return headerTemplate({ html, state }, resource);
  },
  item({ item, html, components }) {
    const distinct = config.show_products;
    const variantInfo = !distinct && item.objectID !== item.id ? `?variant= ${item.objectID}` : '';
    const itemLink = `/products/${item.handle}/${variantInfo}`;
    const getConversionData = (e, item) => {
      if (!algolia.config.analytics_enabled) return;
+     algolia.saveForConversionTracking({
+       eventName: 'Added to cart',
+       index: item.__autocomplete_indexName,
+       objectIDs: [item.objectID],
+       queryID: item.__autocomplete_queryID,
+     });
  }
  return productTemplate({ item, html, components }, distinct, itemLink, getConversionData);
},

  4. In the template file algolia.analytics.js.liquid, replace YOUR_ADD_TO_CART_SELECTOR with the CSS selector for your Add to cart button. This sends a conversion event when a user clicks on your Add to cart button.

    Copy 
    1
2
3
4
5
6
7
8

    // Track a conversion event when clicking the 'add to cart' button.
// Change the query selector match your theme.
const addToCartBtn = document.querySelector('YOUR_ADD_TO_CART_SELECTOR')
if (addToCartBtn) {
  addToCartBtn.addEventListener('click', function (e) {
    trackConversion()
  })
}

Widget updates

If you aren’t using the latest versions of the Algolia Search and Discovery app, you need to set up conversion analytics and personalization manually.

Conversion events

To support conversion tracking, your algolia_analytics.js.liquid file has to contain the following methods:

saveForConversionTracking
This method saves details in localStorage about objects that were clicked from the search results.
trackConversion
This method sends the events using the data stored in the localStorage about objects that were clicked from the search results.

The files algolia_instant_search.js.liquid and algolia_autocomplete.js.liquid include calls to saveForConversionTracking, but these are commented out by default. To enable conversion tracking, uncomment these lines.

algolia_analytics.js.liquid

The algolia_analytics.js.liquid file contains the following updates:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75

@@ -9,4 +9,68 @@
     appId: algolia.config.app_id,
     apiKey: algolia.config.search_api_key,
   });
+
+  const localStorageKey = 'algolia_analytics_clicked_objects';
+
+  /**
+   * Saves details in local storage for conversion tracking
+   */
+  algolia.saveForConversionTracking = function (data) {
+    /**
+     * We're using a try, catch here to handle any possible exceptions
+     * resulting from local storage or JSON parsing.
+     */
+    try {
+      // Get any data previously stored
+      const previousClickItemsString = localStorage.getItem(localStorageKey) || '[]';
+      const previousClickItems = JSON.parse(previousClickItemsString);
+
+      var conversionData = data;
+
+      // Changing the event to 'convert' from 'click'
+      conversionData.eventName = 'convert';
+      // Removing the `positions` property
+      delete conversionData.positions;
+
+      // Add the current products data to local storage
+      previousClickItems.push(conversionData)
+      localStorage.setItem(localStorageKey, JSON.stringify(previousClickItems))
+    } catch (error) {
+      // No need to do anything in this scenario
+    }
+  };

+  /**
+   * Try to get the details from local storage for conversion tracking.
+   * We're using a try...catch here to handle any possible exceptions resulting
+   * from local storage or JSON parsing.
+   */
+   function trackConversion() {
+     try {
+       // Get any previously stored data.
+       const previousClickItemsString = localStorage.getItem(localStorageKey)
+       // If data was found, send a conversion event for those products.
+       if (!!previousClickItemsString) {
+         const previousClickItems = JSON.parse(previousClickItemsString)
+         previousClickItems.forEach((data) => {
+           aa('convertedObjectIDsAfterSearch', data)
+           // If you're still using version 1 of the insights library integration, use this function:
+           // aa.convertedObjectIDsAfterSearch(data);
+         })
+       }
+     } catch (error) {
+       // No need to do anything in this scenario.
+     }
+
+     // Try to remove the items from local storage.
+     try {
+       localStorage.removeItem(localStorageKey)
+     } catch (error) {
+       // No need to do anything in this scenario.
+     }
+   }
+
+   // Track a conversion event when clicking the 'add to cart' button.
+   // Change the query selector to be the correct one for your theme.
+   const addToCartBtn = document.querySelector('YOUR_ADD_TO_CART_SELECTOR')
+   if (addToCartBtn) {
+     addToCartBtn.addEventListener('click', function (e) {
+       trackConversion()
+     })
+   }
+
 })(window.algoliaShopify);

Replace YOUR_ADD_TO_CART_SELECTOR with the CSS selector for your Add to cart button.

algolia_autocomplete.js.liquid

The algolia_autocomplete.js.liquid file contains the following updates:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

@@ -280,13 +280,21 @@
   // Event listeners
   autocompleteInstance.on('autocomplete:selected', function(obj, datum, name) {
     if (algolia.config.analytics_enabled) {
-      aa.clickedObjectIDsAfterSearch({
+      var clickData = {
         index: datum._index,
         eventName: 'click',
         queryID: datum._queryID,
         objectIDs: [datum.objectID],
         positions: [datum._position],
-      });
+      };
+
+      // Send the click event
+      aa.clickedObjectIDsAfterSearch(clickData);
+      /**
+       * Uncomment the following function call to start storing data in
+       * local storage for conversion tracking
+       */
+      // algolia.saveForConversionTracking(clickData);
     }
     switch (name) {
       case 'products': {

algolia_instant_search.js.liquid

The algolia_instant_search.js.liquid file contains the following updates:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

@@ -617,13 +617,21 @@
             link += '?variant=' + variant_id;
           }
           if (algolia.config.analytics_enabled) {
-            aa.clickedObjectIDsAfterSearch({
+            var clickData = {
               index: hit.dataset.algoliaIndex,
               eventName: 'click',
               queryID: hit.dataset.algoliaQueryid,
               objectIDs: [hit.dataset.algoliaObjectid],
               positions: [Number(hit.dataset.algoliaPosition)],
-            });
+            };
+
+            // Send the click event
+            aa.clickedObjectIDsAfterSearch(clickData);
+            /**
+             * Uncomment the following function call to start storing data in
+             * local storage for conversion tracking
+             */
+            // algolia.saveForConversionTracking(clickData);
           }
           window.location.href = link;
         });

Personalization

To personalize your search on the old version of the Algolia Search and Discovery app, you need to link events to your users.

theme.liquid

In the theme.liquid file, change the way the search-insights script is added to the site.

First, remove the inclusion of the search-insights JavaScript file:

Copy 
1

- <script src="https://cdn.jsdelivr.net/npm/search-insights@1.9.0/dist/search-insights.min.js" integrity="sha256-/zXpGP2+kWLFmVvxDBsJtOhx05CPGoY6nuOg9P/5fgc=" crossorigin="anonymous"></script>

Then, add the following script after all the other Algolia scripts have been added and before the </head>:

Copy 
1
2
3
4
5
6
7
8

<script>
  var ALGOLIA_INSIGHTS_SRC = "https://cdn.jsdelivr.net/npm/search-insights@2.8.3/dist/search-insights.min.js";

  !function(e,a,t,n,s,i,c){e.AlgoliaAnalyticsObject=s,e[s]=e[s]||function(){
  (e[s].queue=e[s].queue||[]).push(arguments)},e[s].version=(n.match(/@([^\/]+)\/?/) || [])[1],i=a.createElement(t),c=a.getElementsByTagName(t)[0],
  i.async=1,i.src=n,c.parentNode.insertBefore(i,c)
  }(window,document,"script",ALGOLIA_INSIGHTS_SRC,"aa");
</script>

algolia_externals.js

Edit the algolia_externals.js file:

Copy 
1
2
3
4

  autocomplete: window.autocomplete,
-  aa: window.AlgoliaAnalytics.default,

  // Export the required widgets

algolia_analytics.js.liquid

Edit the algolia_analytics.js.liquid file:

Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

'use strict';
-  var aa = algolia.externals.aa;

var enabled = algolia.config.analytics_enabled;
if (!enabled) return;

-  aa.init({
-    appId: algolia.config.app_id,
-    apiKey: algolia.config.search_api_key,
-  });
+  window.aa('init', {
+    appId: algolia.config.app_id,
+    apiKey: algolia.config.search_api_key,
+  });
+
+  // Uncomment the following line and replace `yourUniqueUserToken` with a unique userToken to link events to a user.
+  //window.aa('setUserToken', 'yourUniqueUserToken');

Uncomment the call to window.aa('setUserToken') and pass it your user’s unique token.

To track conversion events, update the algolia_analytics.js.liquid file:

Copy 
1
2
3
4
5
6
7

if (!!previousClickItemsString) {
  const previousClickItems = JSON.parse(previousClickItemsString);
  previousClickItems.forEach(data => {
-   aa('convertedObjectIDsAfterSearch', data);
+   window.aa('convertedObjectIDsAfterSearch', data);
  });
}

If you added your own tracking of conversion events, you need to update your code:

Copy 
1
2

-  aa('convertedObjectIDsAfterSearch', data);
+  window.aa('convertedObjectIDsAfterSearch', data);

Replace data with the relevant variable or JSON object used in this conversion event.

algolia_instant_search.js.liquid

Copy 
1
2
3
4
5
6
7

var connectRatingMenu =
  algolia.externals.connectors.connectRatingMenu;
- var aa = algolia.externals.aa;

var collectionPageEnabled =
  algolia.is_collection_results_page &&
  algolia.config.instant_search_enabled_on_collection;
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

var clickData = {
  index: hit.dataset.algoliaIndex,
  eventName: 'click',
  queryID: hit.dataset.algoliaQueryid,
  objectIDs: [hit.dataset.algoliaObjectid],
  positions: [Number(hit.dataset.algoliaPosition)],
};

// Send the click event
- aa.clickedObjectIDsAfterSearch(clickData);
+ window.aa('clickedObjectIDsAfterSearch', clickData);
  /**
   * Uncomment the following function call to start storing data in
   * local storage for conversion tracking
  */

algolia_autocomplete.js.liquid

Copy 
1
2

var autocomplete = algolia.externals.autocomplete;
-  var aa = algolia.externals.aa;
Copy 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

var clickData = {
  index: datum._index,
  eventName: 'click',
  queryID: datum._queryID,
  objectIDs: [datum.objectID],
  positions: [datum._position],
};

// Send the click event
- aa.clickedObjectIDsAfterSearch(clickData);
+ window.aa('clickedObjectIDsAfterSearch', clickData);
/**
 * Uncomment the following function call to start storing data in
 * local storage for conversion tracking
 */
Did you find this page helpful?