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 thealgolia_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
:
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 conversion events
To track conversions, follow these steps:
- Check that click analytics is turned on.
- In the template file
algolia_instant_search.js.liquid
, uncomment calls to thesaveForConversionTracking
method. -
If you’re using the newer template files with the
html
tagged templates, update the filealgolia_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?Copy1 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); },
-
In the template file
algolia.analytics.js.liquid
, replaceYOUR_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.Copy1 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:
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:
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:
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:
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>
:
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:
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:
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:
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:
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
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;
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
1
2
var autocomplete = algolia.externals.autocomplete;
- var aa = algolia.externals.aa;
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
*/