Send click and conversion events with InstantSearch Android
On this page
Events are actions that users take on your app or website. They unlock powerful features, such as recommendations, personalization, smarter search results, and analytics that help you optimize your user experience. For more information, see Get started with click and conversion events.
To send events from your InstantSearch Android app, follow these steps:
- Add the
insightsclient. - Add click events when users click search results.
- Track conversions that start in your InstantSearch app.
Add the InstantSearch Insights library
Add the library as a dependency to your build.gradle file:
1
implementation "com.algolia:instantsearch-insights-android:3.+"
Add the Insights client
To add the Insights client, you’ll need your Algolia application ID, (search) API key, and the index name. You can find your application ID and API key in the Algolia dashboard.
1
2
3
4
5
6
7
8
9
val appID = ApplicationID("applicationID")
val apiKey = APIKey("apiKey")
val indexName = IndexName("indexName")
val configuration = Insights.Configuration(
connectTimeoutInMilliseconds = 5000,
readTimeoutInMilliseconds = 5000
)
registerInsights(context, appID, apiKey, indexName, configuration)
Set the userToken
All events must have a userToken field to specify the user it relates to. You can set the userToken field in three ways:
- Globally, for all events
- Per app, for every event tracked by the app
- Individually, for each event
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
// Global userToken default value
val configuration = Insights.Configuration(
connectTimeoutInMilliseconds = 5000,
readTimeoutInMilliseconds = 5000,
defaultUserToken = UserToken("userToken")
)
registerInsights(context, appID, apiKey, indexName, configuration)
// App userToken overrides global default
sharedInsights(indexName).apply {
userToken = UserToken("userToken")
}
// Event userToken overrides previous defaults
sharedInsights?.clicked(
InsightsEvent.Click(
eventName = EventName("eventName"),
indexName = IndexName("indexName"),
userToken = UserToken("userToken"),
timestamp = System.currentTimeMillis(),
queryID = QueryID("queryId"),
resources = InsightsEvent.Resources.ObjectIDs(
listOf(ObjectID("objectID1"))
)
)
)
User opt-out
You can exclude users who opted out from tracking with the following code:
1
2
3
sharedInsights(indexName)?.enabled = false
// Alternatively, by getting the latest registered Insights instance
sharedInsights?.enabled = false
Create a HitsTracker to track events from search results
1
2
3
4
5
val hitsTracker = HitsTracker(
eventName = EventName("hits"),
searcher = searcher,
insights = sharedInsights(indexName)
)
Create a FilterTracker to track events from filters
1
2
3
4
5
val filterTracker = FilterTracker(
eventName = EventName("demo"),
searcher = searcher,
insights = sharedInsights(IndexName)
)
Send events
Use the trackView, trackClick, and trackConversion methods to send events.
When you add events, check them in the Events Debugger in the Algolia dashboard.
For more information, see Validate your events.
Send view events
1
2
3
4
5
// HitsTracker
hitsTracker.trackView(hit)
// FilterTracker
filterTracker.trackView(facet)
Send click events
1
2
3
4
5
// HitsTracker
hitsTracker.trackClick(hit, position)
// FilterTracker
filterTracker.trackClick(facet)
Send conversion events
1
2
3
4
5
// HitsTracker
hitsTracker.trackConvert(hit)
// FilterTracker
filterTracker.trackConversion(facet)
Conversions often happen outside your search pages. For example, the Order completed event for a successful purchase happens in the shopping cart. To capture these conversions, keep track of the query ID across your app.
Event batching
By default, events are sent in batches of 10.
To customize this, adjust the minBatchSize parameter:
1
2
3
4
5
6
7
8
// Customize at registration
registerInsights(context, appID, apiKey, indexName, configuration).apply {
minBatchSize = 1
}
// Customize by getting shared insights
sharedInsights(indexName).apply {
minBatchSize = 1
}
Enable logging
You can also check if you’ve sent an event by enabling logging:
1
2
3
4
5
6
7
8
// Check at insights registration
registerInsights(context, appID, apiKey, indexName, configuration).apply {
loggingEnabled = true
}
// Check by getting shared insights
sharedInsights(indexName).apply {
loggingEnabled = true
}
After you’ve enabled it, check the output for success messages or errors.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Success
[Algolia Insights - appName] Sync succeded for EventsPackage(id: "37E9A093-8F86-4049-9937-23E99E4E4B33", events: [{
eventName = "search result click";
eventType = click;
index = "my index";
objectIDs = (
1234567
);
positions = (
3
);
queryID = 08a76asda34fl30b7d06b7aa19a9e0;
timestamp = 1545069313405;
userToken = "C1D1322E-8CBF-432F-9875-BE3B5AFDA498";
}], region: nil)
//Error
[Algolia Insights - appName] The objectID field is missing (Code: 422)
For positions, the first object in the list of search results has a value of 1 (not 0), the second has a value of 2.
