FingerprintJS

Quick start guide

You need to start a trial to use FingerprintJS Pro. Use this URL to start your trial: FingerprintJS Pro signup. A trial account only becomes active after you add a valid payment method.

JS Agent

Once you have your trial started, you need to configure the JS agent. The agent is required to send requests to our identification API.

Whenever you need to identify a visitor, use JS agent to send identification requests.
Every identification request will return a unique visitorId value, that will remain attached to the current visitor.
The visitorId accuracy is 99.5% (it means that out of 1,000 random visitors, 5 may be misidentified).

Add the code snippet below to all pages where you want to identify visitors.
We support both NPM and global variable methods of usage. Global variable script can be loaded from our CDN or manually copied to your website's JS assets.

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'
 
FingerprintJS.load({ token: 'your-browser-token' })
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
<script>
  function initFingerprintJS() {
    FingerprintJS.load({ token: 'your-browser-token' })
      .then(fp => fp.get())
      .then(result => console.log(result.visitorId));
  }
</script>
<script
  async
  src="//cdn.jsdelivr.net/npm/@fingerprintjs/[email protected]/dist/fp.min.js"
  onload="initFingerprintJS()"
></script>

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

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

FingerprintJS.load({
  token: 'your-pro-key',
+ region: 'eu'
})
import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'
 
FingerprintJS.load({ token: 'your-browser-token', region: 'eu' })
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
<script>
  function initFingerprintJS() {
    FingerprintJS.load({ token: 'your-browser-token', region: 'eu' })
      .then(fp => fp.get())
      .then(result => console.log(result.visitorId));
  }
</script>
<script
  async
  src="//cdn.jsdelivr.net/npm/@fingerprintjs/[email protected]/dist/fp.min.js"
  onload="initFingerprintJS()"
></script>

Subdomain integration

Subdomain integration allows you to use your own domain with FingerprintJS Pro API. It is strongly recommended that you enable a subdomain integration 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.
  • It is much harder to detect that your website is using FingerprintJS Pro.

After you enable the subdomain integration, your subdomain will be linked to a FingerprintJS server.

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

Issue an SSL certificate for your new subdomain

FingerprintJS needs to issue an SSL certificate for your subdomain first.
In order for FingerprintJS to issue a certificate, you need to confirm that you are the subdomain owner by adding a special validating DNS record.

When you add your subdomain certificate, you can add up to 20 domains to it.
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; make sure to add all your domains at once.

📘

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.

Editing the DNS records is done in your domain registrar account, e.g. GoDaddy DNS, CloudFlare or Route53 (if you’re on AWS).
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.
At 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.

Add two A records per each subdomain with IP addresses that we’ll show you on page 3 of the wizard.

If you added more than one domain on step 1 of the wizard, please add these A records for each corresponding subdomain.

📘

Note:

Some DNS providers (like Route 53) allow you to add one record with two IP address values, while others (like CloudFlare), 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'
 
FingerprintJS.load({ token: 'your-browser-token', endpoint: 'fp.yourdomain.com' })
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
<script>
  function initFingerprintJS() {
    FingerprintJS.load({ token: 'your-browser-token', 
                         endpoint: 'fp.yourdomain.com' })
      .then(fp => fp.get())
      .then(result => console.log(result.visitorId));
  }
</script>
<script
  async
  src="//cdn.jsdelivr.net/npm/@fingerprintjs/[email protected]/dist/fp.min.js"
  onload="initFingerprintJS()"
></script>

Subdomain integration pricing

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

Webhook

We recommend creating and registering your webhook with us, so that we stream the data securely in real time to your server as events occur. You can read more information about webhooks here https://dev.fingerprintjs.com/docs/webhooks. You can register your webhook in the dashboard: Subscriptions -> Subscription name -> Webhooks. A web hook must use an https domain (it cannot be an IP or a non https domain).

Server API

You can query visit information using our server API. To query a visitor's data, 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.

This is the API endpoint to receive data back about visitors to your website: 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 contains the history of the visitor, 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 request with a value that makes sense for your business, e.g. userId or shoppingCartId or a transactionId.
You can add a linkedId or a tag to a request, and it will be returned in a response. Tags and linkedIds are available in both webhooks and server API.

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

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'
 
FingerprintJS.load({ token: 'your-browser-token' })
  .then(fp => fp.get({ linkedId: 'your-linked-id', tag: { yourTag: 123456 } }))
  .then(result => console.log(result.visitorId))
<script>
  function initFingerprintJS() {
    FingerprintJS.load({ token: 'your-browser-token' })
      .then(fp => fp.get({ linkedId: 'your-linked-id', tag: { yourTag: 123456 }}))
      .then(result => console.log(result.visitorId));
  }
</script>
<script
  async
  src="//cdn.jsdelivr.net/npm/@fingerprintjs/[email protected]/dist/fp.min.js"
  onload="initFingerprintJS()"
></script>

The webhook and API payload will contain the tag and/or linkedId:

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

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

Updated 4 days ago


Quick start guide


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.