The InstantSearch Insights Android library allows developers to send click, conversion, and view events. For search-related events, it correlates the event with the queryIDs generated when you’ve set the clickAnalytics parameter to true.
Algolia uses valid search-related events for Click and Conversion Analytics. Click and Conversion Analytics form the foundation for more advanced features like A/B Testing and AI Re-Ranking. Algolia uses all valid events for Personalization. Even if you aren’t planning on implementing Personalization right away, it’s helpful to consider sending events as if you were. This lets you implement Personalization later on with a robust corpus of well-formatted user data.
To learn more about why you would want to send events and which events Algolia uses for which features, please read the guide on capturing user behaviors as events. To make sure you’re following InstantSearch best practices, please read the Getting Started guide before sending events.
Install the InstantSearch Insights library
Add the following dependency to your build.gradle file:
1
| implementation "com.algolia:instantsearch-insights-android:3.+"
|
Initialize the Insights client
You need your Application ID, API Key and the index name to initialize the Insights client.
You can find them on your Algolia account.
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)
|
Sending metrics
You can start sending metrics after registering your index with the Application ID and the API Key.
- Create a
HitsTracker to track hits events.
1
2
3
4
5
| val hitsTracker = HitsTracker(
eventName = EventName("hits"),
searcher = searcher,
insights = sharedInsights(indexName)
)
|
- Create a
FilterTracker to filter events.
1
2
3
4
5
| val filterTracker = FilterTracker(
eventName = EventName("demo"),
searcher = searcher,
insights = sharedInsights(IndexName)
)
|
1
2
3
4
| // HitsTracker
hitsTracker.trackView(hit)
// FilterTracker
filterTracker.trackView(facet)
|
1
2
3
4
| // HitsTracker
hitsTracker.trackClick(hit, position)
// FilterTracker
filterTracker.trackClick(facet)
|
1
2
3
4
| // HitsTracker
hitsTracker.trackConvert(hit)
// FilterTracker
filterTracker.trackConversion(facet)
|
Event batching
By default, events are sent in batches of 10. You can customize this setting with minBatchSize.
1
2
3
4
5
6
7
8
| // at registration
registerInsights(context, appID, apiKey, indexName, configuration).apply {
minBatchSize = 1
}
// or, by getting shared insights
sharedInsights(indexName).apply {
minBatchSize = 1
}
|
User tracking
All events should 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 application, 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)
// application 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 should allow users to opt-out of tracking anytime they want to. When they request opt-out, you can honor it using the following code:
1
2
3
| sharedInsights(indexName)?.enabled = false
// or, by getting latest registered Insights instance
sharedInsights?.enabled = false
|
Logging and debugging
You need to enable logging to check whether the metric was sent.
1
2
3
4
5
6
7
8
| // at insights registration
registerInsights(context, appID, apiKey, indexName, configuration).apply {
loggingEnabled = true
}
// or, by getting shared insights
sharedInsights(indexName).apply {
loggingEnabled = true
}
|
After you enable logging, you can check the output for success messages or errors.
1
2
3
4
5
| // Success
D/Algolia Insights: Index=bestbuy: Sync succeeded for View(eventName=EventName(raw=demo), indexName=bestbuy, userToken=UserToken(raw=userToken), timestamp=1634315597574, queryID=null, resources=ObjectIDs(objectIDs=[1762527]))."
// Error
D/Algolia Insights - indexName The objectID field is missing (Code: 422)
|
