> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hightouch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK

> Hightouch's Java SDK for collecting events

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

## Installation

The Java SDK is available via
[JitPack](https://jitpack.io/#ht-sdks/events-sdk-java/).

**Maven**

```
<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>
```

**Gradle**

```
allprojects {
  repositories {
    ...
    maven { url 'https://jitpack.io' }
  }
}

dependencies {
  ...
  compile 'com.github.ht-sdks.events-sdk-java:analytics:+'
}
```

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](https://docs.hightouch.com/events/sdks/browser.md), 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**:

| Parameter | Type | Description |
| - | - | - |
| `userId` | String | The user's persistent ID |
| `anonymousId` | String | The user's anonymous ID. This is automatically set if both `userId` and `anonymousId` are omitted. |
| `traits` | Map | Additional traits about the user, such as `email` and `name`. |
| `context` | Map | Overrides to values in the event `context`. By default, `context` contains information autocollected by the SDK. |
| `timestamp` | Date | The 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**:

| Parameter | Type | Description |
| - | - | - |
| `userId` | String | The user's persistent ID |
| `anonymousId` | String | The user's anonymous ID. This is automatically set if both `userId` and `anonymousId` are omitted. |
| `event` | String | The name of the event. |
| `properties` | Map | Additional properties about the event, such as `product_id`. |
| `context` | Map | Overrides to values in the event `context`. By default, `context` contains information autocollected by the SDK. |
| `timestamp` | Date | The 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**:

| Parameter | Type | Description |
| - | - | - |
| `userId` | String | The user's persistent ID |
| `anonymousId` | String | The user's anonymous ID. This is automatically set if both `userId` and `anonymousId` are omitted. |
| `name` | String | The page's name. For example "Getting started" |
| `properties` | Map | Additional properties about the event, such as `url`. |
| `context` | Map | Overrides to values in the event `context`. By default, `context` contains information autocollected by the SDK. |
| `timestamp` | Date | The 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**:

| Parameter | Type | Description |
| - | - | - |
| `userId` | String | The user's persistent ID |
| `anonymousId` | String | The user's anonymous ID. This is automatically set if both `userId` and `anonymousId` are omitted. |
| `name` | String | The screen's name. For example "Getting started" |
| `category` | String | The screen's category. For example "Docs" |
| `properties` | Map | Additional properties about the event, such as `url`. |
| `context` | Map | Overrides to values in the event `context`. By default, `context` contains information autocollected by the SDK. |
| `timestamp` | Date | The 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**:

| Parameter | Type | Description |
| - | - | - |
| `userId` | String | The user's persistent ID |
| `anonymousId` | String | The user's anonymous ID. This is automatically set if both `userId` and `anonymousId` are omitted. |
| `groupId` | String | The id for the group. |
| `traits` | Map | Additional traits about the group, such as `company_name`. |
| `context` | Map | Overrides to values in the event `context`. By default, `context` contains information autocollected by the SDK. |
| `timestamp` | Date | The 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()
```