Guides / Building Search UI

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:

  1. Add the insights client.
  2. Add click events when users click search results.
  3. Track conversions that start in your InstantSearch app.

Add the InstantSearch Insights library

Add the library as a dependency to your build.gradle file:

Copy 
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.

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

To send events without timestamps, and be automatically attributed on the server, set the generateTimestamps parameter to false:

Copy 
1
2

val configuration = Insights.Configuration(generateTimestamps = false)
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
Copy 
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:

Copy 
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

Copy 
1
2
3
4
5

val hitsTracker = HitsTracker(
    eventName = EventName("hits"),
    searcher = searcher,
    insights = sharedInsights(indexName)
)

Create a FilterTracker to track events from filters

Copy 
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

Copy 
1
2
3
4
5

// HitsTracker
hitsTracker.trackView(hit)

// FilterTracker
filterTracker.trackView(facet)

Send click events

Copy 
1
2
3
4
5

// HitsTracker
hitsTracker.trackClick(hit, position)

// FilterTracker
filterTracker.trackClick(facet)

Send conversion events

Copy 
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:

Copy 
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:

Copy 
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.

Copy 
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.

Previous
Installation
Next
Upgrade guide for InstantSearch Android
Did you find this page helpful?
InstantSearch Android v3