Google Tag Manager

If you have already integrated Google Tag Manager (GTM) on your website, you can leverage this solution to send click, conversion and view events to the Algolia Insights API.

Setup

Before sending events to the Insights API via Google Tag Manager (GTM), you need to import the official Algolia Search Insights template.

In GTM, click on the New button in the Templates section of your Workspace, search for the official Algolia Search Insights tag template in Tag Templates and add it to your workspace.

Once added, you should see the below screen:

Variables

Enable Click and Conversion Analytics to track the queryID

To track the queryID, you need to enable Click and Conversion Analytics in your code. You can pass clickAnalytics as a search parameter to the API client or to InstantSearch.

Required HTML attributes for hits

This guide expects your Algolia Hits to be rendered with the following data attributes within your HTML:

• data-insights-object-id with the actual objectID value
• data-insights-position with the position of the hit within the results list (starting from 1). For InstantSearch implementations, this position is available through the __position attribute.
• data-insights-query-id with the queryID related to the search. For InstantSearch implementations, this queryID is available through the __queryID attribute.

1
2
3
4
5
6
7
<div class=”my-hit”
 data-insights-object-id="{{objectID}}"
 data-insights-position="{{__position}}"
 data-insights-query-id="{{__queryID}}"
>
  <!-- ... -->
</div>

Add built-in variable

First, add the built-in variable Click Element. This variable is used to retrieve the data associated with the various clicks.

Create user-defined variables

For events to be sent with the correct information from your Algolia implementation, you need to add variables in the User-Defined Variables section:

• A “Your Algolia Application ID” constant
• A “Your Algolia Search API Key” constant
• A “Find closest” custom JavaScript helper
• An “Algolia Hit ObjectIDs” custom JavaScript helper
• An “Algolia Hit Positions” custom JavaScript helper
• An “Algolia Hit QueryID” custom JavaScript helper
• An “Algolia Displayed Object IDs” Data-Layer variable
• An “Algolia UserToken” Data-Layer variable
• An “Algolia Index Name” Data-Layer variable

Once you’ve added all the variables, it should look something like this:

Algolia application ID and search API key

In order to create user-defined variables, you need to go to the Variables section of your workspace and click on the New button in the User-Defined Variables sub-section.

To create your Algolia Application ID and your Algolia Search API Key as user-defined variables, you need to click on the New button.

From there, you need to name the Untitled Variable as “Algolia Application ID” and choose the variable type as Constant under the Utilities sub-section. Copy and paste your Algolia Application ID and save.

Repeat the exact same steps but this time name the Untitled Variable as “Algolia Search API Key” and copy and paste your Algolia Search API Key from the dashboard.

All the relevant variables should now be created and ready for use.

Next, you need to create the following user-defined variables with the Custom JavaScript type to capture objectIDs, queryID, userToken and send proper events.

Find closest custom JavaScript helper

To target elements based on their selection, you need to create a user-defined variables section with the Custom JavaScript type and name it “Find closest” with the following code to paste in the custom JavaScript section:

1
2
3
4
5
6
7
8
9
function() {
  return function(target, selector) {
    while (!target.matches(selector) && !target.matches('body')) {
      target = target.parentElement;
    }

    return target.matches(selector) ? target : undefined;
  }
}

Click Save to save your changes.

In the GTM interface, a new variable called {{Find closest}} is available and has the nearest element matching the selector.

Algolia Hit ObjectIDs custom JavaScript helper

To ensure you capture the objectID, you need to create a custom JavaScript variable and name it Algolia Hit ObjectIDs with the following code to paste in the custom JavaScript section:

1
2
3
4
5
6
7
function() {
  var element = {{Find closest}}({{Click Element}}, '[data-insights-object-id]');

  return typeof element !== 'undefined'
    ? element.getAttribute('data-insights-object-id')
    : undefined;
}

Click Save to save your changes.

In the GTM interface, a new variable called {{Algolia Hit ObjectIDs}} is available, which gives you the objectIDs of the hits you want to capture for a click or a conversion.

Algolia Hit Positions custom JavaScript helper

To ensure you capture the position of the objectID, you need to create a custom JavaScript variable and name it Algolia Hit Positions with the following code to paste in the custom JavaScript section:

1
2
3
4
5
6
7
function() {
  var element = {{Find closest}}({{Click Element}}, '[data-insights-position]');

  return typeof element !== 'undefined'
    ? element.getAttribute('data-insights-position')
    : undefined;
}

Click Save to save your changes.

In the GTM interface, a new variable called {{Algolia Hit Positions}} is available, which gives you the position of the objectID you want to capture for a click or a conversion.

Algolia Hit QueryID custom JavaScript helper

To capture the queryID you need to create a custom JavaScript variable and name it Algolia Hit QueryID with the following code to paste in the custom JavaScript section:

1
2
3
4
5
6
7
function() {
  var element = {{Find closest}}({{Click Element}}, '[data-insights-query-id]');

  return typeof element !== 'undefined'
    ? element.getAttribute('data-insights-query-id')
    : undefined;
}

Click Save to save your changes.

In the GTM interface, a new variable called {{Algolia Hit QueryID}} is available, which gives you the queryID related to the hit. This is the identifier of the search query that returned the hit.

Algolia Displayed Object IDs Data-Layer variable

To capture the ObjectID displayed on the product detail pages, the best is to rely on the Data-Layer. You need to add a new “Data Layer Variable” named “Algolia Displayed Object IDs” and set the “Data Layer Variable Name” to “algoliaDisplayedObjectIDs”.

In the HTML code of your product detail page, ensure the algoliaDisplayedObjectIDs are set using window.dataLayer.push.

1
2
3
4
window.dataLayer = window.dataLayer || []
window.dataLayer.push({
  algoliaDisplayedObjectIDs: 'objectID1, objectID2, objectID3' // a comma-separated list of displayed objectIDs—one in most cases
})

Algolia UserToken Data-Layer variable

To capture the current visitor’s user token, the best is to rely on the Data-Layer. You need to add a new “Data Layer Variable” named “Algolia UserToken” and set the “Data Layer Variable Name” to “algoliaUserToken”.

In your HTML code, ensure the algoliaUserToken is set using window.dataLayer.push.

1
2
3
4
window.dataLayer = window.dataLayer || []
window.dataLayer.push({
  algoliaUserToken: 'userToken1' // the userToken of the current visitor to uniquely identify them
})

Algolia Index Name Data-Layer variable

To capture the Algolia index used, the best is to rely on the Data-Layer. You need to add a new “Data Layer Variable” named “Algolia Index Name” and set the “Data Layer Variable Name” to “algoliaIndexName”.

In your HTML code, ensure the algoliaIndexName is set using window.dataLayer.push.

1
2
3
4
window.dataLayer = window.dataLayer || []
window.dataLayer.push({
  algoliaIndexName: '<The index used for the search>'
})

Tags

Tags should specify which Insights method to call when triggered. Each Insights method is represented by a tag in GTM.

Setup your initialization tag (mandatory)

This step is mandatory for initializing the connection with the Insights API. You need to create a new tag in the Tags section of your workspace and select Algolia Search Insights with the right Init Options.

In the dropdown, select the {{Algolia Application ID}} and {{ Algolia Search API Key}}, set up as user-defined variables. You want to trigger this tag on all pages, hence in the Triggering section below, you need to select “All Pages” as the triggering option.

In the GTM interface, a new tag called “Init” is available.

Setup your click tags

Clicked Object IDs After Search

This method refers to Clicked Object IDs After Search from the Insights API which sends a click event to capture a query and its clicked items and positions. To setup this click tag, you need to create a new tag in the Tags section of your workspace, select Algolia Search Insights with the appropriate Event Options below and choose the following Triggering option:

In the GTM interface, a new tag called Clicked ObjectIDs After Search is available.

Clicked Object IDs

This method refers to Clicked Object IDs from the Insights API which sends a click event to capture a query and its clicked items and positions regardless of the query associated with it. To setup this click tag, you need to create a new tag in the Tags section of your workspace and select Algolia Search Insights with the appropriate Event and Triggering Options below (the example uses the Clicked on Algolia Hit trigger defined earlier):

In the GTM interface, a new tag called Clicked ObjectIDs is available.

Setup your view tags

Viewed Object IDs

This method refers to Viewed Object IDs from the Insights API which sends a view event to capture clicked items. To setup this click tag, you need to create a new tag in the Tags section of your workspace and select Algolia Search Insights with the appropriate Event and Triggering Options below (the example uses the Clicked on Algolia Hit trigger):

In the GTM interface, a new tag called Viewed ObjectIDs is available.

Setup your conversion tags

Converted Object IDs After Search

This method refers to Converted Object IDs After Search from the Insights API which sends a conversion event to capture a query and its clicked items. To setup this tag, you need to create a new tag in the Tags section of your workspace and select Algolia Search Insights with the appropriate Event and Triggering Options below (the example uses the Clicked on Algolia Hit trigger):

In the GTM interface, a new tag called Converted ObjectIDs After Search is available.

Converted Object IDs

This method refers to Converted Object IDs from the Insights API which sends a conversion event to capture a query and its clicked items. To setup this click tag, you need to create a new tag in the Tags section of your workspace and select Algolia Search Insights with the appropriate Event and Triggering Options below (the example uses the Clicked on Algolia Hit trigger):

In the GTM interface, a new tag called Converted ObjectIDs After Search is available.

Triggers

Triggers listen to events occurring on the app to trigger tags. To send an event to the Insights API, you need to attach its tag to the corresponding trigger. This page assumes you’ve set up triggers in your Google Tag Manger Workspace.

As an example, this guide uses the Clicked on Algolia Hit trigger—defined in the Triggers section of your Workspace—which fires with the following settings:

Now you can add this trigger to your tag. When clicking on the Add Trigger menu, you can see a list of your triggers to choose from.

Submit your changes and debug your events

Once you’ve set up the different variables, tags, and triggers, you can submit your changes. To ensure you’re sending events to the Insights API, you can use the Tag Assistant from Google.

This allows you to check that the expected Algolia variables are all set:

You can also rely on Algolia’s tools to make sure your events are being sent to the Insights API. The Insights Validator Chrome extension can help you monitor events in real time, and you can inspect the Insights API Logs in the Monitoring section of the Algolia dashboard.