FingerprintJS

Quick start guide

Use this URL to start your FingerprintJS Pro trial: FingerprintJS Pro signup. We require credit cards for our trials.

JS Agent

Once you start your trial, you need to install the JS agent. The agent is required to send requests to our identification API.

You can install the JS Agent as a node module or you can use a CDN.

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'
 
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="https://cdn.jsdelivr.net/npm/@fingerprintjs/[email protected]/dist/fp.min.js"
  onload="initFingerprintJS()"
></script>

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

Note that you need to use your specific 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 visitors, 5 identifiers will likely be incorrect).

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'
})
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="https://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 the FingerprintJS Pro API. It is strongly recommended that you enable 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 subdomain integration, your subdomain will be assigned 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 will need to issue an SSL certificate for your subdomain. In order for FingerprintJS to issue a certificate, you need to confirm that you control the domain by adding a special validating DNS record.

You can add up to 20 domains to to a single certificate but all of the domains will be visible on the same certificate. 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 certificate validation will fail if the record is not added during 48 hours.

📘

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

Add two A records for 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: 'https://fp.yourdomain.com'
    })
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
<script>
  function initFingerprintJS() {
    FingerprintJS.load({
            token: 'your-browser-token',
            endpoint: 'https://fp.yourdomain.com'
        })
        .then(fp => fp.get())
        .then(result => console.log(result.visitorId));
  }
</script>
<script
  async
  src="https://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.

Webhooks

We recommend creating and registering a webhook with us, so that we stream the data securely and in real time to your server as events occur.

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

You can read more information about webhooks here https://dev.fingerprintjs.com/docs/webhooks.

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.

🚧

Browser token vs API token

The browser token and API token are different values 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 APIs to collect data back about visitors.

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 both available via webhooks and the 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="https://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 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.

Updated 18 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.