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 workspace.

If you are just getting started with Fingerprint, we recommend reading the following guides first:

• Install the JavaScript agent
• Identify visitors

If you encountered errors using the JavaScript agent, see the Error handling reference.

load() options

To configure the agent, pass parameters into the load() function or its equivalent in your frontend library.

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

Required: no
Default: "us"
Type: string
Available values: "us", "eu" and "ap"

Use this parameter to specify the region you picked for your workspace 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

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)

Required: no
Default: (a subpath of the endpoint)
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)

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

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

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

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 the apiKey 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

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 to true
• query replaces the query portion of the URL with a securely encoded hash if set to true
• fragment replaces the fragment portion of the URL with a securely encoded hash if set to true

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&param2=clientSecret&param3=tokenValue#id342324

📘

If either query, param or fragment part are empty, they are returned as-is without hashing. As an example URL https://example.com/?# stays as is.

load() response

The 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.