Skip to main content
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:
gradle
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.
Kotlin
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:
Kotlin
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
Kotlin
// 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:
Kotlin
sharedInsights(indexName)?.enabled = false
// Alternatively, by getting the latest registered Insights instance
sharedInsights?.enabled = false

​
Enable automatic view events tracking

InstantSearch can automatically send view events when hits are returned from Algolia. To enable this feature, set isAutoSendingHitsViewEvents to true when you initialize HitsSearcher:
Kotlin
val searcher = HitsSearcher(
  applicationID = ApplicationID("ALGOLIA_APPLICATION_ID"),
  apiKey = APIKey("ALGOLIA_SEARCH_API_KEY"),
  indexName = IndexName("indexName"),
  isAutoSendingHitsViewEvents = true
)

​
Create a HitsTracker to track events from search results

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

​
Create a FilterTracker to track events from filters

Kotlin
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

Kotlin
// HitsTracker
hitsTracker.trackView(hit)

// FilterTracker
filterTracker.trackView(facet)

​
Send click events

Kotlin
// HitsTracker
hitsTracker.trackClick(hit, position)

// FilterTracker
filterTracker.trackClick(facet)

​
Send conversion events

Kotlin
// 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:
Kotlin
// 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:
Kotlin
// 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. 
// 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 the positions parameter of the clickedObjectIdsAfterSearch method, the first object in the list of search results has a value of 1 (not 0), the second has a value of 2.