Skip to content

OpenPanel is an open-source web and product analytics platform, an open-source alternative to Mixpanel with optional self-hosting.

7.4 KB
Raw Blame
---
title: Java
description: The OpenPanel Java SDK allows you to track user behavior in your JVM backend applications.
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Callout } from 'fumadocs-ui/components/callout';
import CommonSdkConfig from '@/components/common-sdk-config.mdx';

The OpenPanel Java SDK allows you to track user behavior in your JVM backend applications. It targets **Java 11+** and works with Spring Boot, Quarkus, Micronaut, plain Java, and more.

<Callout>
View the [Java SDK on GitHub](https://github.com/idcapture/openpanel-java-sdk) for the latest updates and source code.
</Callout>

<Callout type="info">
For Android/Kotlin applications, see the [Kotlin SDK](/docs/sdks/kotlin) instead.
</Callout>

## Installation

<Steps>
### Step 1: Add Dependency

Add the OpenPanel SDK to your project's dependencies:

#### Maven

```xml
<dependency>
    <groupId>fr.idcapture</groupId>
    <artifactId>openpanel-java</artifactId>
    <version>0.4.0</version>
</dependency>
```

#### Gradle (Groovy)

```groovy
implementation 'fr.idcapture:openpanel-java:0.4.0'
```

#### Gradle (Kotlin DSL)

```kotlin
implementation("fr.idcapture:openpanel-java:0.4.0")
```

### Step 2: Initialize

Import the SDK and initialize it with your client ID and secret:

```java
import fr.idcapture.openpanel.OpenPanel;
import fr.idcapture.openpanel.OpenPanelOptions;

OpenPanel op = OpenPanel.create(
    OpenPanelOptions.builder()
        .clientId("YOUR_CLIENT_ID")
        .clientSecret("YOUR_CLIENT_SECRET")
        .build()
);
```

### Configuration Options

<CommonSdkConfig />

Additional Java-specific options:

- `apiUrl` - API endpoint URL (default: `https://api.openpanel.dev`)
- `disabled` - Set to `true` to disable all [event tracking](/features/event-tracking)
- `filter` - A function that will be called before tracking an event. If it returns `false`, the event will not be tracked
- `connectTimeoutSeconds` - Connection timeout in seconds (default: `10`)
- `readTimeoutSeconds` - Read timeout in seconds (default: `30`)
- `maxRetries` - Maximum number of retries for failed requests (default: `3`, set to `0` to disable)
- `initialRetryDelayMs` - Initial retry delay in milliseconds (default: `500`, doubles each attempt)
- `verbose` - Set to `true` to enable verbose logging via `java.util.logging`

#### Full configuration example

```java
OpenPanel op = OpenPanel.create(
    OpenPanelOptions.builder()
        .clientId("YOUR_CLIENT_ID")
        .clientSecret("YOUR_CLIENT_SECRET")
        .apiUrl("https://api.openpanel.dev")
        .disabled(false)
        .filter(name -> !name.startsWith("debug_"))
        .connectTimeoutSeconds(10)
        .readTimeoutSeconds(30)
        .maxRetries(3)
        .initialRetryDelayMs(500)
        .verbose(false)
        .build()
);
```

</Steps>

## Usage

All methods return `CompletableFuture<Void>`. You can ignore the future (fire-and-forget) or chain callbacks for error handling.

### Tracking Events

To track an event:

```java
// Minimal
op.track("page_viewed");

// With properties
op.track("button_clicked", Map.of("button_id", "submit_form"));

// With user
op.track("checkout_started", Map.of("cart_value", 149.99), "user123");

// With user + groups
op.track("report_exported",
    Map.of("format", "pdf"),
    "user123",
    List.of("org_acme")
);
```

### Identifying Users

To identify a user:

```java
// With custom properties only
op.identify("user123", Map.of("plan", "enterprise"));

// With standard fields + custom properties
op.identify("user123", "John", "Doe", "[email protected]", Map.of("tier", "premium"));

// With avatar
op.identify("user123", "John", "Doe", "[email protected]",
    "https://example.com/avatar.png", Map.of("tier", "premium"));
```

### Setting Global Properties

Properties set here are merged into every `track()` call. Caller properties take precedence over global ones.

```java
op.setGlobalProperties(Map.of(
    "app_version", "2.1.0",
    "env", "production"
));

// All subsequent track() calls will include app_version and env automatically
op.track("feature_used", Map.of("feature", "export"));
```

### Incrementing Properties

To increment a numeric property on a user profile:

```java
op.increment("user123", "login_count", 1);
```

### Decrementing Properties

To decrement a numeric property on a user profile:

```java
op.decrement("user123", "credits", 5);
```

### Tracking Revenue

To track revenue events:

```java
// Simple
op.revenue(99.99);

// With user
op.revenue(99.99, "user123");

// With user + extra properties
op.revenue(49.99, "user123", Map.of("currency", "EUR", "plan", "pro"));
```

### Groups

```java
// Create or update a group
op.group("org_acme", "company", "Acme Inc", Map.of("plan", "enterprise", "seats", 25));

// Assign a user to groups
op.assignGroup("user123", List.of("org_acme"));
```

<Callout>
Groups are **not** automatically attached to track events. Pass them explicitly on each `track()` call where needed.
</Callout>

### Shutdown

Shutdown the client cleanly when your application stops:

```java
// Explicit
op.close();

// Or via try-with-resources
try (OpenPanel op = OpenPanel.create(options)) {
    op.track("startup");
}
```

## Advanced Usage

### Error Handling

On API errors (4xx/5xx), the `CompletableFuture` is completed exceptionally with an `HttpTracker.OpenPanelApiException` containing the HTTP status code:

```java
op.track("event")
  .exceptionally(e -> {
      if (e.getCause() instanceof HttpTracker.OpenPanelApiException apiEx) {
          logger.warn("OpenPanel returned {}", apiEx.getStatusCode());
      }
      return null;
  });
```

### Retry Behavior

Failed requests (5xx and network errors) are retried automatically with exponential backoff. Defaults: 3 retries, starting at 500ms (500ms → 1s → 2s). Client errors (4xx) are not retried.

```java
// Customize retry behavior
OpenPanelOptions.builder()
    .clientId("id")
    .maxRetries(5)              // more retries
    .initialRetryDelayMs(1000)  // start at 1s
    .build();

// Disable retries entirely
OpenPanelOptions.builder()
    .clientId("id")
    .maxRetries(0)
    .build();
```

### Custom Event Filtering

You can filter events by name before they are sent:

```java
OpenPanelOptions.builder()
    .clientId("YOUR_CLIENT_ID")
    .filter(eventName -> !eventName.startsWith("internal_"))
    .build();
```

### Disabling Tracking

Useful for local development or testing — no HTTP calls are made:

```java
OpenPanelOptions.builder()
    .clientId("YOUR_CLIENT_ID")
    .disabled(true)
    .build();
```

### Self-Hosted OpenPanel

If you're running a self-hosted OpenPanel instance, set the `apiUrl`:

```java
OpenPanelOptions.builder()
    .clientId("YOUR_CLIENT_ID")
    .apiUrl("https://your-openpanel-instance.com")
    .build();
```

### Debug Logging

Enable verbose mode to log all HTTP requests and responses via `java.util.logging`:

```java
OpenPanelOptions.builder()
    .clientId("YOUR_CLIENT_ID")
    .verbose(true)
    .build();
```

### Kotlin Interop

All property maps use JetBrains `@Nullable` type-use annotations (`Map<String, @Nullable Object>`), so Kotlin sees `Map<String, Any?>` natively — no `@Suppress("UNCHECKED_CAST")` needed.

```kotlin
op.track("checkout", mapOf("amount" to 49.99, "coupon" to null))
```

## Community SDK

<Callout>
The Java SDK is a community-maintained SDK by [idcapture](https://github.com/idcapture). For issues or feature requests, please file an issue on the [Java SDK GitHub repository](https://github.com/idcapture/openpanel-java-sdk).
</Callout>