The Android SDK makes it easy to track events from Java and Kotlin Android applications.
Installation
The Android SDK is hosted on Jitpack.
You may install it via Gradle by adding it to your settings.gradle
and build.gradle
.
// settings.gradle
allprojects {
repositories {
maven { url 'https://jitpack.io' }
}
}
// build.gradle
dependencies {
implementation 'com.github.ht-sdks.events-sdk-android:analytics:0.+'
}
Initialization
You should initialize the SDK in a central location and store it in a variable
for use across your application. For example, you may want to initialize it in
your application's onCreate
callback. After initialization, you can use the
SDK anywhere you import the Analytics
class via the singleton instance.
Kotlin example:
import com.hightouch.analytics.Analytics
val analytics = Analytics.Builder(context, "YOUR_WRITE_KEY")
.defaultApiHost("us-east-1.hightouch-events.com/v1")
.trackApplicationLifecycleEvents()
.build()
Analytics.setSingletonInstance(analytics)
Java example:
import com.hightouch.analytics.Analytics
Analytics analytics = new Analytics.Builder(context, "YOUR_WRITE_KEY")
.defaultApiHost("us-east-1.hightouch-events.com/v1")
.trackApplicationLifecycleEvents()
.build();
Analytics.setSingletonInstance(analytics);
Configuration options:
Option | Type | Description |
---|---|---|
defaultApiHost | String | The API host to send the tracked events to. |
flushQueueSize | int | The number of events to queue before sending events to the Hightouch API. Defaults to 20. |
flushInterval | int | The maximum amount of time (in seconds) to store events locally before forwarding to Hightouch. Defaults to 30 seconds. |
trackApplicationLifecycleEvents | n/a | Automatically track application lifecycle events (like opening the application). |
recordScreenViews | n/a | Automatically track screen views. |
trackDeepLinks | n/a | Automatically track deep links. |
Context
By default, Hightouch automatically collects contextual metadata with each event, such as the device operating system. This context is forwarded with each event.
Modify global context
To customize the default context sent with every event, use the getAnalyticsContext()
method. This allows you to add or remove metadata that will be included with all subsequent events.
For example, to set UTM campaign parameters globally:
AnalyticsContext context = Analytics.with(context).getAnalyticsContext();
context.putValue("custom_key", "custom_value");
This applies the campaign data to every future event in the session.
For more information, see:
Override context per event
You can override the context for an individual track()
or identify()
call by passing an Options
object as the third argument. This is useful when you want to apply custom context — like UTM campaign parameters — to a single event.
ValueMap campaign = new ValueMap()
.putValue("utm_source", "adwords")
.putValue("utm_medium", "cpc")
.putValue("utm_campaign", "product_launch");
ValueMap contextMap = new ValueMap().putValue("campaign", campaign);
Options options = new Options().setContext(contextMap);
Analytics.with(context).track("Product Viewed", null, options);
This will attach campaign context only to the specified event.
For implementation details, see:
API
Identify
The identify
method sends an identify
event. It accepts user id and trait
information for the current user -- if you only have partial information, you
can just supply a single parameter.
Java method signature:
Analytics.with(context).identify("userId", new Traits().putEmail("email"), null);
Kotlin method signature:
Analytics.with(context).identify("userId", Traits().putEmail("email"), null);
Method parameters:
Parameter | Type | Description |
---|---|---|
userId | String | The user's persistent ID |
traits | Traits (optional) | Additional traits about the user, such as email and name . |
options | Options (optional) | Overrides to the event's context may be passed through the options object. This includes setting custom fields like campaign data. Note that this overrides the default context. |
Track
The track
method sends a track
event. The event name is required, and
additional properties that describe the event may be supplied.
Java method signature:
Analytics.with(context).track("eventName", new Properties().putValue("custom", "property"), null);
Kotlin method signature:
Analytics.with(context).track("eventName", Properties().putValue("custom", "property"), null);
Method parameters:
Parameter | Type | Description |
---|---|---|
name | String | The name of the event. |
properties | Properties (optional) | Additional properties about the event, such as product_id . |
options | Options (optional) | Overrides to the event's context may be passed through the options object. Note that this overrides the default context. |
Screen
The screen
method sends a screen
event. The screen title is required, and
additional information about the screen's category and properties may be
supplied.
Java method signature:
Analytics.with(context).screen("category", "name", new Properties().putValue("custom", "property"), null);
Kotlin method signature:
Analytics.with(context).screen("category", "name", Properties().putValue("custom", "property"), null);
Method parameters:
Parameter | Type | Description |
---|---|---|
category | String (optional if name is supplied) | The screen's category. For example "Docs" |
title | String (optional if category is supplied) | The screen's name. For example "Getting started" |
properties | Properties (optional) | Additional properties about the event, such as from_link . |
options | Options (optional) | Overrides to the event's context may be passed through the options object. Note that this overrides the default context. |
Group
The group
method sends a group
event.
The id identifying the user's group is required. Additional traits on the group can be provided.
Java method signature:
Analytics.with(context).group("groupId", new Traits().putValue("custom", "property"), null);
Kotlin method signature:
Analytics.with(context).group("groupId", Traits().putValue("custom", "property"), null);
Method parameters:
Parameter | Type | Description |
---|---|---|
groupId | String | The id for the group. |
traits | Traits (optional) | Additional traits about the group, such as company_name . |
options | Options (optional) | Overrides to the event's context may be passed through the options object. Note that this overrides the default context. |
Flush
The Android SDK buffers events locally before sending them to Hightouch's servers. This minimizes the number of requests made by the SDK and makes the tracking non-blocking.
To force the local buffer to be sent to Hightouch immediately call the flush
method.
Method signature:
Analytics.with(context).flush()
Reset
The reset
method resets the identify
and group
for the local session.
The reset
method should be called when users log out. This way, if the user
logs back in with another account, the userIds and traits from the different
sessions remain separate.
Method signature:
Analytics.with(context).reset()
Opt out
The optOut
method disabled event tracking. When called, events are not sent
to Hightouch's servers.
Note that the opt out persists across device reboots. To opt back in to
tracking, pass false
to optOut
.
Method signature:
Analytics.with(context).optOut(true)