API reference for the JavaScript agent's load()
function
This page contains the API Reference for the JavaScript agent's load()
function or its equivalent in your frontend library. The function is exported from the @fingerprintjs/fingerprintjs-pro NPM package.
Call the load()
function to initialize the JavaScript agent for your Fingerprint application.
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.
load()
options
load()
optionsTo configure the agent, pass parameters into the load()
function or its equivalent in your frontend library.
apiKey
apiKey
Required: yes for NPM installation
Type:string
Your public API key to authenticate the agent. You can get one at dashboard.fingerprint.com. If you log into this documentation portal through the dashboard, you will be able to see your personal API key in the example below.
Example usage:
const fpPromise = FingerprintJS.load({ apiKey: "<<browserToken>>" })
The parameter is required for the NPM installation method and optional for the CDN (where the key is a part of the URL).
region
region
Required: no
Default:"us"
Type:string
Available values:"us"
,"eu"
and"ap"
Use this parameter to specify the region you picked for your application during registration (defaults to us
).
The Fingerprint Platform CDN can usually determine the region automatically using your API Key. Nevertheless, we recommend you specify it explicitly. Our proxy integrations rely on the region
parameter, as they do not have access to the same internal API that our CDN does. Even if you use our CDN, specifying the region explicitly will keep your JS agent working correctly if our internal API is temporarily disrupted.
The parameter is ignored when both the endpoint
and tlsEndpoint
parameters are used.
Example:
const fpPromise = FingerprintJS.load({ region: 'eu' })
endpoint
endpoint
Required: no
Default: (depends on the region)
Type:string | string[]
This parameter should only be used with the Custom subdomain or a cloud proxy integration. Specify your custom endpoint URL here.
Multiple endpoints can be set using an array. The JS agent will try to send the request with the first endpoint, and if the request fails, retry the request with the second endpoint, and so on. Use FingerprintJS.defaultEndpoint
to fall back to the default endpoint.
import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'
const fpPromise = FingerprintJS.load({
apiKey: 'your-public-api-key',
endpoint: [
'https://fp.example.com', // This endpoint will be used primarily
FingerprintJS.defaultEndpoint, // The default endpoint will be used if the primary fails
],
})
JS agent will throw an error if an empty array is given.
tlsEndpoint
(deprecated)
tlsEndpoint
(deprecated)Required: no
Default: (a subpath of theendpoint
)
Type:string | string[]
Since: v3.1.0
As of JS Agent version 3.8.22, this option has been deprecated and will likely be removed in the next major version.
Your custom TLS endpoint URL address.
Multiple endpoints can be set with an array. The JS agent will try to send the request with the first endpoint, and if the request fails, retry the request with the second endpoint, and so on. Use FingerprintJS.defaultTlsEndpoint
to fall back to the default endpoint.
disableTls
(deprecated)
disableTls
(deprecated)Required: no
Default:false
Type:string
Since: v3.4.0
As of JS Agent version 3.8.22, this option has been deprecated and will likely be removed in the next major version.
Set to true
to disable the extra TLS request. This is not recommended as it will negatively affect your identification accuracy.
remoteControlDetection
remoteControlDetection
Required: no
Default:false
Type:boolean
Since: v3.10.0
Set to true
to enable the collection of data for identifying the use of remote control tools. We will collect this data until the collection of other signals is complete, so for faster devices, the process might be too quick to capture it effectively. In these scenarios, it is recommended to implement a delay between the load()
and get()
functions to improve detection accuracy.
storageKey
storageKey
Required: no
Default:'_vid'
Type:string
Name of key to store data in visitor browsers. The data is stored in cookies and local storage. You shouldn't change this parameter once your code runs in production. The change will cause the data in visitor browsers to be purged which will decrease the identification accuracy.
scriptUrlPattern
scriptUrlPattern
Only for NPM installation
Required: no
Default:'https://fpnpmcdn.net/v<version>/<apiKey>/loader_v<loaderVersion>.js'
Type:string | string[]
Since: v3.6.0
By default, the JS agent downloads the code from our CDN. The scriptUrlPattern
option overrides this default by providing a pattern of the URL from where the JS agent downloads the latest code at runtime. This is commonly used in two scenarios:
- To set up the agent download URL through your Custom Subdomain.
- To correctly set up the agent download through proxy integrations.
JS agent automatically substitutes the following substrings in the provided scriptUrlPattern
string:
<version>
— the major version of the JS agent;<apiKey>
— the public key set via theapiKey
parameter;<loaderVersion>
— the exact version of the@fingerprintjs/fingerprintjs-pro
package.
You can set multiple endpoints using an array. The JS agent will try to download the code from the first URL, and if it fails, retry to download with the second URL, and so on. Use FingerprintJS.defaultScriptUrlPattern
to fall back to the default URL.
import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'
const fpPromise = FingerprintJS.load({
apiKey: 'your-public-api-key',
scriptUrlPattern: [
// This endpoint will be used primarily
'/myproxy/v<version>/<apiKey>/loader_v<loaderVersion>.js',
// The default endpoint will be used if the primary fails
FingerprintJS.defaultScriptUrlPattern,
],
})
urlHashing
urlHashing
Only for NPM installation
Required: no
Default:undefined
(no hashing)
Type:UrlHashing
Since: v3.11.0
urlHashing
flags ensure no PII or secret data get unintentionally leaked through path
, query
or fragment
values in an URL by replacing raw values with a securely encoded hash.
urlHashing
configuration has no effect on performance or accuracy of Identification and Smart Signals products.
The UrlHashing
type has the following configuration structure
type UrlHashing = {
path?: boolean
query?: boolean
fragment?: boolean
}
path
replaces the path portion of the URL with a securely encoded hash if set totrue
query
replaces the query portion of the URL with a securely encoded hash if set totrue
fragment
replaces the fragment portion of the URL with a securely encoded hash if set totrue
The portion of the URL that contains either path
, query
or fragment
is replaced with a single value that represents a securely encoded hash of the original URL parts.
Example:
The following example illustrates the behavior of our JS agent without and with the urlHashing
flags configured. Original URL represents the URL we would normally send to our backend (in an obfuscated form) Result shows how our JS agent hashes the URL if the path
, query
and fragment
parameters of urlHashing
were set to true
respectively. The order of the query parameters has no effect on the output hash.
Original URL
https://example.com/test?param1=somePII¶m2=clientSecret¶m3=tokenValue#id342324
path enabled | query enabled | fragment enabled | Result |
---|---|---|---|
NO | YES | NO | https://example.com/test?UNrfPps8c1O_mrVgqvhVju4SCMDncBNJat8_iDK-00M#id342324 |
YES | NO | NO | https://example.com/n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg?param1=somePII¶m2=clientSecret¶m3=tokenValue#id342324 |
NO | NO | YES | https://example.com/test?param1=somePII¶m2=clientSecret¶m3=tokenValue#rws4nbTyh7ALUYP6QsxMBWqGTa2T0QzIWHBSRr0rHDo |
YES | YES | YES | https://example.com/n4bQgYhMfWWaL-qgxVrQFaO_TxsrC4Is0V1sFbDwCgg?UNrfPps8c1O_mrVgqvhVju4SCMDncBNJat8_iDK-00M#rws4nbTyh7ALUYP6QsxMBWqGTa2T0QzIWHBSRr0rHDo |
If either
query
,param
orfragment
part are empty, they are returned as-is without hashing. As an example URLhttps://example.com/?#
stays as is.
load()
response
load()
responseThe load()
function returns a Promise that resolves to the JavaScript agent instance. The instance has a get()
method you can use to identify visitors.
import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro';
async function identifyVisitor() {
const agent = await FingerprintJS.load({ apiKey: 'PUBLIC_API_KEY' })
const result = await agent.get()
console.log(result.visitorId)
}
See Configuring the JavaScript agent for more details.