Google Tag Manager
On this page
If you have already integrated Google Tag Manager (GTM) on your website, you can leverage this solution to send Insights events to Algolia.
This guide only demonstrates the use of the Algolia GTM connector for an InstantSearch front end.
Setup
Import the template
Before sending events, you need to import the Algolia Search Insights template in GTM.
In your workspace, open Tag Manager, find the template in Tag Templates > Search Gallery, and add it to your workspace.
Create variables
For events to be sent with the correct information (userToken
, objectIDs
, queryID
, etc.), you need to add variables in the User-Defined Variables section.
- Click New in the Variables panel.
- Refer to the Variables section.
Create tags
Tags should specify which Insights method to call when triggered.
- Click New in the Tags panel.
- Select the Algolia Search Insights tag type.
- Choose the Insights method and provide the options.
- Refer to the Tags section to specify the Insights method.
Create triggers
Triggers listen to events happening on the app to trigger tags.
- Click New in the Triggers panel.
- Select the element to interact with.
Tags
Each Insights method is represented by a tag in GTM.
Init
This method is necessary for initializing the connection with the Insights API.
Configuration
You need to define some variables to use this method:
- App ID
- Search API key
Trigger
It’s recommended to trigger this tag on the “Page View” event.
Clicked Object IDs After Search
This method refers to Clicked Object IDs After Search from the Insights API.
Configuration
You need to define some variables to use this method:
- Event name
- User Token
- Index
- Query ID
- Object IDs
- Positions
Templates
1
2
3
4
5
6
7
8
9
10
11
12
13
14
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<article
data-insights-object-id="{{objectID}}"
data-insights-position="{{__position}}"
data-insights-query-id="{{__queryID}}"
>
<!-- ... -->
</article>
`
}
})
Clicked Object IDs
This method refers to Clicked Object IDs from the Insights API.
Configuration
You need to define some variables to use this method:
- Event name
- User token
- Index
- Object IDs
- Positions
Templates
1
2
3
4
5
6
7
8
9
10
11
12
13
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<article
data-insights-object-id="{{objectID}}"
data-insights-position="{{__position}}"
>
<!-- ... -->
</article>
`
}
})
Clicked Filters
This method refers to Clicked Filters from the Insights API.
Configuration
You need to define some variables to use this method:
- Event name
- User token
- Index
- Filters
Templates
Replace brand
with the attribute to track.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
instantsearch.widgets.refinementList({
container: '#brands',
attribute: 'brand',
templates: {
item: `
<label
class="ais-RefinementList-label"
data-insights-filter="brand:{{value}}"
>
<input type="checkbox" class="ais-RefinementList-checkbox" value="{{value}}">
<span class="ais-RefinementList-labelText">{{label}}</span>
<span class="ais-RefinementList-count">{{count}}</span>
</label>
`
}
})
Converted Objects IDs After Search
This method refers to Converted Objects IDs After Search from the Insights API.
Configuration
You need to define some variables to use this method:
- Event name
- User token
- Index
- Query ID
- Object IDs
Trigger
It’s recommended to trigger this tag when a user clicks a search result.
Templates
1
2
3
4
5
6
7
8
9
10
11
12
13
14
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<article
data-insights-object-id="{{objectID}}"
data-insights-position="{{__position}}"
data-insights-query-id="{{__queryID}}"
>
<!-- ... -->
</article>
`
}
})
Converted Objects IDs
This method refers to Converted Objects IDs from the Insights API.
Configuration
You need to define some variables to use this method:
- Event name
- User token
- Index
- Object IDs
Templates
1
2
3
4
5
6
7
8
9
10
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<article data-insights-object-id="{{objectID}}">
<!-- ... -->
</article>
`
}
})
Converted Filters
This method refers to Converted Filters from the Insights API.
Configuration
You need to define some variables to use this method:
- Event name
- User token
- Index
- Filters
Templates
Replace brand
with the attribute to track.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
instantsearch.widgets.refinementList({
container: '#brands',
attribute: 'brand',
templates: {
item: `
<label
class="ais-RefinementList-label"
data-insights-filter="brand:{{value}}"
>
<input type="checkbox" class="ais-RefinementList-checkbox" value="{{value}}">
<span class="ais-RefinementList-labelText">{{label}}</span>
<span class="ais-RefinementList-count">{{count}}</span>
</label>
`
}
})
Viewed Object IDs
This method refers to Viewed Object IDs from the Insights API.
Configuration
You need to define some variables to use this method:
- Event name
- User token
- Index
- Object IDs
Templates
1
2
3
4
5
6
7
8
9
10
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<article data-insights-object-id="{{objectID}}">
<!-- ... -->
</article>
`
}
})
Viewed Filters
This method refers to Viewed Filters from Insights API.
Configuration
You need to define some variables to use this method:
- Event name
- User token
- Index
- Filters
Templates
Replace brand
with the attribute to track.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
instantsearch.widgets.refinementList({
container: '#brands',
attribute: 'brand',
templates: {
item: `
<label
class="ais-RefinementList-label"
data-insights-filter="brand:{{value}}"
>
<input type="checkbox" class="ais-RefinementList-checkbox" value="{{value}}">
<span class="ais-RefinementList-labelText">{{label}}</span>
<span class="ais-RefinementList-count">{{count}}</span>
</label>
`
}
})
Variables
Including userToken
You can forward the user token to GTM via a Data Layer. Note that a user token is only necessary if you plan to leverage Personalization.
In you application code, store the userToken
in the Data Layer:
1
2
3
4
window.dataLayer = window.dataLayer || []
window.dataLayer.push({
userToken: 'USER_1'
})
In GTM, create a variable called UserToken
of type “Data Layer Variable” with the name userToken
(same name as the JavaScript key you pushed to the Data Layer).
In the GTM interface, a new variable called {{UserToken}}
is available.
Including objectIDs
, positions
, queryID
You can forward the objectIDs
, positions
, queryID
variables to GTM via data attributes.
The following example uses InstantSearch.js and assumes that you’ve set the data attributes in the templates.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const search = instantsearch({
searchClient,
indexName: 'products'
})
search.addWidgets([
instantsearch.widgets.hits({
container: '#hits',
templates: {
item: `
<article
data-insights-object-id="{{objectID}}"
data-insights-position="{{__position}}"
data-insights-query-id="{{__queryID}}"
>
<!-- ... -->
</article>
`
}
})
])
search.start()
__queryID
and __position
are available in hits
and infiniteHits
from InstantSearch.js 3.4.0.
Once these values are available in the hits template, you can retrieve them in GTM.
First, you need to create a utility variable to target elements based on their selector. Select Custom JavaScript variable and name it Find closest
:
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;
}
}
Element.matches
needs to be polyfilled to support IE11.
In the GTM interface, a new variable called {{Find closest}}
is available and contains the nearest element matching the selector.
Including objectID
Create a Custom JavaScript variable and name it HitObjectID
:
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;
}
In the GTM interface, a new variable called {{HitObjectID}}
is available and gives you the object ID of the hit.
You can use getAttribute
to add compatibility for Internet Explorer, which doesn’t support JavaScript access to dataset
.
Including positions
Create a Custom JavaScript variable and name it HitPosition
:
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;
}
In the GTM interface, a new variable called {{HitPosition}}
is available and gives you the absolute position of the hit.
Including queryID
From InstantSearch
Create a Custom JavaScript variable and name it HitQueryID
:
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;
}
In the GTM interface, a new variable called {{HitQueryID}}
is available and gives you the query ID related to the hit. This is the identifier of the search query that returned the hit.
From the URL
Create a “URL” variable named URLQueryID
of type “Query” and with the query parameter name of the queryID
as key.
In the GTM interface, a new variable called {{URLQueryID}}
is available and gives you the query ID related to the URL.
Including filters
You can forward the filters
variable to GTM via data attributes.
The following example uses InstantSearch.js and assumes that you’ve set data attributes in the templates.
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
const search = instantsearch({
searchClient,
indexName: 'products'
})
search.addWidgets([
instantsearch.widgets.refinementList({
container: '#brands',
attribute: 'brand',
templates: {
item: `
<label
class="ais-RefinementList-label"
data-insights-filter="brand:{{value}}"
>
<input type="checkbox" class="ais-RefinementList-checkbox" value="{{value}}">
<span class="ais-RefinementList-labelText">{{label}}</span>
<span class="ais-RefinementList-count">{{count}}</span>
</label>
`
}
})
])
search.start()
Once these values are available in the hits template, you can retrieve them in GTM.
Create a Custom JavaScript variable and name it Filters
:
1
2
3
4
5
6
7
function() {
var element = {{Find closest}}({{Click Element}}, '[data-insights-filter]');
return typeof element !== 'undefined'
? element.getAttribute('data-insights-filter')
: undefined;
}
In the GTM interface, a new variable called {{Filters}}
is available and gives you the filters.