Concepts / Building Search UI / Plug analytics
Jan. 07, 2019

Plug analytics

Using Algolia Insights with Android InstantSearch

Introduction

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.

Once a search has been initialized and the queryID received, the library currently supports two types of events - click and conversion.

Getting started

Supported platforms

InstantSearch Insights Android is supported on Android devices starting from SDK 14 (Ice Cream Sandwich) and is usable from both Kotlin and Java code.

Install

Add jCenter to your repositories in build.gradle

1
2
3
4
5
6
allprojects {
    repositories {
        // [...]
        jcenter()
    }
}

Add the following dependency to your Gradle file

1
2
3
4
5
dependencies {
    // [...]
    implementation 'com.algolia.instantsearch-android:insights:1.+'
    // [...]
}

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.

Kotlin

1
2
3
4
5
val configuration = Insights.Configuration(
    connectTimeoutInMilliseconds= 5000,
    readTimeoutInMilliseconds = 5000
)
Insights.register("testApp", "testKey", "indexName", configuration)

Java

1
2
Insights.Configuration configuration = new Insights.Configuration(5000, 5000);
Insights.register(context,  "testApp", "testKey",  "indexName", configuration);

Sending metrics

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

View events

Kotlin

1
2
Insights.shared("indexName").viewed("eventName", "indexName", EventObjects.IDs("objectID1", "objectID2"))
Insights.shared("indexName").viewed("eventName", "indexName", EventObjects.Filters("foo:bar", "foo:baz"))

Java

1
2
3
Insights.shared("indexName").viewed("eventName", "indexName", new EventObjects.IDs("objectID1", "objectID2"));
Insights.shared("indexName").viewed("eventName", "indexName", new EventObjects.Filters("foo:bar", "foo:baz"));

Click events

Kotlin

1
2
3
Insights.shared?.clicked("eventName", "indexName", EventObjects.IDs("objectID1", "objectID2"))
Insights.shared?.clicked("eventName", "indexName", EventObjects.Filters("foo:bar", "foo:baz"))
Insights.shared?.clickedAfterSearch("eventName", "indexName", "queryID", EventObjects.IDs("objectID1", "objectID2"), listOf(0, 3))

Java

1
2
3
Insights.shared().clicked("eventName", "indexName", new EventObjects.IDs("objectID1", "objectID2"));
Insights.shared().clicked("eventName", "indexName", new EventObjects.Filters("foo:bar", "foo:baz"));
Insights.shared().clickedAfterSearch("eventName", "indexName", "queryID", new EventObjects.IDs("objectID1", "objectID2"), Arrays.asList(0, 3));

Conversion events

Kotlin

1
2
3
Insights.shared?.converted("eventName", "indexName", EventObjects.IDs("objectID1", "objectID2"))
Insights.shared?.converted("eventName", "indexName", EventObjects.Filters("foo:bar", "foo:baz"))
Insights.shared?.convertedAfterSearch("eventName", "indexName", "queryID", EventObjects.IDs("objectID1", "objectID2"))

Java

1
2
3
Insights.shared().converted("eventName", "indexName", new EventObjects.IDs("objectID1", "objectID2"));
Insights.shared().converted("eventName", "indexName", new EventObjects.Filters("foo:bar", "foo:baz"));
Insights.shared().convertedAfterSearch("eventName", "indexName", "queryID", new EventObjects.IDs("objectID1", "objectID2"));

Event Batching

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

Kotlin

1
Insights.shared?.minBatchSize = 1 // Sends each event as soon as it is tracked

Java

1
Insights.shared().setMinBatchSize(1); // Sends each event as soon as it is tracked

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

Kotlin

1
2
3
4
5
6
7
8
9
10
11
12
13
// Global userToken default value
val configuration = Insights.Configuration(
    connectTimeoutInMilliseconds= 5000,
    readTimeoutInMilliseconds = 5000,
    defaultUserToken = "foo"
)
Insights.register("testApp", "testKey", "indexName", configuration)

// Application userToken, overrides global default
Insights.shared?.userToken = "bar"

// Event usertoken, overrides previous defaults
Insights.shared?.clicked(Event.clicked("eventName", "indexName", "userToken", System.currentTimeMillis(), "queryId", Arrays.asList("objectID1", "objectID2")))

Java

1
2
3
4
5
6
7
8
9
// Global userToken default value
Insights.Configuration configuration = new Insights.Configuration(5000, 5000, "foo");
Insights.register(context,  "testApp", "testKey",  "indexName", configuration);

// Application userToken, overrides global default
Insights.shared?.userToken = "bar"

// Event usertoken, overrides previous defaults
Insights.shared?.clicked(Event.clicked("eventName", "indexName", "userToken", System.currentTimeMillis(), "queryId", Arrays.asList("objectID1", "objectID2")))

Java

1
2
3
4
5
6
7
8
9
// Global userToken default value
Insights.Configuration configuration = new Insights.Configuration(5000, 5000, "foo");
Insights.register(context,  "testApp", "testKey",  "indexName", configuration);

// Application userToken, overrides global default
Insights.shared().setUserToken("bar");

// Event userToken, overrides previous defaults
Insights.shared().clicked(new Event.clicked("eventName", "indexName", "userToken", System.currentTimeMillis(), "queryId", Arrays.asList("objectID1", "objectID2")));

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

Kotlin

1
Insights.shared?.enabled = false

Java

1
Insights.shared().setEnabled(false);

Logging and debuging

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

1
Insights.shared?.loggingEnabled = true
1
Insights.shared().setLoggingEnabled(true)

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

1
2
3
4
5
// Success
D/Algolia Insights - indexName Sync succeeded for Click(params: {"position": 2, "queryID": 74e382ecaf889f9f2a3df0d4a9742dfb,"objectID": 85725102})

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

Getting help

Getting involved

Did you find this page helpful?