@fingerprintjs/fingerprintjs-pro-server-api
Advanced tools
Node.js wrapper for FingerprintJS Sever API
Fingerprint is a device intelligence platform offering 99.5% accurate visitor identification.
The Fingerprint Server Node SDK is an easy way to interact with the Fingerprint Server API from your Node application. You can retrieve visitor history or individual identification events.
TypeScript support:
Supported runtimes:
Node.js 18 LTS or higher (we support all Node LTS releases before end-of-life).
Deno and Bun might work but are not actively tested.
"Edge" runtimes might work with some modifications but are not actively tested.
This SDK can be made compatible with JavaScript "edge" runtimes that do not support all Node APIs, for example, Vercel Edge Runtime, or Cloudflare Workers.
To make it work, replace the SDK's built-in fetch function (which relies on Node APIs) with the runtime's native fetch function. Pass the function into the constructor with proper binding:
const client = new FingerprintJsServerApiClient({
region: Region.EU,
apiKey: apiKey,
fetch: fetch.bind(globalThis),
});
Install the package using your favorite package manager:
NPM:
npm i @fingerprintjs/fingerprintjs-pro-server-api
Yarn:
yarn add @fingerprintjs/fingerprintjs-pro-server-api
pnpm:
pnpm i @fingerprintjs/fingerprintjs-pro-server-api
Initialize the client instance and use it to make API requests. You need to specify your Fingerprint Secret API key and the region of your Fingerprint application.
import { FingerprintJsServerApiClient, Region } from '@fingerprintjs/fingerprintjs-pro-server-api';
const client = new FingerprintJsServerApiClient({
apiKey: '<SECRET_API_KEY>',
region: Region.Global,
});
// Get visit history of a specific visitor
client.getVisitorHistory('<visitorId>').then((visitorHistory) => {
console.log(visitorHistory);
});
// Get a specific identification event
client.getEvent('<requestId>').then((event) => {
console.log(event);
});
When handling Webhooks coming from Fingerprint, you can cast the payload as the built-in VisitWebhook type:
const visit = visitWebhookBody as unknown as VisitWebhook;
The getEvent and getVisitorHistory methods can throw EventError and VisitorsError.
You can use the provided isVisitorsError and isEventError type guards to narrow down error types:
import { isVisitorsError, isEventError } from '@fingerprintjs/fingerprintjs-pro-server-api';
client
.getVisitorHistory('<visitorId>', filter)
.then((result) => console.log(result))
.catch((err) => {
if (isVisitorsError(err)) {
if (err.code === 429) {
// VisitorsError429 type
retryLater(err.retryAfter); // this function needs to be implemented on your side
} else {
console.log('error: ', err.error);
}
} else {
console.log('unknown error: ', err);
}
});
client
.getEvent('<requestId>')
.then((result) => console.log(result))
.catch((err) => {
if (isEventError(err)) {
console.log(`error ${err.code}: `, err.error.message);
} else {
console.log('unknown error: ', err);
}
});
constructor({region: Region, apiKey: string})Creates an instance of the client.
const client = new FingerprintJsServerApiClient({ region: Region.EU, apiKey: '<api_key>' });
region: Region - a region of the server, possible values: Region.EU, Region.AP, or Region.GlobalapiKey: string - secret API key from the FingerprintJS dashboardfetch?: typeof fetch - optional implementation of fetch function (defaults to node-fetch)getEvent(requestId: string): Promise<EventResponse>Retrieves a specific identification event with the information from each activated product — Identification and all active Smart signals.
client
.getEvent('<requestId>')
.then((eventInfo) => {
console.log(eventInfo);
})
.catch((error) => {
if (error.status === 403 || error.status === 404) {
console.log(error.code, error.message);
}
});
requestId: string - identifier of the eventPromise<EventResponse> - promise with event responseEventResponseFor more information, see the Server API documentation.
{
"products": {
"identification": {
"data": {
"visitorId": "Ibk1527CUFmcnjLwIs4A9",
"requestId": "0KSh65EnVoB85JBmloQK",
"incognito": true,
"linkedId": "somelinkedId",
"time": "2019-05-21T16:40:13Z",
"timestamp": 1582299576512,
"url": "https://www.example.com/login",
"ip": "61.127.217.15",
"ipLocation": {
"accuracyRadius": 10,
"latitude": 49.982,
"longitude": 36.2566,
"postalCode": "61202",
"timezone": "Europe/Dusseldorf",
"city": {
"name": "Dusseldorf"
},
"continent": {
"code": "EU",
"name": "Europe"
},
"country": {
"code": "DE",
"name": "Germany"
},
"subdivisions": [
{
"isoCode": "63",
"name": "North Rhine-Westphalia"
}
]
},
"browserDetails": {
"browserName": "Chrome",
"browserMajorVersion": "74",
"browserFullVersion": "74.0.3729",
"os": "Windows",
"osVersion": "7",
"device": "Other",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...."
},
"confidence": {
"score": 0.97
},
"visitorFound": true,
"firstSeenAt": {
"global": "2022-03-16T11:26:45.362Z",
"subscription": "2022-03-16T11:31:01.101Z"
},
"lastSeenAt": {
"global": "2022-03-16T11:28:34.023Z",
"subscription": null
}
}
},
"botd": {
"data": {
"bot": {
"result": "notDetected"
},
"url": "https://example.com/login",
"ip": "61.127.217.15",
"time": "2019-05-21T16:40:13Z"
}
}
}
}
getVisitorHistory(visitorId: string, filter?: VisitorHistoryFilter): Promise<VisitorsResponse>Retrieves event history for the specific visitor using the given filter, returns a promise with visitor history response.
client
.getVisitorHistory('<visitorId>', filter)
.then((visitorHistory) => {
console.log(visitorHistory);
})
.catch((error) => {
if (error.status === 403) {
console.log(error.error);
} else if (error.status === 429) {
retryLater(error.retryAfter); // this function needs to be implemented on your side
}
});
visitorId: string - identifier of the visitorfilter?: VisitorHistoryFilter - visitor history filter (details below)VisitorHistoryFilterFilter for querying the visitors Server API endpoint.
Usage:
const filter = {
request_id: '<request_id>',
linked_id: '<linked_id>',
limit: 5,
paginationKey: '<paginationKey>',
};
Properties:
request_id: string - filter visits by requestId.
Every identification request has a unique identifier associated with it called requestId. This identifier is returned to the client in the identification result. When you filter visits by requestId, only one visit will be returned.
linked_id: string - filter visits by your custom identifier.
You can use linkedId to associate identification requests with your own identifier, for example: session ID, purchase ID, or transaction ID. You can then use this linked_id parameter to retrieve all events associated with your custom identifier.
limit: number - limit scanned results.
For performance reasons, the API first scans some number of events before filtering them. Use limit to specify how many events are scanned before they are filtered by requestId or linkedId. Results are always returned sorted by the timestamp (most recent first). By default, the most recent 100 visits are scanned, the maximum is 500.
paginationKey: string - use paginationKey to get the next page of results.
When more results are available (e.g., you requested 200 results using limit parameter, but a total of 600 results are available), the paginationKey top-level attribute is added to the response. The key corresponds to the requestId of the last returned event. In the following request, use that value in the paginationKey parameter to get the next page of results:
GET api-base-url/visitors/:visitorId?limit=200response.paginationKey to get the next page of results: GET api-base-url/visitors/:visitorId?limit=200&paginationKey=1683900801733.Ogvu1jPagination happens during scanning and before filtering, so you can get less visits than the limit you specified with more available on the next page. When there are no more results available for scanning, the paginationKey attribute is not returned.
Promise<VisitorsResponse> - promise with the visitor history responseVisitorsResponseFor more information, see the Server API documentation.
{
"visitorId": "Ibk1527CUFmcnjLwIs4A9",
"visits": [
{
"requestId": "0KSh65EnVoB85JBmloQK",
"incognito": true,
"linkedId": "somelinkedId",
"time": "2019-05-21T16:40:13Z",
// timestamp of the event with millisecond precision
"timestamp": 1582299576512,
"url": "https://www.example.com/login",
"ip": "61.127.217.15",
"ipLocation": {
"accuracyRadius": 10,
"latitude": 49.982,
"longitude": 36.2566,
"postalCode": "61202",
"timezone": "Europe/Dusseldorf",
"city": {
"name": "Dusseldorf"
},
"continent": {
"code": "EU",
"name": "Europe"
},
"country": {
"code": "DE",
"name": "Germany"
},
"subdivisions": [
{
"isoCode": "63",
"name": "North Rhine-Westphalia"
}
]
},
"browserDetails": {
"browserName": "Chrome",
"browserMajorVersion": "74",
"browserFullVersion": "74.0.3729",
"os": "Windows",
"osVersion": "7",
"device": "Other",
"userAgent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) ...."
},
"confidence": {
"score": 0.97
},
"visitorFound": true,
"firstSeenAt": {
"global": "2022-03-16T11:26:45.362Z",
"subscription": "2022-03-16T11:31:01.101Z"
},
"lastSeenAt": {
"global": "2022-03-16T11:28:34.023Z",
"subscription": null
}
}
],
// optional, if more results are available for pagination.
"lastTimestamp": 1582299576512
}
To report problems, ask questions or provide feedback, please use Issues. If you need private support, you can email us at oss-support@fingerprint.com.
This project is licensed under the MIT license.
FAQs
Node.js wrapper for FingerprintJS Sever API
The npm package @fingerprintjs/fingerprintjs-pro-server-api receives a total of 4,194 weekly downloads. As such, @fingerprintjs/fingerprintjs-pro-server-api popularity was classified as popular.
We found that @fingerprintjs/fingerprintjs-pro-server-api demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Company News
Socket is joining TC54 to help develop standards for software supply chain security, contributing to the evolution of SBOMs, CycloneDX, and Package URL specifications.
Security News
PyPI now allows maintainers to archive projects, improving security and helping users make informed decisions about their dependencies.
Research
Security News
Malicious npm package postcss-optimizer delivers BeaverTail malware, targeting developer systems; similarities to past campaigns suggest a North Korean connection.