ChangelogBook a demoSign up

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:

OptionTypeDescription
defaultApiHostStringThe API host to send the tracked events to.
flushQueueSizeintThe number of events to queue before sending events to the Hightouch API. Defaults to 20.
flushIntervalintThe maximum amount of time (in seconds) to store events locally before forwarding to Hightouch. Defaults to 30 seconds.
trackApplicationLifecycleEventsn/aAutomatically track application lifecycle events (like opening the application).
recordScreenViewsn/aAutomatically track screen views.
trackDeepLinksn/aAutomatically 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:

ParameterTypeDescription
userIdStringThe user's persistent ID
traitsTraits (optional)Additional traits about the user, such as email and name.
optionsOptions (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:

ParameterTypeDescription
nameStringThe name of the event.
propertiesProperties (optional)Additional properties about the event, such as product_id.
optionsOptions (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:

ParameterTypeDescription
categoryString (optional if name is supplied)The screen's category. For example "Docs"
titleString (optional if category is supplied)The screen's name. For example "Getting started"
propertiesProperties (optional)Additional properties about the event, such as from_link.
optionsOptions (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:

ParameterTypeDescription
groupIdStringThe id for the group.
traitsTraits (optional)Additional traits about the group, such as company_name.
optionsOptions (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)

Ready to get started?

Jump right in or a book a demo. Your first destination is always free.

Book a demoSign upBook a demo

Need help?

Our team is relentlessly focused on your success. Don't hesitate to reach out!

Feature requests?

We'd love to hear your suggestions for integrations and other features.

Privacy PolicyTerms of Service

Last updated: Oct 4, 2023

On this page
  • Installation
  • Initialization
  • Context
  • API
  • Identify
  • Track
  • Screen
  • Group
  • Flush
  • Reset
  • Opt out

Was this page helpful?