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 Dynamic Re-ranking. Algolia uses all valid events for Personalization. Even if you aren’t immediately planning on implementing Personalization, it’s helpful to consider sending events anyway. This lets you implement Personalization later on with a robust corpus of well-formatted user data.
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 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
After registering your index with the Application ID and the API Key, you can start sending metrics.
- 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
| // Customize at registration
registerInsights(context, appID, apiKey, indexName, configuration).apply {
minBatchSize = 1
}
// Customize 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 to opt out, you can honor it with the following code:
1
2
3
| sharedInsights(indexName)?.enabled = false
// Alternatively by getting latest registered Insights instance
sharedInsights?.enabled = false
|
Logging and debugging
Enable logging to check if the engine sent the metric.
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 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)
|
