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, Highotuch automatically collects context such as the device operating system. This context is forwarded with each event.
To modify the context sent with each event, modify the context dictionary
returned by getAnalyticsContext(). You may add additional values, as well as
remove default metadata.
You may also override the context in individual event calls. See the per-event methods for more information.
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. 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)