Concepts / Getting insights and analytics / Send Personalization Events with Android InstantSearch
Apr. 24, 2019

Send Personalization Events with Android InstantSearch

Introduction

InstantSearch Insights Android library allows developers to report personalization events.

Click and conversion events sent can be used for personalization purposes as well. Some events however can only be used for personalization purposes.

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

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.

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

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

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

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

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

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

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

Did you find this page helpful?