Android SDK

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:

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:

• AnalyticsContext.java
• Android SDK README – Context

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:

• Options.java
• Android SDK README – Context

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:

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:

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:

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:

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)