Java

⚠️ Warning - This is in beta and may break.

This is an optional library you can install if you're working with Java. It uses an internal queue to make calls fast and non-blocking. It also batches requests and flushes asynchronously, making it perfect to use in any part of your web app or other server side application that needs performance.

Installation

The best way to install the PostHog Java SDK is with a build system like Gradle or Maven. This ensures you can easily upgrade to the latest versions.

Lookup the latest version in com.posthog.java.

Gradle

All you need to do is add the posthog module to your build.gradle:

dependencies {
  implementation 'com.posthog.java:posthog:+'
}

Maven

All you need to do is add the posthog module to your pom.xml:

<dependency>
  <groupId>com.posthog.java</groupId>
  <artifactId>posthog</artifactId>
  <version>LATEST</version>
</dependency>

Other

See the com.posthog.java in the Maven Central Repository. Clicking on the latest version shows you options for adding dependencies for other build systems.

Setup

import com.posthog.java.PostHog;

class Sample {
  private static final String POSTHOG_API_KEY = "<ph_project_api_key>";
  private static final String POSTHOG_HOST = "<ph_instance_address>";

  public static void main(String args[]) {
    PostHog posthog = new PostHog.Builder(POSTHOG_API_KEY).host(POSTHOG_HOST).build();

    // run commands

    posthog.shutdown();  // send the last events in queue
  }
}

Making calls

Capture

Capture allows you to capture anything a user does within your system, which you can later use in PostHog to find patterns in usage, work out which features to improve or where people are giving up.

A capture call requires:

• distinct id which uniquely identifies your user
• event name to specify the event

We recommend naming events with "[noun][verb]", such as movie played or movie updated, in order to easily identify what your events mean later on (we know this from experience).

Optionally you can submit:

• properties which is a dictionary with any information you'd like to add

posthog.capture("distinct id", "movie played", new HashMap<String, Object>() {
  {
    put("movie_id", 123);
    put("category", "romcom");
  }
});

Setting user properties

To set user properties, include the properties you'd like to set when capturing an event:

posthog.capture("distinct_id", "event_name", new HashMap<String, Object>() {
  {
    put("$set",  new HashMap<String, Object>() {       
      {
        put("name", "Max Hedgehog");
      }
    });
    put("$set_once",  new HashMap<String, Object>() {
      {
        put("initial_url", "/blog");
      }
    });
  }
});

For more details on the difference between $set and $set_once, see our user properties docs.

Alias

Sometimes, you may want to assign multiple distinct IDs to a single user. This is helpful in scenarios where your primary distinct ID may be inaccessible. For example, if a distinct ID which is typically used on the frontend is not available in certain parts of your backend code. In this case, you can use alias to assign another distinct ID to the same user.

We strongly recommend reading our docs on alias to best understand how to correctly use this method.