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.

Look up 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:1.+'
}

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 = "https://us.i.posthog.com";

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

Capturing events

You can send custom events using capture:

posthog.capture("distinct_id_of_the_user", 
    "user_signed_up");

Tip: We recommend using a [object] [verb] format for your event names, where [object] is the entity that the behavior relates to, and [verb] is the behavior itself. For example, project created, user signed up, or invite sent.

Setting event properties

Optionally, you can also include additional information in the event by setting the properties value:

posthog.capture("distinct_id_of_the_user", "user_signed_up", new HashMap<String, Object>() {
  {
    put("login_type", "email");
    put("is_free_trial", true);
  }
});

Person profiles and properties

For backward compatibility, the Java SDK captures identified events by default. These create person profiles. To set person properties in these profiles, include them 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 person properties docs.

To capture anonymous events without person profiles, set the event's $process_person_profile property to false:

posthog.capture("distinct_id", "event_name", new HashMap<String, Object>() {
  {
    put("$process_person_profile", false);
  }
});

Alias

Sometimes, you want to assign multiple distinct IDs to a single user. This is helpful when your primary distinct ID is inaccessible. For example, if a distinct ID used on the frontend is not available in your backend.

In this case, you can use alias to assign another distinct ID to the same user.

posthog.alias("distinct_id", "alias_id");

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

Feature flags

PostHog's feature flags enable you to safely deploy and roll back new features.

Feature flags are not supported yet in our Java SDK. However, you can integrate them into your project by using the PostHog API.