README.md

Fingerprint Pro Server API Java SDK

Fingerprint is a device intelligence platform offering 99.5% accurate visitor identification. The Fingerprint Server Java SDK is an easy way to interact with the Fingerprint Server API from your Java application. You can retrieve visitor history or individual identification events.

Automatically generated by the OpenAPI Generator

Requirements

The following versions of Gradle/Maven are supported

• Maven (3.8.3+)
• Gradle (7.2+)

The following versions of Java are supported

• Java 11
• Java 17
• Java 21

Installation

Maven users

Add this dependency to your project's POM:

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependency>
  <groupId>com.github.fingerprintjs</groupId>
  <artifactId>fingerprint-pro-server-api-java-sdk</artifactId>
  <version>v7.0.0-develop.0</version>
</dependency>

Gradle users

Add this dependency to your project's build file (build.gradle or build.gradle.kts):

// build.gradle
repositories {
  maven { url 'https://jitpack.io' }
}

dependencies {
  implementation "com.github.fingerprintjs:fingerprint-pro-server-api-java-sdk:v7.0.0-develop.0"
}

// build.gradle.kts

repositories {
  maven {
    url = uri("https://jitpack.io")
  }
}

dependencies {
  implementation("com.github.fingerprintjs:fingerprint-pro-server-api-java-sdk:v7.0.0-develop.0")
}

Others

At first generate the JAR by executing:

./gradlew jar

Then manually install the following JARs:

• target/fingerprint-pro-server-api-sdk-7.0.0-develop.0.jar

Getting Started

Please follow the installation instruction and execute the following Java code:

package main;

import com.fingerprint.api.FingerprintApi;
import com.fingerprint.model.EventsGetResponse;
import com.fingerprint.model.EventsUpdateRequest;
import com.fingerprint.model.VisitorsGetResponse;
import com.fingerprint.sdk.ApiClient;
import com.fingerprint.sdk.ApiException;
import com.fingerprint.sdk.Configuration;
import com.fingerprint.sdk.Region;

public class FingerprintApiExample {
    // Fingerprint Pro Secret API Key
    private static final String FPJS_API_SECRET = "Fingerprint Pro Secret API Key";
    // A mandatory visitorId of a specific visitor
    private static final String FPJS_VISITOR_ID = "visitorId";
    // An optional requestId made by a specific visitor
    private static final String FPJS_REQUEST_ID = "requestId";
    // An optional linkedId of the visit
    private static final String FPJS_LINKED_ID = "linkedId";
    // An optional parameter limiting scanned results
    private static final Integer LIMIT = 10;
    // An optional parameter used to paginate results, see lastTimestamp
    private static final String PAGINATION_KEY = "1683900801733.Ogvu1j";

    public static void main(String... args) {
        // Create a new api client instance from Configuration with your Fingerprint Pro Server API Key and your Fingerprint Pro Server API Region.
        /*
        You can specify a region on getDefaultApiClient function's second parameter
        If you leave the second parameter empty, then Region.GLOBAL will be used as a default region
        Options for regions are:
        Region.GLOBAL
        Region.EUROPE
        Region.ASIA
        */
        ApiClient client = Configuration.getDefaultApiClient(FPJS_API_SECRET, Region.EUROPE);
        FingerprintApi api = new FingerprintApi(client);
        // Get an event with a given requestId
        try {
            // Fetch the event with a given requestId
            EventsGetResponse response = api.getEvent(FPJS_REQUEST_ID);
            System.out.println(response.getProducts().toString());
        } catch (ApiException e) {
            System.err.println("Exception when calling FingerprintApi.getEvent:" + e.getMessage());
        }

        // Update an event with a given requestId
        try {
            EventsUpdateRequest request = new EventsUpdateRequest();
            request.setLinkedId("myNewLinkedId");
            api.updateEvent(FPJS_REQUEST_ID, request);
        } catch (ApiException e) {
            System.err.println("Exception when calling FingerprintApi.updateEvent:" + e.getMessage());
        }

        // Get a specific visitor's all visits
        try {
            // Fetch all visits with a given visitorId, with a page limit
            VisitorsGetResponse response = api.getVisits(FPJS_VISITOR_ID, null, null, LIMIT, null, null);
            System.out.println(response.getVisits().toString());
        } catch (ApiException e) {
            System.err.println("Exception when calling FingerprintApi.getVisits:" + e.getMessage());
        }

        // Get a specific visitor's all visits with a linkedId
        try {
            // Fetch all visits with a given visitorId, with a page limit, skipping the first visit
            VisitorsGetResponse response = api.getVisits(FPJS_VISITOR_ID, null, FPJS_LINKED_ID, LIMIT, PAGINATION_KEY, null);
            System.out.println(response.getVisits().toString());
        } catch (ApiException e) {
            System.err.println("Exception when calling FingerprintApi.getVisits:" + e.getMessage());
        }

        // Use all the parameters on getVisits
        try {
            // Fetch the visitor's all visits with a given requestId and linkedId with a page limit while skipping the first visit
            VisitorsGetResponse response = api.getVisits(FPJS_VISITOR_ID, FPJS_REQUEST_ID, FPJS_LINKED_ID, LIMIT, PAGINATION_KEY, null);
            System.out.println(response.getVisits().toString());
        } catch (ApiException e) {
            System.err.println("Exception when calling FingerprintApi.getVisits:" + e.getMessage());
        }

        // Delete visitor data with a given visitorID
        try {
            api.deleteVisitorData(FPJS_VISITOR_ID);
        } catch (ApiException e) {
            System.err.println("Exception when calling FingerprintApi.deleteVisitorData:" + e.getMessage());
        }
    }
}

Sealed results

This SDK provides utility methods for decoding sealed results.

package com.fingerprint.example;

import com.fingerprint.Sealed;
import com.fingerprint.model.EventsGetResponse;

import java.util.Base64;

public class SealedResults {
    public static void main(String... args) throws Exception {
        // Sealed result from the frontend.
        String SEALED_RESULT = System.getenv("BASE64_SEALED_RESULT");

        // Base64 encoded key generated in the dashboard.
        String SEALED_KEY = System.getenv("BASE64_KEY");

        final EventsGetResponse event = Sealed.unsealEventResponse(
                Base64.getDecoder().decode(SEALED_RESULT),
                // You can provide more than one key to support key rotation. The SDK will try to decrypt the result with each key.
                new Sealed.DecryptionKey[]{
                        new Sealed.DecryptionKey(
                                Base64.getDecoder().decode(SEALED_KEY),
                                Sealed.DecryptionAlgorithm.AES_256_GCM
                        )
                }
        );

        // Do something with unsealed response, e.g: send it back to the frontend.
    }
}

To learn more, refer to example located in src/examples/java/com/fingerprint/example/SealedResults.java.

Webhook signature validation

This SDK provides utility method for verifying the HMAC signature of the incoming webhook request.

Here is an example implementation using Spring Boot:

import com.fingerprint.sdk.Webhook;

@RestController
class WebhookController {

    @PostMapping("/api/webhook")
    public ResponseEntity<String> webhookHandler(@RequestBody byte[] webhook, @RequestHeader HttpHeaders headers) {
        final String secret = System.getenv("WEBHOOK_SIGNATURE_SECRET");
        if (secret == null || secret.isEmpty()) {
            return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body("Secret key is not configured");
        }

        final String signature = headers.getFirst("fpjs-event-signature");
        if (signature == null || signature.isEmpty()) {
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Missing fpjs-event-signature header");
        }

        final boolean isValidSignature = Webhook.isValidWebhookSignature(signature, webhook, secret);
        if (!isValidSignature) {
            return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Webhook signature is not valid");
        }

        return ResponseEntity.ok("Webhook received");
    }
}

Documentation for API Endpoints

All URIs are relative to https://api.fpjs.io

Class	Method	HTTP request	Description
FingerprintApi	deleteVisitorData	DELETE /visitors/{visitor_id}	Delete data by visitor ID
FingerprintApi	getEvent	GET /events/{request_id}	Get event by request ID
FingerprintApi	getVisits	GET /visitors/{visitor_id}	Get visits by visitor ID
FingerprintApi	updateEvent	PUT /events/{request_id}	Update an event with a given request ID
FingerprintApi	webhookTrace	TRACE /webhook

Documentation for Models

• Botd
• BotdBot
• BotdBotResult
• BrowserDetails
• ClonedApp
• DeprecatedGeolocation
• DeveloperTools
• Emulator
• Error
• ErrorCode
• ErrorPlainResponse
• ErrorResponse
• EventsGetResponse
• EventsUpdateRequest
• FactoryReset
• Frida
• Geolocation
• GeolocationCity
• GeolocationContinent
• GeolocationCountry
• GeolocationSubdivision
• HighActivity
• IPBlocklist
• IPBlocklistDetails
• IPInfo
• IPInfoASN
• IPInfoDataCenter
• IPInfoV4
• IPInfoV6
• Identification
• IdentificationConfidence
• IdentificationSeenAt
• Incognito
• Jailbroken
• LocationSpoofing
• PrivacySettings
• ProductBotd
• ProductClonedApp
• ProductDeveloperTools
• ProductEmulator
• ProductFactoryReset
• ProductFrida
• ProductHighActivity
• ProductIPBlocklist
• ProductIPInfo
• ProductIdentification
• ProductIncognito
• ProductJailbroken
• ProductLocationSpoofing
• ProductPrivacySettings
• ProductProxy
• ProductRawDeviceAttributes
• ProductRemoteControl
• ProductRootApps
• ProductSuspectScore
• ProductTampering
• ProductTor
• ProductVPN
• ProductVelocity
• ProductVirtualMachine
• Products
• Proxy
• RawDeviceAttribute
• RawDeviceAttributeError
• RemoteControl
• RootApps
• SuspectScore
• Tampering
• Tor
• VPN
• VPNConfidence
• VPNMethods
• Velocity
• VelocityData
• VelocityIntervals
• VirtualMachine
• Visit
• VisitorsGetResponse
• Webhook
• WebhookClonedApp
• WebhookDeveloperTools
• WebhookEmulator
• WebhookFactoryReset
• WebhookFrida
• WebhookHighActivity
• WebhookIPBlocklist
• WebhookIPInfo
• WebhookJailbroken
• WebhookLocationSpoofing
• WebhookPrivacySettings
• WebhookProxy
• WebhookRemoteControl
• WebhookRootApps
• WebhookSuspectScore
• WebhookTampering
• WebhookTor
• WebhookVPN
• WebhookVelocity
• WebhookVirtualMachine

Documentation for Authorization

Authentication schemes defined for the API:

ApiKeyHeader

• Type: API key
• API key parameter name: Auth-API-Key
• Location: HTTP header

ApiKeyQuery

• Type: API key
• API key parameter name: api_key
• Location: URL query string

Documentation for sealed results

• Sealed
• DecryptionKey

Recommendation

It's recommended to create an instance of ApiClient per thread in a multithreaded environment to avoid any potential issues.

Support

To report problems, ask questions or provide feedback, please use Issues. If you need private support, you can email us at [email protected].

License

This project is licensed under the MIT License.