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

# Java Server SDK

> The [Fingerprint Server Java SDK](https://github.com/fingerprintjs/java-sdk) is an easy way to interact with our Server API from your Java application. You can retrieve and manage identification events. View our [Java Server SDK quickstart](/docs/java-server-quickstart) for a step-by-step guide to get started.

## How to install

### Using Maven

Add this dependency to your project's POM:

```xml XML theme={"theme":"github-dark-dimmed"}
<repositories>
  <repository>
    <id>jitpack.io</id>
    <url>https://jitpack.io</url>
  </repository>
</repositories>
```

```xml XML theme={"theme":"github-dark-dimmed"}
<dependency>
  <groupId>com.github.fingerprintjs</groupId>
  <artifactId>java-sdk</artifactId>
  <version>v8.4.0</version>
</dependency>
```

### Using Gradle

Add this dependency to your project's build file:

```groovy Groovy theme={"theme":"github-dark-dimmed"}
// build.gradle
repositories {
  maven { url 'https://jitpack.io' }
}

dependencies {
  implementation "com.github.fingerprintjs:java-sdk:v8.4.0"
}
```

```kotlin Kotlin theme={"theme":"github-dark-dimmed"}
// build.gradle.kts
repositories {
  maven {
    url = uri("https://jitpack.io")
  }
}

dependencies {
  implementation("com.github.fingerprintjs:java-sdk:v8.4.0")
}
```

### Others

Generate the JAR file:

```bash Bash theme={"theme":"github-dark-dimmed"}
./gradlew jar
```

Then manually install `sdk/build/libs/java-sdk-8.4.0.jar`.

## Usage

Initialize the client instance and use it to make API requests. You need to specify your secret API key and region (if it is not US/Global).

```java Java theme={"theme":"github-dark-dimmed"}
import com.fingerprint.v4.api.FingerprintApi;
import com.fingerprint.v4.model.Event;
import com.fingerprint.v4.model.EventSearch;
import com.fingerprint.v4.sdk.ApiClient;
import com.fingerprint.v4.sdk.ApiException;
import com.fingerprint.v4.sdk.Configuration;
import com.fingerprint.v4.sdk.Region;

public class FingerprintApiExample {
  public static void main(String... args) {
    ApiClient client = Configuration.getDefaultApiClient(
      "SECRET_API_KEY",
      Region.GLOBAL
      // Region.EUROPE
      // Region.ASIA
    );
    FingerprintApi api = new FingerprintApi(client);

    // Search events for a specific visitor
    try {
      EventSearch response = api.searchEvents(
        new FingerprintApi.SearchEventsOptionalParams()
          .setVisitorId("VISITOR_ID")
          .setLimit(10)
      );
      System.out.println(response.getEvents());
    } catch (ApiException e) {
      System.err.println(e.getMessage());
    }

    // Get a specific identification event
    try {
      Event event = api.getEvent("EVENT_ID");
      System.out.println(event.getIdentification().getVisitorId());
    } catch (ApiException e) {
      System.err.println(e.getMessage());
    }
  }
}
```

## Migration guide for Java SDK v8

Version 8 migrates the SDK from Server API v3 to v4. This is a breaking change.

### Package rename

The artifact ID changed from `fingerprint-pro-server-api-java-sdk` to `java-sdk`. All import paths changed from `com.fingerprint.*` to `com.fingerprint.v4.*`.

**Gradle (build.gradle):**

```groovy Groovy theme={"theme":"github-dark-dimmed"}
implementation "com.github.fingerprintjs:fingerprint-pro-server-api-java-sdk:v7.x.x" // [!code --]
implementation "com.github.fingerprintjs:java-sdk:v8.4.0" // [!code ++]
```

### Import changes

All imports change from `com.fingerprint.*` to `com.fingerprint.v4.*`:

```java Java theme={"theme":"github-dark-dimmed"}
import com.fingerprint.api.FingerprintApi; // [!code --]
import com.fingerprint.model.EventsGetResponse; // [!code --]
import com.fingerprint.sdk.ApiClient; // [!code --]
import com.fingerprint.sdk.Configuration; // [!code --]
import com.fingerprint.sdk.Region; // [!code --]
import com.fingerprint.v4.api.FingerprintApi; // [!code ++]
import com.fingerprint.v4.model.Event; // [!code ++]
import com.fingerprint.v4.sdk.ApiClient; // [!code ++]
import com.fingerprint.v4.sdk.Configuration; // [!code ++]
import com.fingerprint.v4.sdk.Region; // [!code ++]
```

### `getEvent` return type

`getEvent` now returns `Event` instead of `EventsGetResponse`. The event object has a flatter structure. Smart Signals are now top-level fields instead of nested under `products`:

```java Java theme={"theme":"github-dark-dimmed"}
EventsGetResponse response = api.getEvent("EVENT_ID"); // [!code --]
String visitorId = response.getProducts().getIdentification().getData().getVisitorId(); // [!code --]
BotdBotResult botResult = response.getProducts().getBotd().getData().getBot().getResult(); // [!code --]
Event event = api.getEvent("EVENT_ID"); // [!code ++]
String visitorId = event.getIdentification().getVisitorId(); // [!code ++]
BotResult botResult = event.getBot(); // [!code ++]
```

### `getVisits` replaced by `searchEvents`

`getVisits` and `getRelatedVisitors` have been removed. Use `searchEvents` to query visitor history:

```java Java theme={"theme":"github-dark-dimmed"}
VisitorsGetResponse response = api.getVisits("VISITOR_ID"); // [!code --]
EventSearch response = api.searchEvents( // [!code ++]
  new FingerprintApi.SearchEventsOptionalParams() // [!code ++]
    .setVisitorId("VISITOR_ID") // [!code ++]
    .setLimit(10) // [!code ++]
); // [!code ++]
```

### Handling sealed client results from a v3 JavaScript agent

Java SDK v8 will fail to deserialize the decrypted payload of a [sealed client result](/docs/sealed-client-results) sent by a v3 JavaScript agent into an `Event` because the payload is an `EventsGetResponse` (the v3 event format), not an `Event`.

To upgrade to Java SDK v8 without requiring a concurrent upgrade to the v4 JavaScript agent, you can fall back to using the Server API if unsealing the sealed client results fails.
To enable this fallback path, your frontend must send the event ID alongside the sealed client results, as recommended by the [sealed client results guide](/docs/sealed-client-results#step-3-send-sealed_result-to-your-backend).

Both `Sealed.unsealEventResponse` and `api.getEvent` return an `Event`, so the fallback returns the same type.

```java Java theme={"theme":"github-dark-dimmed"}
// Partial example (imports and surrounding class omitted).
private static Event getEvent(
  FingerprintApi api,
  byte[] sealedResult,
  String eventId,
  Sealed.DecryptionKey[] keys
) throws ApiException {
  // Try to unseal the payload locally first.
  try {
    return Sealed.unsealEventResponse(sealedResult, keys);
  } catch (InvalidSealedDataException e) {
    // Deserialization failed. Fall back to the Server API using the event ID
    // sent alongside the sealed client results.
    System.out.println("Could not unseal result, falling back to Server API: " + e);
    return api.getEvent(eventId);
  }
}
```

## Documentation

You can find the full documentation in the official [GitHub repository](https://github.com/fingerprintjs/java-sdk/).