Search documentation...

K
ChangelogBook a demoSign up

Java SDK

The Java SDK makes it easy to track events from Java applications.

Installation

The Java SDK is available via JitPack.

<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>

<dependency>
  <groupId>com.github.ht-sdks.events-sdk-java</groupId>
  <artifactId>analytics</artifactId>
  <version>LATEST</version>
</dependency>

To initialize the Java SDK in your application, create an Analytics instance:

import com.hightouch.analytics.Analytics;

public class Main {
  public static void main(String... args) throws Exception {
    final Analytics analytics =
        Analytics.builder(WRITE_KEY)
            .endpoint(API_ENDPOINT)
            .build();
  }
}

API

Identify

The IdentifyMessage sends an identify event.

Unlike the Browser SDK, it does not persist the user ID and traits locally, so user IDs must be explicitly added to other events. This is because server side events are usually servicing many different users at once.

Example usage:

analytics.enqueue(IdentifyMessage.builder()
    .userId("123")
    .traits(ImmutableMap.builder()
        .put("name", "John Doe")
        .put("email", "test@example.com")
        .build()
    )
);

Method parameters:

ParameterTypeDescription
userIdStringThe user's persistent ID
anonymousIdStringThe user's anonymous ID. This is automatically set if both userId and anonymousId are omitted.
traitsMapAdditional traits about the user, such as email and name.
contextMapOverrides to values in the event context. By default, context contains information autocollected by the SDK.
timestampDateThe date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date.

Track

The TrackMessage sends a track event.

Example usage:

analytics.enqueue(TrackMessage.builder("Item Purchased")
    .userId("123")
    .properties(ImmutableMap.builder()
        .put("revenue", 39.95)
        .put("shipping", "2-day")
        .build()
    )
);

Method parameters:

ParameterTypeDescription
userIdStringThe user's persistent ID
anonymousIdStringThe user's anonymous ID. This is automatically set if both userId and anonymousId are omitted.
eventStringThe name of the event.
propertiesMapAdditional properties about the event, such as product_id.
contextMapOverrides to values in the event context. By default, context contains information autocollected by the SDK.
timestampDateThe date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date.

Page

The PageMessage sends a page event.

Example usage:

analytics.enqueue(PageMessage.builder("Schedule")
    .userId("123")
    .properties(ImmutableMap.builder()
        .put("category", "Sports")
        .put("path", "/sports/schedule")
        .build()
    )
);

Method parameters:

ParameterTypeDescription
userIdStringThe user's persistent ID
anonymousIdStringThe user's anonymous ID. This is automatically set if both userId and anonymousId are omitted.
nameStringThe page's name. For example "Getting started"
propertiesMapAdditional properties about the event, such as url.
contextMapOverrides to values in the event context. By default, context contains information autocollected by the SDK.
timestampDateThe date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date.

Screen

The ScreenMessage sends a screen event.

Example usage:

analytics.enqueue(ScreenMessage.builder("Schedule")
    .userId("123")
    .properties(ImmutableMap.builder()
        .put("category", "Sports")
        .put("path", "/sports/schedule")
        .build()
    )
);

Method parameters:

ParameterTypeDescription
userIdStringThe user's persistent ID
anonymousIdStringThe user's anonymous ID. This is automatically set if both userId and anonymousId are omitted.
nameStringThe screen's name. For example "Getting started"
categoryStringThe screen's category. For example "Docs"
propertiesMapAdditional properties about the event, such as url.
contextMapOverrides to values in the event context. By default, context contains information autocollected by the SDK.
timestampDateThe date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date.

Group

The GroupMessage sends a group event.

Example usage:

analytics.enqueue(GroupMessage.builder("group123")
    .userId("123")
    .traits(ImmutableMap.builder()
        .put("name", "Hightouch")
        .put("size", 50)
        .build()
    )
);

Method parameters:

ParameterTypeDescription
userIdStringThe user's persistent ID
anonymousIdStringThe user's anonymous ID. This is automatically set if both userId and anonymousId are omitted.
groupIdStringThe id for the group.
traitsMapAdditional traits about the group, such as company_name.
contextMapOverrides to values in the event context. By default, context contains information autocollected by the SDK.
timestampDateThe date of the message. When backfilling data, this can be set to a date in the past. By default, this is autoset to the current date.

Flush

The Java 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. flush should be called when shutting down your Java app to make sure no events are lost.

Example usage:

analytics.flush()

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.

Last updated: Mar 12, 2024

On this page

InstallationAPIIdentifyTrackPageScreenGroupFlush

Was this page helpful?