fingerprintjs/fingerprint-pro-server-api-java-sdk
GitHub: fingerprintjs/fingerprint-pro-server-api-java-sdk
Fingerprint Pro Server API 的官方 Java SDK，帮助 Java 应用在服务端获取和管理设备智能与访客识别数据。
Stars: 17 | Forks: 8
# Fingerprint Server API Java SDK
[Fingerprint](https://fingerprint.com/) 是一个提供行业领先准确性的设备智能平台。Fingerprint Server Java SDK 是一种从您的 Java 应用程序与 Fingerprint [Server API](https://dev.fingerprint.com/reference/pro-server-api) 进行交互的简便方法。您可以搜索、更新和删除识别事件。
*由 [OpenAPI Generator](https://openapi-generator.tech) 自动生成*
## 要求
支持以下 Gradle/Maven 版本
- Maven (3.8.3+)
- Gradle (7.2+)
支持以下 Java 版本
- Java 11
- Java 17
- Java 21
## 安装说明
### Maven 用户
将此依赖项添加到您项目的 POM 中：
```
jitpack.io
https://jitpack.io
```
```
com.github.fingerprintjs
fingerprint-pro-server-api-java-sdk
v7.12.0
```
### Gradle 用户
将此依赖项添加到您项目的构建文件（`build.gradle` 或 `build.gradle.kts`）中：
```
// build.gradle
repositories {
maven { url 'https://jitpack.io' }
}
dependencies {
implementation "com.github.fingerprintjs:fingerprint-pro-server-api-java-sdk:v7.12.0"
}
```
```
// build.gradle.kts
repositories {
maven {
url = uri("https://jitpack.io")
}
}
dependencies {
implementation("com.github.fingerprintjs:fingerprint-pro-server-api-java-sdk:v7.12.0")
}
```
### 其他
首先通过执行以下命令生成 JAR：
```
./gradlew jar
```
然后手动安装以下 JAR 包：
- `target/fingerprint-pro-server-api-sdk-7.12.0.jar`
## 入门指南
请按照[安装说明](#installation)并执行以下 Java 代码：
```
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 Secret API Key
private static final String FPJS_API_SECRET = "Fingerprint 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 Server API Key and your Fingerprint 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());
}
// Search events with custom filters
try {
// By visitorId
SearchEventsResponse response = api.searchEvents(LIMIT, new FingerprintApi.SearchEventsOptionalParams().setVisitorId(FPJS_VISITOR_ID));
// Next page
// SearchEventsResponse response = api.searchEvents(LIMIT, new FingerprintApi.SearchEventsOptionalParams().setPaginationKey(response.getPaginationKey()).setVisitorId(FPJS_VISITOR_ID));
// Bad bot
// SearchEventsResponse response = api.searchEvents(LIMIT, new FingerprintApi.SearchEventsOptionalParams().setBot("bad"));
// Filtered by IP
// SearchEventsResponse response = api.searchEvents(LIMIT, new FingerprintApi.SearchEventsOptionalParams().setIpAddress("192.168.0.1/32"));
System.out.println(response.getEvents().toString());
} catch (ApiException e) {
System.err.println("Exception when calling FingerprintApi.searchEvents:" + 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());
}
}
}
```
## 密封结果
此 SDK 提供了用于解码[密封结果](https://dev.fingerprint.com/docs/sealed-client-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.
}
}
```
了解更多信息，请参阅[密封结果示例](/examples/src/main/java/com/fingerprint/example/SealedResults.java)。
## Webhook 签名验证
此 SDK 提供了用于验证传入 webhook 请求的 HMAC 签名的实用方法。
以下是使用 Spring Boot 的示例实现：
```
import com.fingerprint.sdk.WebhookValidation;
@RestController
class WebhookController {
@PostMapping("/api/webhook")
public ResponseEntity
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 = WebhookValidation.isSignatureValid(signature, webhook, secret);
if (!isValidSignature) {
return ResponseEntity.status(HttpStatus.BAD_REQUEST).body("Webhook signature is not valid");
}
return ResponseEntity.ok("Webhook received");
}
}
```
## API 端点文档
所有 URI 的基础路径为 *https://api.fpjs.io*
Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
*FingerprintApi* | [**deleteVisitorData**](docs/FingerprintApi.md#deleteVisitorData) | **DELETE** /visitors/{visitor_id} | 按 visitor ID 删除数据
*FingerprintApi* | [**getEvent**](docs/FingerprintApi.md#getEvent) | **GET** /events/{request_id} | 按 request ID 获取事件
*FingerprintApi* | [**getRelatedVisitors**](docs/FingerprintApi.md#getRelatedVisitors) | **GET** /related-visitors | 获取相关访客
*FingerprintApi* | [**getVisits**](docs/FingerprintApi.md#getVisits) | **GET** /visitors/{visitor_id} | 按 visitor ID 获取访问记录
*FingerprintApi* | [**searchEvents**](docs/FingerprintApi.md#searchEvents) | **GET** /events/search | 通过搜索获取事件
*FingerprintApi* | [**updateEvent**](docs/FingerprintApi.md#updateEvent) | **PUT** /events/{request_id} | 使用指定的 request ID 更新事件
*FingerprintApi* | [**webhookTrace**](docs/FingerprintApi.md#webhookTrace) | **TRACE** /webhook | 用于描述 webhook 格式的虚拟路径。
## 模型文档
- [Botd](docs/Botd.md)
- [BotdBot](docs/BotdBot.md)
- [BotdBotResult](docs/BotdBotResult.md)
- [BrowserDetails](docs/BrowserDetails.md)
- [ClonedApp](docs/ClonedApp.md)
- [DeprecatedGeolocation](docs/DeprecatedGeolocation.md)
- [DeveloperTools](docs/DeveloperTools.md)
- [Emulator](docs/Emulator.md)
- [Error](docs/Error.md)
- [ErrorCode](docs/ErrorCode.md)
- [ErrorPlainResponse](docs/ErrorPlainResponse.md)
- [ErrorResponse](docs/ErrorResponse.md)
- [EventsGetResponse](docs/EventsGetResponse.md)
- [EventsUpdateRequest](docs/EventsUpdateRequest.md)
- [FactoryReset](docs/FactoryReset.md)
- [Frida](docs/Frida.md)
- [Geolocation](docs/Geolocation.md)
- [GeolocationCity](docs/GeolocationCity.md)
- [GeolocationContinent](docs/GeolocationContinent.md)
- [GeolocationCountry](docs/GeolocationCountry.md)
- [GeolocationSubdivision](docs/GeolocationSubdivision.md)
- [HighActivity](docs/HighActivity.md)
- [IPBlocklist](docs/IPBlocklist.md)
- [IPBlocklistDetails](docs/IPBlocklistDetails.md)
- [IPInfo](docs/IPInfo.md)
- [IPInfoASN](docs/IPInfoASN.md)
- [IPInfoDataCenter](docs/IPInfoDataCenter.md)
- [IPInfoV4](docs/IPInfoV4.md)
- [IPInfoV6](docs/IPInfoV6.md)
- [Identification](docs/Identification.md)
- [IdentificationConfidence](docs/IdentificationConfidence.md)
- [IdentificationSeenAt](docs/IdentificationSeenAt.md)
- [Incognito](docs/Incognito.md)
- [Integration](docs/Integration.md)
- [IntegrationSubintegration](docs/IntegrationSubintegration.md)
- [Jailbroken](docs/Jailbroken.md)
- [LocationSpoofing](docs/LocationSpoofing.md)
- [MitMAttack](docs/MitMAttack.md)
- [PrivacySettings](docs/PrivacySettings.md)
- [ProductBotd](docs/ProductBotd.md)
- [ProductClonedApp](docs/ProductClonedApp.md)
- [ProductDeveloperTools](docs/ProductDeveloperTools.md)
- [ProductEmulator](docs/ProductEmulator.md)
- [ProductFactoryReset](docs/ProductFactoryReset.md)
- [ProductFrida](docs/ProductFrida.md)
- [ProductHighActivity](docs/ProductHighActivity.md)
- [ProductIPBlocklist](docs/ProductIPBlocklist.md)
- [ProductIPInfo](docs/ProductIPInfo.md)
- [ProductIdentification](docs/ProductIdentification.md)
- [ProductIncognito](docs/ProductIncognito.md)
- [ProductJailbroken](docs/ProductJailbroken.md)
- [ProductLocationSpoofing](docs/ProductLocationSpoofing.md)
- [ProductMitMAttack](docs/ProductMitMAttack.md)
- [ProductPrivacySettings](docs/ProductPrivacySettings.md)
- [ProductProximity](docs/ProductProximity.md)
- [ProductProxy](docs/ProductProxy.md)
- [ProductRawDeviceAttributes](docs/ProductRawDeviceAttributes.md)
- [ProductRemoteControl](docs/ProductRemoteControl.md)
- [ProductRootApps](docs/ProductRootApps.md)
- [ProductSuspectScore](docs/ProductSuspectScore.md)
- [ProductTampering](docs/ProductTampering.md)
- [ProductTor](docs/ProductTor.md)
- [ProductVPN](docs/ProductVPN.md)
- [ProductVelocity](docs/ProductVelocity.md)
- [ProductVirtualMachine](docs/ProductVirtualMachine.md)
- [Products](docs/Products.md)
- [Proximity](docs/Proximity.md)
- [Proxy](docs/Proxy.md)
- [ProxyConfidence](docs/ProxyConfidence.md)
- [ProxyDetails](docs/ProxyDetails.md)
- [RawDeviceAttribute](docs/RawDeviceAttribute.md)
- [RawDeviceAttributeError](docs/RawDeviceAttributeError.md)
- [RelatedVisitor](docs/RelatedVisitor.md)
- [RelatedVisitorsResponse](docs/RelatedVisitorsResponse.md)
- [RemoteControl](docs/RemoteControl.md)
- [RootApps](docs/RootApps.md)
- [SDK](docs/SDK.md)
- [SearchEventsResponse](docs/SearchEventsResponse.md)
- [SearchEventsResponseEventsInner](docs/SearchEventsResponseEventsInner.md)
- [SupplementaryID](docs/SupplementaryID.md)
- [SuspectScore](docs/SuspectScore.md)
- [Tampering](docs/Tampering.md)
- [Tor](docs/Tor.md)
- [VPN](docs/VPN.md)
- [VPNConfidence](docs/VPNConfidence.md)
- [VPNMethods](docs/VPNMethods.md)
- [Velocity](docs/Velocity.md)
- [VelocityData](docs/VelocityData.md)
- [VelocityIntervals](docs/VelocityIntervals.md)
- [VirtualMachine](docs/VirtualMachine.md)
- [Visit](docs/Visit.md)
- [VisitorsGetResponse](docs/VisitorsGetResponse.md)
- [Webhook](docs/Webhook.md)
- [WebhookClonedApp](docs/WebhookClonedApp.md)
- [WebhookDeveloperTools](docs/WebhookDeveloperTools.md)
- [WebhookEmulator](docs/WebhookEmulator.md)
- [WebhookFactoryReset](docs/WebhookFactoryReset.md)
- [WebhookFrida](docs/WebhookFrida.md)
- [WebhookHighActivity](docs/WebhookHighActivity.md)
- [WebhookIPBlocklist](docs/WebhookIPBlocklist.md)
- [WebhookIPInfo](docs/WebhookIPInfo.md)
- [WebhookJailbroken](docs/WebhookJailbroken.md)
- [WebhookLocationSpoofing](docs/WebhookLocationSpoofing.md)
- [WebhookMitMAttack](docs/WebhookMitMAttack.md)
- [WebhookPrivacySettings](docs/WebhookPrivacySettings.md)
- [WebhookProximity](docs/WebhookProximity.md)
- [WebhookProxy](docs/WebhookProxy.md)
- [WebhookRemoteControl](docs/WebhookRemoteControl.md)
- [WebhookRootApps](docs/WebhookRootApps.md)
- [WebhookSupplementaryIDs](docs/WebhookSupplementaryIDs.md)
- [WebhookSuspectScore](docs/WebhookSuspectScore.md)
- [WebhookTampering](docs/WebhookTampering.md)
- [WebhookTor](docs/WebhookTor.md)
- [WebhookVPN](docs/WebhookVPN.md)
- [WebhookVelocity](docs/WebhookVelocity.md)
- [WebhookVirtualMachine](docs/WebhookVirtualMachine.md)
## 鉴权文档
为 API 定义的认证方案：
### ApiKeyHeader
- **类型**：API key
- **API key 参数名称**：Auth-API-Key
- **位置**：HTTP header
### ApiKeyQuery
- **类型**：API key
- **API key 参数名称**：api_key
- **位置**：URL query string
## 密封结果文档
- [Sealed](docs/Sealed.md)
- [DecryptionKey](docs/DecryptionKey.md)
## 建议
建议在多线程环境中为每个线程创建一个 `ApiClient` 实例，以避免任何潜在问题。
## 支持
要报告问题、提问或提供反馈，请使用 [Issues](https://github.com/fingerprintjs/fingerprint-pro-server-api-java-sdk/issues)。
如果您需要私密支持，可以发送电子邮件至 [oss-support@fingerprint.com](mailto:oss-support@fingerprint.com)。
## 许可证
本项目基于 [MIT 许可证](https://github.com/fingerprintjs/fingerprint-pro-server-api-java-sdk/blob/main/LICENSE) 授权。标签：API集成, FingerprintJS, Fingerprint Pro, Java SDK, Java开发, JitPack, JS文件枚举, MIT开源, SDK封装, 反机器人, 反欺诈, 可观测性, 后台面板检测, 域名枚举, 服务端API, 浏览器指纹, 用户识别, 网络安全, 设备指纹, 设备智能, 访客识别, 隐私保护