🚀 Quick start guide

Fingerprint Pro platform

Fingerprint Pro as a platform consists of two products: Identification (former Fingerprinting) and Bot Detection (beta).

🚧

Bot Detection limited availability

Bot Detection product is not available to all users while in beta. To enable it for your account, reach out to [email protected]

Create a subscription

Click this link to start your free Fingerprint Pro subscription: Fingerprint Pro signup.
(if you have issues accessing our dashboard, go to this troubleshooting page)

Once you've started your free subscription, go to App Settings -> API Keys to get your public API key that you'll need to run examples on this page.
No credit card is required to start your subscription, but you'll need a credit card if you want to upgrade to a paid plan.

📘

Integrations and SDKs

To view the list of supported integrations, please visit this page: https://fingerprint.com/integrations/
For SDKs and framework libraries, go to this page: https://fingerprint.com/sdk-libraries/

JS Agent

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

Full JS agent reference is available here. If you need to start with a mobile platform, please use either Android or iOS guide.

You can install the JS agent from a CDN into an HTML code directly, or as a Node module.

To install the Node module, use NPM or Yarn:

npm install @fingerprintjs/fingerprintjs-pro

Or:

yarn add @fingerprintjs/fingerprintjs-pro

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

<script>
  // Initialize the agent at application startup.
  // Some ad blockers or browsers will block Fingerprint Pro CDN URL.
  // To fix this, please use the NPM package instead.
  const fpPromise = import('https://fpjscdn.net/v3/<<browserToken>>')
    .then(FingerprintJS => FingerprintJS.load());

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

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({ apiKey: '<<browserToken>>' })

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

Note that you need to use your subscription public API key in the JS agent configuration. You can find your public API key in the dashboard under App Settings -> API Keys (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).

EU Region users

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

FingerprintJS.load({
  apiKey: '<<browserToken>>',
+ region: 'eu'
})

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

<script>
  // Initialize the agent at application startup.
  const fpPromise = import('https://fpjscdn.net/v3/<<browserToken>>')
    .then(FingerprintJS => FingerprintJS.load({
      region: 'eu'
    }));

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

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({
  apiKey: '<<browserToken>>',
  region: 'eu'
})

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

Asia (Mumbai) Region users

Similarly to the EU Region, if you choose the Asia (Mumbai) region during registration, configure the JS agent:

<script>
  // Initialize the agent at application startup.
  const fpPromise = import('https://fpjscdn.net/v3/<<browserToken>>')
    .then(FingerprintJS => FingerprintJS.load({
      region: 'ap'
    }));

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

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({
  apiKey: '<<browserToken>>',
  region: 'ap'
})

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

Custom subdomain setup

Setting up a custom subdomain allows you to use your own domain with the Fingerprint Pro platform. 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 backend.
• Increased difficulty for malicious users to detect that your website is using Fingerprint Pro.

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

To create a custom subdomain, open your subscription, navigate to App Settings, and switch to the Subdomains tab.

Issue an SSL certificate for your new subdomain

Fingerprint will need to issue an SSL certificate for your subdomain. In order for Fingerprint 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:

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 DNS record is not added within 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 metrics.yourwebsite.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 Custom subdomain setup.

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 custom domain creation wizard. For this step, you’ll need to add the 2nd DNS record to your DNS settings. This is necessary to point your custom subdomain to our server.

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 separated by a new line, 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.

<script>
  // Initialize the agent at application startup.
  const fpPromise = import('https://fpjscdn.net/v3/<<browserToken>>')
    .then(FingerprintJS => FingerprintJS.load({
        endpoint: 'https://metrics.yourwebsite.com'
    }));

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

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({
  apiKey: '<<browserToken>>',
  endpoint: 'https://fp.yourdomain.com'
})

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

Custom subdomain pricing

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

For a full custom subdomain guide please go to this page: Custom Subdomain Guide.

Webhooks

We recommend creating and registering a webhook so that all events are sent securely and in real time to your server as they occur.

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 or visitor information using our Server API. To query the events, you will need a requestId value and the secret API key (it is different from the public API key). To query the visitor information, including the visitor history, you will need a visitorId value. You can find your secret API key on the API Keys page.

We support several official server-side SDKs to help you work with our server API in your favorite programming language: SDKs and Libraries.

📘

Public API key vs Secret API key

The public API key and secret API key are different API keys used in different parts of your integration. The public API key is used with the JS agent, the Android SDK and the iOS SDK. The secret API key is used to make requests to our Server API to query events securely.

Tagging events

Sometimes you want to tag each event 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:

<script>
  // Initialize the agent at application startup.
  const fpPromise = import('https://fpjscdn.net/v3/<<browserToken>>')
    .then(FingerprintJS => FingerprintJS.load({
        endpoint: 'https://metrics.yourwebsite.com'
    }));

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

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize an agent at application startup.
const fpPromise = FingerprintJS.load({ apiKey: '<<browserToken>>' })

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

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

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

You can find the difference between linkedId and tag on the below documentation pages.
More information about linkedId can be found here: https://dev.fingerprint.com/docs/js-agent#linkedid.
More information about tags is available here: https://dev.fingerprint.com/docs/js-agent#tag.

Try the JS agent in your browser

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