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:+'
}

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

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

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.

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.