🚀 Quick start guide

Use this URL to start your free FingerprintJS Pro subscription: FingerprintJS Pro signup.
No credit card is required.

JS Agent

Once you start your subscription, you need to install the JavaScript agent. The agent is required to send requests to our browser identification API. We refer to the JavaScript agent as "JS agent" further in this guide.

You can install the JS agent as a node module or you can use a CDN to use FingerprintJS as a global variable.

In order to install the node module, you can use NPM:

npm install @fingerprintjs/fingerprintjs-pro

Or you can install with Yarn:

yarn add @fingerprintjs/fingerprintjs-pro

Afterwards, add the code snippet below to all pages where you want to identify visitors.

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({ token: 'your-browser-token' })

// Get the visitor identifier when you need it.
fpPromise
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
<script>
  // Initialize the agent at application startup.
  const fpPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.onload = resolve;
    script.onerror = reject;
    script.async = true;
    script.src = 'https://cdn.jsdelivr.net/npm/'
      + '@fingerprintjs/[email protected]/dist/fp.min.js';
    document.head.appendChild(script);
  })
    .then(() => FingerprintJS.load({ token: 'your-browser-token' }));

  // Get the visitor identifier when you need it.
  fpPromise
    .then(fp => fp.get())
    .then(result => console.log(result.visitorId));
</script>

We support both NPM and global variable methods of usage. The global variable script can be loaded from the CDN or manually copied to your website's JS assets.

Note that you need to use your subscription browser token in the JS agent configuration. You can find your browser token in the dashboard under Tokens (see image below).

Every identification request will return a unique visitorId value for the current visitor. The visitorId accuracy is 99.5% (it means that out of 1,000 random unique visitors, up to 5 identifiers may be incorrect).

Screenshot of tokens in FingerprintJS dashboardScreenshot of tokens in FingerprintJS dashboard

Screenshot of tokens in FingerprintJS dashboard

EU Region users

If you chose the EU region during registration, please add this to the JS agent initialization:

FingerprintJS.load({
  token: 'your-pro-key',
+ region: 'eu'
})

This will guarantee that your data will always be kept in EU (Germany) and will not be replicated to other data centers.

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({
  token: 'your-browser-token',
  region: 'eu',
})

// Get the visitor identifier when you need it.
fpPromise
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
<script>
  // Initialize the agent at application startup.
  const fpPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.onload = resolve;
    script.onerror = reject;
    script.async = true;
    script.src = 'https://cdn.jsdelivr.net/npm/'
      + '@fingerprintjs/[email protected]/dist/fp.min.js';
    document.head.appendChild(script);
  })
    .then(() => FingerprintJS.load({
      token: 'your-browser-token',
      region: 'eu'
    }));

  // Get the visitor identifier when you need it.
  fpPromise
    .then(fp => fp.get())
    .then(result => console.log(result.visitorId));
</script>

Subdomain setup

Setting up a subdomain allows you to use your own domain with the FingerprintJS Pro API. It is required that you set up a subdomain for several reasons:

  • Improved Safari identification accuracy.
  • Extended lifetime of visitorID value by enabling secure first-party cookies.
  • Preventing ad blockers from blocking the API calls to our fraud-detection API.
  • Increased difficulty for malicious users to detect that your website is using FingerprintJS Pro.

After creating and verifying your subdomain, a FingerprintJS server will be connected directly to it.

To start the subdomain integration process, open your subscription and click the "Subdomain Integration" link in the sidebar.

Screenshot of how to add an SSL certificate in the FingerprintJS dashboardScreenshot of how to add an SSL certificate in the FingerprintJS dashboard

Screenshot of how to add an SSL certificate in the FingerprintJS dashboard

Issue an SSL certificate for your new subdomain

FingerprintJS will need to issue an SSL certificate for your subdomain. In order for FingerprintJS to issue a certificate, you need to confirm that you own or control the domain by adding a special validating DNS record.

You can add up to 50 domains to a single certificate. Note that all of the domains will be visible in your certificate. For an example of how multiple domains are visible in a single SSL certificate, please see this wikipedia.org certificate below:

Screenshot of multiple domains for wikipedia.orgScreenshot of multiple domains for wikipedia.org

Screenshot of multiple domains for wikipedia.org

If you need several certificates please contact [email protected] for pricing.

Please note that the certificate cannot be edited later. You will need to recreate the certificate from scratch if you want to change the list of domains. The domain ownership validation will fail if the record is not added during 48 hours.

Screenshot of how to add a domain in the FingerprintJS dashboardScreenshot of how to add a domain in the FingerprintJS dashboard

Screenshot of how to add a domain in the FingerprintJS dashboard

📘

Note:

  • You need to own the top-level domain on which you’re creating the subdomain.
  • Certificates cannot be issued for subdomains on domains like heroku.com, azurewebsites.net etc (those, that are owned by other companies.)
  • It should be a subdomain, not a domain.
  • Our recommendation is to create a subdomain like fp.yourdomain.com for this integration. You must use a new subdomain that you are not currently using for anything else.

You will need to add one DNS record to prove ownership of your domain. The record details will be provided on the second step of the subdomain integration wizard.

Screenshot of a CNAME record available in the FingerprintJS dashboardScreenshot of a CNAME record available in the FingerprintJS dashboard

Screenshot of a CNAME record available in the FingerprintJS dashboard

Editing the DNS records is done in your domain registrar account, e.g. GoDaddy DNS, or AWS Route53. Once you add the domain ownership verification record, we’ll issue your certificate.

Add a DNS record for your new subdomain

We will send you an email when your certificate is issued. When you receive this email, please click the link. That will bring you to the 3rd and final step of the subdomain integration wizard. For this step, you’ll need to add the 2nd DNS record to your DNS settings. This is necessary to point your subdomain to our server.

Screenshot of a completed SSL certificate process in the dashboardScreenshot of a completed SSL certificate process in the dashboard

Screenshot of a completed SSL certificate process in the dashboard

On page 3 of the wizard you will be provided with two A records for each subdomain listed. Make sure to add all A records to your DNS.

📘

Note:

Some DNS providers (like Route 53) allow you to add one record with two IP address values, while others require you to add one A record per IP address.

Configuring JS Agent

When the certificate is issued and your subdomain points to our server, your JS agent configuration needs to be updated with your subdomain URL.

You will see a full JavaScript example with your new subdomain URL in the code snippet example on the 3rd page of the wizard.

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({
  token: 'your-browser-token',
  endpoint: 'https://fp.yourdomain.com'
})

// Get the visitor identifier when you need it.
fpPromise
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
<script>
  // Initialize the agent at application startup.
  const fpPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.onload = resolve;
    script.onerror = reject;
    script.async = true;
    script.src = 'https://cdn.jsdelivr.net/npm/'
      + '@fingerprintjs/[email protected]/dist/fp.min.js';
    document.head.appendChild(script);
  })
    .then(() => FingerprintJS.load({
        token: 'your-browser-token',
        endpoint: 'https://fp.yourdomain.com'
    }));

  // Get the visitor identifier when you need it.
  fpPromise
    .then(fp => fp.get())
    .then(result => console.log(result.visitorId));
</script>

Subdomain integration pricing

The subdomain integration is free for one SSL certificate. Contact [email protected] if you need more than one SSL certificate.

Webhooks

We recommend creating and registering a webhook so that all responses are sent securely and in real time to your server as events occur. Note that webhooks are not a replacement for the JS agent responses, they're sent in addition to them.

You can register your webhook in the dashboard: Subscriptions -> Subscription name -> Webhooks. A webhook must use an https endpoint (it cannot use an IP address or an http endpoint).

You can read more information about webhooks here.

Server API

You can query identification events using our server API. To query the events, you will need a visitorId value and the API token (it is different from the browser token). You can find your API token on the Tokens page.

📘

Browser token vs API token

The browser token and API token are different tokens used in different parts of your integration. The browser token is used with the JS agent. The API token is used to make requests to our Server APIs to query identification events.

Screenshot of subscription tokens in the FingerprintJS dashboardScreenshot of subscription tokens in the FingerprintJS dashboard

Screenshot of subscription tokens in the FingerprintJS dashboard

This is the API endpoint to receive identification events data: https://api.fpjs.io/visitors/someVisitorID?token=your-api-token for the US region. If you created your account in the EU region then the endpoint domain will be https://eu.api.fpjs.io.

Replace someVisitorID with the visitorId that you want to use and your-api-token with your API token.

If the server API response has identification event data, then it is a valid visitorId. If it returns an empty response, then it is not a valid visitorId. If you get an error then your token is incorrect.

Tagging your requests

Sometimes you want to tag each identification request with a value that makes sense for your business, e.g. userId or shoppingCartId or a transactionId.
You can attach a linkedId or a tag value to an identification request, and it will be returned in a response. Tags and linkedIds are both available in the webhook and the server API responses.

An example of how to send a linkedId or a tag with your identification request:

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({ token: 'your-browser-token' })

// Get the visitor identifier when you need it.
fpPromise
  .then(fp => fp.get({ linkedId: 'your-linked-id', tag: { yourTag: 123456 } }))
  .then(result => console.log(result.visitorId))
<script>
  // Initialize the agent at application startup.
  const fpPromise = new Promise((resolve, reject) => {
    const script = document.createElement('script');
    script.onload = resolve;
    script.onerror = reject;
    script.async = true;
    script.src = 'https://cdn.jsdelivr.net/npm/'
      + '@fingerprintjs/[email protected]/dist/fp.min.js';
    document.head.appendChild(script);
  })
    .then(() => FingerprintJS.load({ token: 'your-browser-token' }));

  // Get the visitor identifier when you need it.
  fpPromise
    .then(fp => fp.get({ linkedId: 'your-linked-id', tag: { yourTag: 123456 }})
    .then(result => console.log(result.visitorId));
</script>

The webhook and the server API response will now contain the tag and/or linkedId:

{
  "requestId": "Px6VxbRC6WBkA39yeNH3",
  "tag": { "youTag": 123456 },
  "linkedId": "your-linked-id",
  …
}

More information about linkedId can be found here: https://dev.fingerprintjs.com/docs/js-agent#linkedid.
More information about tags is available here: https://dev.fingerprintjs.com/docs/js-agent#tag.

Try JS agent

Use the following code editors to try JS agent with your credentials.

CDN installation:

NPM installation:


Did this page help you?