InstantSearch Insights for Android

InstantSearch Insights Android library allows developers to report click and conversion metrics related to search queries. It does so by correlating events with queryIDs generated by the search API when a query parameter clickAnalytics=true is set.

⚠️ Important: this library is not compatible with the older insights library.

Getting started

InstantSearch Insights is supported on Android devices starting from SDK 21 and it is built on top of Algolia's Kotlin API Client.

Install

You can add InstantSearch Insights to your Android application by adding the following line to your build.gradle's dependencies.

implementation "com.algolia:instantsearch-insights-android:$instantsearch_version"

Quick Start

Initialize the Insights client

You first need to initialize the Insights client. For that you need your Application ID, API Key and the ** index name**. You can find them on your Algolia account.

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

Once that you registered your index with the Application ID and the API Key you can easily start sending metrics

Create a HitsTracker to track hits events:

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

Create a FilterTracker for filter events:

val filterTracker = FilterTracker(
    eventName = EventName("demo"),
    searcher = searcher,
    insights = sharedInsights(IndexName)
)

View events

Tracker	Command
Hits	`hitsTracker.trackView(hit)`
Filters	`filterTracker.trackView(facet)`

Click events

Tracker	Command
Hits	`hitsTracker.trackClick(hit, position)`
Filters	`filterTracker.trackClick(facet)`

Conversion events

Tracker	Command
Hits	`hitsTracker.trackConvert(hit)`
Filters	`filterTracker.trackConversion(facet)`

Event Batching

By default, events are only sent by batches of 10. You can customize this setting with minBatchSize:

// At insights registration
registerInsights(context, appID, apiKey, indexName, configuration).apply {
    minBatchSize = 1
}
// Or, by getting shared insights
sharedInsights(indexName).apply {
    minBatchSize = 1
}

User tracking

Any event should have an userToken field to specify the user it relates to. You can set it in three ways:

Globally for all events
Per application, for every event tracked by this app
Individually on an event

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

sharedInsights(indexName)?.enabled = false
// Or, by getting latest registered Insights instance
sharedInsights?.enabled = false

Logging and debuging

In case you want to check if the metric was sent correctly, you need to enable the logging first

// At insights registration
registerInsights(context, appID, apiKey, indexName, configuration).apply {
    loggingEnabled = true
}
// Or, by getting shared insights
sharedInsights(indexName).apply {
    loggingEnabled = true
}

After you enabled it, you can check the output for success messages or errors

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

To get a more meaningful search experience, please follow our Getting Started Guide.

Upload mechanism

Events are stored in a SharedPreference database. Each time an event is successfully uploaded, it is removed from the database. An event can be updated using two distinct mechanisms:

Single upload attempt

Every time a new event is stored in the database, the following check is performed:

If the number of events is superior or equal to minBatchSize, an attempt at uploading all events is performed. If the attempt fails, because of a network issue for example, it will not be retried, and events remain stored in the database. If you set minBatchSize to 1, an upload attempt will be performed each time a new event is generated.

Periodic upload

The Insights library relies on a third party library WorkManager. Every 15 minutes, a job will run in the background, whether the application is launched in the foreground or not. Each time a job runs, it will attempt to upload all events stored in the database. If it fails, because of a network issue for example, it will be retried later. The 15 minutes delay between each attempt is enforced by the Android system. It does not allow for a shorter delay, for battery saving reason. You can however configure a longer delay, by setting an higher value than 15 to the variable debouncingIntervalInMinutes. Any value below 15 will be ignored, and the 15 minutes delay will remain.

License

InstantSearch Android is licensed under Apache V2.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!