This page contains the API Reference for the JavaScript agent's get()
function or its equivalent in your frontend library. The function is NOT exported directly from the @fingerprintjs/fingerprintjs-pro NPM package. Instead, it is a method on the agent instance returned by the load()
function.
Call the get()
function to send identification requests to Fingerprint and get the browser's visitor ID.
If you are just getting started with Fingerprint, we recommend reading the following guides first:
If you encountered errors using the JavaScript agent, see the Error handling reference.
get()
options
get()
optionsextendedResult
extendedResult
Required: no
Default:false
Type:boolean
Two types of responses are supported: default and extended. You don't need to pass any parameters to get the default response. Extended result format includes geolocation, incognito mode, and other information. It can be requested by setting the extendedResult
parameter to true
. See more details about the responses, see get()
response.
products
products
Required: no
Default: (depends on the API key)
Type:string[]
Since: v3.7.0
As of JS Agent version 3.9.3, this option has been deprecated and will likely be removed in the next major version.
You can enable or disable Fingerprint products that will handle this request. Using this option does not affect billing in any way.
linkedId
linkedId
Required: no
Default:undefined
Type:string
Constraint: the number of characters must not exceed 256
linkedId
is a way of linking the current analysis event with a custom identifier. This will allow you to filter visit information when using the Server API.
// Making an API call
var orderId = 3936532456
fp.get({ linkedId: orderId })
// linkedId will be saved with this event and will be available to be queried later.
If the information stored in linkedId
is not available on the client when the event happens, it is possible to set it through our Update Event Server API.
To learn more about tag
and linkedId
use cases, see Linking and tagging information.
tag
tag
Required: no
Default:undefined
Type: any simple value or an object (not arrays)
Constraint: the size must not exceed 16KB
tag
is a customer-provided value or an object that is saved with the identification event and returned back to you in a webhook message or Server API response. You can use tag
to associate the visit event with other information you have about the visitor.
You can use any simple value (string, number, boolean) or an object. An object is saved as provided. A simple value (for example 123
) is returned wrapped in an object like this: { "tag": 123 }
.
Examples of using the tag
option:
fp.get({ tag: 123 });
fp.get({ tag: "signup" });
fp.get({ tag: { id: "456", location: { city: "Atlanta", country: "US" }});
What comes back in a webhook or Server API response:
{
"visitorId": "nTxJ28Gt4CegeAwdWELL",
"tag": { "tag": 123 },
// ...
},
{
"visitorId": "nTxJ28Gt4CegeAwdWELL",
"tag": { "tag": "signup" },
// ...
},
{
"visitorId": "nTxJ28Gt4CegeAwdWELL",
"tag": {
"id": "456",
"location": {
"city": "Atlanta",
"country": "US"
}
}
// ...
}
If the information stored in tag
is not available on the client when the event happens, it is possible to set it through our Update Event Server API.
To learn more about tag
and linkedId
use cases, see Linking and tagging information.
timeout
timeout
Required: no
Default:10000
Type:number
Client timeout controls the total time (both client-side and server-side) that any analysis event can run. It doesn't include the time when the page is in the background (not visible) because the browser may suspend the analysis process during that time. By default, it's 10 seconds. You can set the client-side timeout in milliseconds using the timeout
option. Example usage:
// A timeout of 20 seconds
// An example of the client-side timeout handling
try {
const result = await fp.get({ timeout: 20000 })
// ...
} catch (error) {
if (error.message === FingerprintJS.ERROR_CLIENT_TIMEOUT) {
console.log("A timeout of 20 seconds exceeded")
}
}
Note that setting a low timeout (less than 2000ms) could increase identification failures on weaker devices with slower internet connections.
get()
response
get()
responsefp.get()
returns a promise that resolves to an object. The object format depends on the extendedResult
option. The format summary:
await fp.get()
// response:
{
"requestId": "8nbmT18x79m54PQ0GvPq",
"visitorId": "2JGu1Z4d2J4IqiyzO3i4",
"visitorFound": true,
"confidence": { "score": 0.995 }
}
await fp.get({ extendedResult: true })
// response:
{
"requestId": "8nbmT18x79m54PQ0GvPq",
"visitorId": "2JGu1Z4d2J4IqiyzO3i4",
"visitorFound": true,
"confidence": { "score": 0.995 },
"ip": "185.230.125.20",
// ipLocation: This field is deprecated and will not return a result for applications created after January 23rd, 2024.
// See IP Geolocation (https://dev.fingerprint.com/docs/smart-signals-overview#ip-geolocation) for a replacement
// available in our Smart Signals product.
"ipLocation": {
"accuracyRadius": 10,
"latitude": 47.3925,
"longitude": 8.4546,
"postalCode": "8010",
"timezone": "Europe/Zurich",
"city": {
"name": "Zurich"
},
"continent": {
"code": "EU",
"name": "Europe"
},
"country": {
"code": "CH",
"name": "Switzerland"
},
"subdivisions": [
{
"isoCode": "ZH",
"name": "Zurich"
}
]
},
"browserName": "Chrome",
"browserVersion": "75.0.3770",
"os": "Mac OS X",
"osVersion": "10.14.5",
"device": "Other",
"incognito": false,
"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
}
}
When the identification product is disabled, all the fields except requestId
are replaced with default values.
Response fields:
requestId
requestId
Required: yes
Type:string
The request identifier is unique for every request. Use it to request information about a specific identification request from the Server API.
visitorId
visitorId
Required: yes
Type:string
The browser identifier (or device identifier for mobile platforms)
The field will contain an empty string if the visitor can't be identified, for example, a search bot. If the identification product is disabled, a dummy value is used.
visitorFound
visitorFound
Required: yes
Type:boolean
If true
, it means this visitor has already appeared in and identified for your application.
If false
, it means this is the first time the visitor has appeared in your application.
You can use firstSeenAt
to get a precise timestamp of the browser's very first visit to your application. On the other hand, lastSeenAt
represents this browser's most recent visit to your application.
If the identification product is disabled, a dummy value is used.
confidence
confidence
Required: yes
Type:{ score: number, comment?: string }
A number between 0 and 1 that represents the probability of accurate identification. The higher the number, the higher the chance of the visitor identifier being true. To learn more about how Fingerprint calculates this value, see Understanding your confidence score.
sealedResult
sealedResult
Required: no
Type:string
(base64-encoded binary data)
See more details in the Sealed Client Results guide. The field will miss if Sealed Client Results are disabled or unavailable for another reason.
zeroTrust
zeroTrust
Required: no
Type:{ hiddenFields: string[], comment?: string }
See more details in the Zero Trust Mode guide.
incognito
incognito
Only when
extendedResult
istrue
Required: yes
Type: boolean
Whether the visitor is in incognito/private mode.
If the identification product is disabled, a dummy value is used.
browserName
browserName
Only when
extendedResult
istrue
Required: yes
Type:string
Browser name. Examples: 'Safari'
, 'Chrome'
.
If the identification product is disabled, a dummy value is used.
browserVersion
browserVersion
Only when
extendedResult
istrue
Required: yes
Type:string
Browser version. Example: '78.0.3904'
.
If the identification product is disabled, a dummy value is used.
device
device
Only when
extendedResult
istrue
Required: yes
Type:string
Device. For desktop/laptop devices, the value will be "Other". Example: 'Samsung SM-J330F'
.
If the identification product is disabled, a dummy value is used.
ip
ip
Only when
extendedResult
istrue
Required: yes
Type:string
IP address. Only IPv4 addresses are returned.
If the identification product is disabled, a dummy value is used.
ipLocation
ipLocation
Only when
extendedResult
istrue
Required: no
Type:Object
This field is deprecated and will not return a result for applications created after January 23rd, 2024. See IP Geolocation for a replacement available in our Smart Signals product.
Can be empty for anonymous proxies. The value type:
{
accuracyRadius?: number
latitude?: number
longitude?: number
timezone?: string
postalCode?: string
city?: {
name: string
}
subdivisions?: {
isoCode: string
name: string
}[]
country?: {
code: string
name: string
}
continent?: {
code: string
name: string
}
}
If the identification product is disabled, the value is absent.
os
os
Only when
extendedResult
istrue
Required: yes
Type:string
Operating system name. Examples: 'Mac OS X'
, 'Android'
.
If the identification product is disabled, a dummy value is used.
osVersion
osVersion
Only when
extendedResult
istrue
Required: yes
Type:string
Operating system version. Examples: '10.13.6'
.
firstSeenAt
firstSeenAt
Only when
extendedResult
istrue
Required: yes
Type:{ subscription: string | null, global: string | null }
The very first time a browser appeared in your application. See Visitor Footprint Timestamps for more information.
If the identification product is disabled, a dummy value is used.
lastSeenAt
lastSeenAt
Only when
extendedResult
istrue
Required: yes
Type:{ subscription: string | null, global: string | null }
The most recent instance (i.e. before this request) the browser visited your application. See Visitor Footprint Timestamps for more information.
If the identification product is disabled, a dummy value is used.