Implement Click and Conversion Analytics

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.

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

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

Sending metrics

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

Insights events (click, conversion, view) used for analytics and/or personalization do not take immediate effect. The delay can range from 10 to 60 minutes depending on how long after the search they are sent. For precise times, see our page on when Insights events take effect.

View events

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

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

Click events

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

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

Conversion events

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

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

Event Batching

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

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

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

User tracking

Any event should have a 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

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

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

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 by altering the enabled setting:

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

1
Insights.shared?.enabled = false

Logging and debugging

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

1
Insights.shared().setLoggingEnabled(true)

1
Insights.shared?.loggingEnabled = 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.