fingerprintjs/dotnet-sdk
GitHub: fingerprintjs/dotnet-sdk
Fingerprint Pro 服务端 API 的官方 C#/.NET SDK，用于在 .NET 后端程序中安全高效地访问设备智能识别数据并管理识别事件。
Stars: 19 | Forks: 7
# Fingerprint Server API Dotnet SDK
[Fingerprint](https://fingerprint.com) 是一个提供业界领先准确性的设备智能平台。
Fingerprint Server API 允许您在服务器环境中搜索、更新和删除识别事件。它可以用于数据导出、决策和数据分析场景。Server API 专供服务器端使用，不适用于客户端（无论是浏览器还是移动设备）。
此 C# SDK 由 [OpenAPI Generator](https://openapi-generator.tech) 项目自动生成：
- API 版本：4
- SDK 版本：8.2.0
- 构建包：org.openapitools.codegen.languages.CSharpClientCodegen
## 要求
- .NET 8.0 或更高版本（我们遵循 [Microsoft 支持策略](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core)）
## 安装方法
我们推荐从 [NuGet](https://docs.nuget.org/consume/installing-nuget) 安装该包：
```
dotnet add package Fingerprint.ServerSdk
```
## 入门指南
```
// Example usage of our SDK
// Import namespaces
using Microsoft.Extensions.Hosting;
using Microsoft.Extensions.DependencyInjection;
using Fingerprint.ServerSdk.Api;
using Fingerprint.ServerSdk.Client;
using Fingerprint.ServerSdk.Model;
namespace YourProject
{
public class Program
{
public static async Task Main(string[] args)
{
var host = CreateHostBuilder(args).Build();
var api = host.Services.GetRequiredService
();
var response = await api.SearchEventsAsync(limit: 2);
if (response.TryOk(out EventSearch events))
{
// Process events...
}
// You can also access the raw content and headers:
// string rawContent = response.RawContent;
// HttpResponseHeaders headers = response.Headers;
}
public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args)
.ConfigureFingerprint((context, services, options) =>
{
BearerToken token = new(Environment.GetEnvironmentVariable("SECRET_API_KEY")!);
options.AddTokens(token);
// optionally choose the method the tokens will be provided with, default is RateLimitProvider
options.UseProvider, BearerToken>();
options.ConfigureJsonOptions((jsonOptions) =>
{
// your custom converters if any
});
options.AddApiHttpClients(client =>
{
// custom client configuration
}, builder =>
{
builder
.AddRetryPolicy(2)
.AddTimeoutPolicy(TimeSpan.FromSeconds(5))
.AddCircuitBreakerPolicy(10, TimeSpan.FromSeconds(30));
// add whatever middleware you prefer
}
);
});
}
}
```
您可以在 [src/Fingerprint.ServerSdk.Examples/Program.cs](src/Fingerprint.ServerSdk.Examples/Program.cs) 中查看更多示例。
### 处理响应
SDK 提供了类型安全的响应处理，包含 `IsXxx` 属性和提取方法：
```
var response = await api.GetEventAsync("event_id");
// Check response status
if (response.IsOk)
{
// Extract successful response
Event ev = response.Ok();
Console.WriteLine($"Visitor ID: {event.Identification.VisitorId}");
}
else if (response.IsNotFound)
{
// Extract error response
ErrorResponse error = response.NotFound();
Console.WriteLine($"Error: {error.Error.Message}");
}
else if (response.IsBadRequest)
{
ErrorResponse error = response.BadRequest();
Console.WriteLine($"Bad request: {error.Error.Message}");
}
else if (response.IsForbidden)
{
ErrorResponse error = response.Forbidden();
Console.WriteLine($"Forbidden: {error.Error.Message}");
}
else if (response.IsTooManyRequests)
{
ErrorResponse error = response.TooManyRequests();
Console.WriteLine($"Rate limited. Retry after: {response.Headers.RetryAfter}");
}
```
您还可以使用 `TryXxx` 方法进行安全提取：
```
if (response.TryOk(out Event ev))
{
Console.WriteLine($"Visitor ID: {ev.Identification.VisitorId}");
}
else if (response.TryNotFound(out ErrorResponse error))
{
Console.WriteLine($"Not found: {error.Error.Message}");
}
```
### 区域
如果您的订阅区域不是美国，您需要在构建 host 时更改区域：
```
public static IHostBuilder CreateHostBuilder(string[] args) => Host.CreateDefaultBuilder(args)
.ConfigureFingerprint((context, services, options) =>
{
// ...
options.Region = Region.EU;
});
```
## 密封结果
此 SDK 提供了用于解码[密封结果](https://dev.fingerprint.com/docs/sealed-client-results)的实用方法。
```
using Fingerprint.ServerSdk;
var sealedResult = Environment.GetEnvironmentVariable("BASE64_SEALED_RESULT")!;
var sealedKey = Environment.GetEnvironmentVariable("BASE64_KEY")!;
var event = Sealed.UnsealEventResponse(Convert.FromBase64String(sealedResult), new[]
{
new Sealed.DecryptionKey(Convert.FromBase64String(sealedKey), Sealed.DecryptionAlgorithm.Aes256Gcm)
});
```
了解更多信息，请参考位于 [src/Fingerprint.ServerSdk.SealedResultExample/Program.cs](src/Fingerprint.ServerSdk.SealedResultExample/Program.cs) 的示例。
## Webhook 签名验证
此 SDK 提供了用于验证传入 webhook 请求 HMAC 签名的实用方法。
```
namespace FingerprintAspNetCore.Areas.Identity.Pages;
using Fingerprint.ServerSdk;
using Microsoft.AspNetCore.Mvc;
using System;
using System.IO;
using System.Threading.Tasks;
[Route("api/[controller]")]
[ApiController]
public class WebhookController : ControllerBase
{
[HttpPost]
public async Task Post()
{
try
{
var secret = Environment.GetEnvironmentVariable("WEBHOOK_SIGNATURE_SECRET");
if (string.IsNullOrEmpty(secret))
{
return BadRequest(new { message = "Secret key is not configured." });
}
var header = Request.Headers["fpjs-event-signature"].ToString();
if (string.IsNullOrEmpty(header))
{
return BadRequest(new { message = "Missing fpjs-event-signature header." });
}
using var memoryStream = new MemoryStream();
await Request.Body.CopyToAsync(memoryStream);
var data = memoryStream.ToArray();
// Validate webhook signature
var isValid = WebhookValidation.IsValidSignature(
header,
data,
secret);
if (!isValid)
{
return Forbid(new { message = "Webhook signature is invalid." });
}
// Process the webhook data here
return Ok(new { message = "Webhook received." });
}
catch (Exception e)
{
return StatusCode(500, new { error = e.Message });
}
}
}
```
了解更多信息，请参考位于 [src/Fingerprint.ServerSdk.WebhookExample/Program.cs](src/Fingerprint.ServerSdk.WebhookExample/Program.cs) 的示例。
## API 端点文档
所有 URI 均基于 *https://api.fpjs.io/v4*
Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
*FingerprintApi* | [**DeleteVisitorDataAsync**](docs/FingerprintApi.md#deletevisitordata) | **DELETE** /visitors/{visitor_id} | 根据 visitor ID 删除数据
*FingerprintApi* | [**GetEventAsync**](docs/FingerprintApi.md#getevent) | **GET** /events/{event_id} | 根据 event ID 获取事件
*FingerprintApi* | [**SearchEventsAsync**](docs/FingerprintApi.md#searchevents) | **GET** /events | 搜索事件
*FingerprintApi* | [**UpdateEventAsync**](docs/FingerprintApi.md#updateevent) | **PATCH** /events/{event_id} | 更新事件
## 模型文档
- [Model.BotInfo](docs/models/BotInfo.md)
- [Model.BotResult](docs/models/BotResult.md)
- [Model.BrowserDetails](docs/models/BrowserDetails.md)
- [Model.Canvas](docs/models/Canvas.md)
- [Model.Emoji](docs/models/Emoji.md)
- [Model.Error](docs/models/Error.md)
- [Model.ErrorCode](docs/models/ErrorCode.md)
- [Model.ErrorResponse](docs/models/ErrorResponse.md)
- [Model.Event](docs/models/Event.md)
- [Model.EventRuleAction](docs/models/EventRuleAction.md)
- [Model.EventRuleActionAllow](docs/models/EventRuleActionAllow.md)
- [Model.EventRuleActionBlock](docs/models/EventRuleActionBlock.md)
- [Model.EventSearch](docs/models/EventSearch.md)
- [Model.EventUpdate](docs/models/EventUpdate.md)
- [Model.FontPreferences](docs/models/FontPreferences.md)
- [Model.Geolocation](docs/models/Geolocation.md)
- [Model.GeolocationSubdivisionsInner](docs/models/GeolocationSubdivisionsInner.md)
- [Model.IPBlockList](docs/models/IPBlockList.md)
- [Model.IPInfo](docs/models/IPInfo.md)
- [Model.IPInfoV4](docs/models/IPInfoV4.md)
- [Model.IPInfoV6](docs/models/IPInfoV6.md)
- [Model.Identification](docs/models/Identification.md)
- [Model.IdentificationConfidence](docs/models/IdentificationConfidence.md)
- [Model.IncrementalIdentificationStatus](docs/models/IncrementalIdentificationStatus.md)
- [Model.Integration](docs/models/Integration.md)
- [Model.IntegrationSubintegration](docs/models/IntegrationSubintegration.md)
- [Model.PluginsInner](docs/models/PluginsInner.md)
- [Model.PluginsInnerMimeTypesInner](docs/models/PluginsInnerMimeTypesInner.md)
- [Model.Proximity](docs/models/Proximity.md)
- [Model.ProxyConfidence](docs/models/ProxyConfidence.md)
- [Model.ProxyDetails](docs/models/ProxyDetails.md)
- [Model.RareDevicePercentileBucket](docs/models/RareDevicePercentileBucket.md)
- [Model.RawDeviceAttributes](docs/models/RawDeviceAttributes.md)
- [Model.RequestHeaderModifications](docs/models/RequestHeaderModifications.md)
- [Model.RuleActionHeaderField](docs/models/RuleActionHeaderField.md)
- [Model.RuleActionType](docs/models/RuleActionType.md)
- [Model.SDK](docs/models/SDK.md)
- [Model.SearchEventsBot](docs/models/SearchEventsBot.md)
- [Model.SearchEventsIncrementalIdentificationStatus](docs/models/SearchEventsIncrementalIdentificationStatus.md)
- [Model.SearchEventsRareDevicePercentileBucket](docs/models/SearchEventsRareDevicePercentileBucket.md)
- [Model.SearchEventsSdkPlatform](docs/models/SearchEventsSdkPlatform.md)
- [Model.SearchEventsVpnConfidence](docs/models/SearchEventsVpnConfidence.md)
- [Model.SupplementaryIDHighRecall](docs/models/SupplementaryIDHighRecall.md)
- [Model.TamperingConfidence](docs/models/TamperingConfidence.md)
- [Model.TamperingDetails](docs/models/TamperingDetails.md)
- [Model.TouchSupport](docs/models/TouchSupport.md)
- [Model.Velocity](docs/models/Velocity.md)
- [Model.VelocityData](docs/models/VelocityData.md)
- [Model.VpnConfidence](docs/models/VpnConfidence.md)
- [Model.VpnMethods](docs/models/VpnMethods.md)
- [Model.WebGlBasics](docs/models/WebGlBasics.md)
- [Model.WebGlExtensions](docs/models/WebGlExtensions.md)
## 密封结果文档
- [Sealed](docs/models/Sealed.md)
- [DecryptionKey](docs/models/DecryptionKey.md)
## Webhook 文档
- [WebhookValidation](docs/models/WebhookValidation.md)
## 支持与反馈
要报告问题、提问或提供反馈，请使用 [Issues](https://github.com/fingerprintjs/dotnet-sdk/issues)。如果您需要私人支持，可以通过 [oss-support@fingerprint.com](mailto:oss-support@fingerprint.com) 给我们发送电子邮件。
## 许可证
本项目基于 [MIT 许可证](https://github.com/fingerprintjs/dotnet-sdk/blob/main/LICENSE) 授权。标签：API集成, C2日志可视化, Fingerprint, FingerprintJS, OpenAPI, 反欺诈, 可观测性, 开源库, 指纹识别, 搜索引擎爬虫, 服务端API, 浏览器指纹, 爬虫检测, 用户追踪, 设备指纹, 设备智能, 访问者识别
