Guides / Building Search UI / Going further

Send Events with InstantSearch Android

The InstantSearch Insights 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 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.

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

First, you need to initialize the Insights client with your application ID, API key, and index name: find them in the API Keys section of the dashboard. Every event you send should have a userToken field to specify the user it relates to.

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 events

Once you’ve registered your index with the application ID and the API key, you can start sending events. For examples of the different kinds of events and what user behaviors translate into them, refer to the guide on capturing user behaviors as events.

Insights events (view, click, and conversion) don’t take immediate effect. There’s a delay of from a few minutes up to an hour (depending on whether they’re sent after a search or not and how long after a search they’re sent).

For a better estimation, see how long it takes for Insights events to be taken into account.

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)
)

Send view events

1
2
3
4
// HitsTracker
hitsTracker.trackView(hit)
// FilterTracker
filterTracker.trackView(facet)

Send click events

1
2
3
4
// HitsTracker
hitsTracker.trackClick(hit, position)
// FilterTracker
filterTracker.trackClick(facet)

Send conversion events

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

To check if you’ve sent an event, first enable 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, you can 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.

Did you find this page helpful?