Send Insights Events
On this page
The InstantSearch Insights Android library allows developers to send click, conversion, and view events. For search-related events, it correlates the event with the queryIDs generated when you’ve set the clickAnalytics parameter to true.
Algolia uses valid search-related events for Click and Conversion Analytics. Click and Conversion Analytics form the foundation for more advanced features like A/B Testing and Dynamic Re-Ranking. Algolia uses all valid events for Personalization. Even if you aren’t planning on implementing Personalization right away, it’s helpful to consider sending events as if you were. This lets you implement Personalization later on with a robust corpus of well-formatted user data.
To learn more about why you would want to send events and which events Algolia uses for which features, please read the guide on capturing user behaviors as events. To make sure you’re following InstantSearch best practices, please read the Getting Started guide before sending events.
Supported platforms
- InstantSearch Insights Android is supported on Android devices starting from SDK 14 (Ice Cream Sandwich).
- You can use either Kotlin or Java code.
Install the InstantSearch Insights library
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:3.+'
// [...]
}
Initialize the Insights client
First, you need to initialize the Insights client. For that you need your application ID, API key, and the index name. You can find them in the API Keys section of the dashboard.
1
2
Insights.Configuration configuration = new Insights.Configuration(5000, 5000);
Insights.register(context, "YourApplicationID", "YourAdminAPIKey", "indexName", configuration);
Sending events
Once that you registered your index with the application ID and the API key, you can start sending events. For examples of the different kinds of events and what user behaviors translate into them, please refer to the guide on capturing user behaviors as events.
Insights events (view, click, and conversion) don’t take immediate effect. The delay can range from a few minutes to an hour, depending on whether they are sent after a search or not, and how long after a search they are sent. For precise timeframes, see our page on when Insights events take effect.
Tracking users behaviors with the userToken
Every event you send 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")));
Allowing users to 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);
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"));
Conversion events don’t always happen on a search results page. For example, a user could buy an item from a product detail page. That means you need to pass the queryID to the detail page. The keeping track of queryID guide shows how to use query parameters to track the queryID.
Batching events
By default, events are sent in batches of 10. You can customize this setting with minBatchSize:
1
Insights.shared().setMinBatchSize(1); // Sends each event as soon as it is tracked
Logging and debugging
In case you want to check if you’ve correctly sent an event, 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)
