Subdomain setup

Using a subdomain is required for correct identification while using FingerprintJS Pro.

The benefits of using a subdomain

  • Significant increase to accuracy in Safari.
  • Cookies are now recognized as “first-party.” This means they can live longer in the browser and extend the lifetime of visitorIds.
  • Ad blockers will not block our JS Agent from loading. Attempts to connect to an external URL will be stopped by most ad blockers while attempts to connect to an internal URL (like a subdomain) will be allowed.
  • FingerprintJS becomes harder to detect. Requests made directly to our website domain can be easily detected. By routing through a subdomain on your domain, FingerprintJS becomes harder for automated blockers and fraudsters to detect.

Setup process

📘

Note:

This process requires adding DNS records to your site. Please make sure you have access to your DNS through your DNS provider. Here are some guides to accessing your DNS with some of the most popular hosting sites:

1. Register your subdomains

In order to use a subdomain, we need to ensure the connection between your site and our server is secure. To do this, we register all subdomains with SSL certificates. With each subscription we provide one free SSL certificate which can hold up to 50 unique subdomains. If you would like to purchase additional SSL certificates, please let us know by messaging [email protected]

You can begin the setup process by going to the customer dashboard and clicking on “Subdomain Integration” in the sidebar. Then click “Add Certificate.”

Next, you will be able to add all of the subdomains you require. For most purposes, one subdomain is all you need.

When entering a subdomain, remember these guidelines:

  • The subdomain should ONLY be used for sending requests to our servers.
  • The subdomain’s primary domain should be the same as the request origin (e.g.: “fp.yourdomain.com” where “yourdomain.com” is the website where you want to set up FingerprintJS).
  • Do not use “fingerprintjs.youdomain.com” or “fingerprint.yourdomain.com” as your subdomain. Instead, use a subdomain like “fp.yourdomain.com” or “metrics.yourdomain.com”. This will make it harder for ad blockers to detect and disable the package from loading.

After you have entered your subdomains, click the submit button to go to the next step.

2. Add CNAME records to verify domain ownership

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.

After clicking submit, we provide a CNAME record for each subdomain. When the record is added to your DNS, it will verify your ownership of the domain and allow the certificate to be issued. Below you can see what our instructions would look like for the example subdomain “fp.yourdomain.com”.

Screenshot of CNAME records in the FingerprintJS dashboardScreenshot of CNAME records in the FingerprintJS dashboard

Screenshot of CNAME records in the FingerprintJS dashboard

At this point, you will need to add all the records seen on this page to your website’s DNS. Please allow up to 24 hours for your CNAME records to be validated once they have been added.

You can check the status of your SSL certificate by returning to the customer dashboard. SSL certificates can have one of three statuses:

  • Waiting Validation: At least one of the CNAME records is still “pending”. This can happen if the records haven’t been added yet or if the records were added incorrectly. To ensure the records are added correctly, you can run this command in terminal using the host value of the CNAME record:
dig <host> +short

If the record was added correctly, the CNAME value will be returned.

  • Invalid: The records have been found, but the certificate cannot be issued. This status occurs when there is a conflicting CAA record registered to the domain that is not allowing our SSL provider (AWS) to issue certificates. Fix this status by adding the following CAA record to your DNS (Replace <fp.yourdomain.com> with your subdomain):
<fp.yourdomain.com>. CAA 0 issue "amazon.com"
  • Issued: The CNAME was added correctly and the certificate has been issued. When your certificate is issued you will receive an email prompting you to return to the dashboard to complete your subdomain setup.

📘

Note:

Using Cloudflare as your DNS provider? Please make sure to disable DNS Proxying for all records associated with your subdomain and also ensure that Universal SSL is turned off.

3. Add A records for each subdomain

Once your certificate has been issued, an email will be sent with a link that will bring you to the next step of the setup.

Screenshot of a completed SSL certificate creation processScreenshot of a completed SSL certificate creation process

Screenshot of a completed SSL certificate creation process

Please navigate again to your DNS provider and enter the A records provided in the customer dashboard.

You will notice that each subdomain will have two corresponding A records. While only one is necessary to make the connection, we recommend that you add both records to ensure coverage in the case that one is temporarily unavailable.

📘

Note:

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

4. Adding the “endpoint” property to the JS Agent

Once the A records have been added, the JS Agent configuration needs to be updated with the “endpoint” property:

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

const fpPromise = FingerprintJS.load({
  token: 'your-browser-token',
  endpoint: 'https://fp.yourdomain.com'
})

// When you need the visitor identifier:
fpPromise
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))
<script>
  function initFingerprintJS() {
    const fpPromise = FingerprintJS.load({
      token: 'your-browser-token',
      endpoint: 'https://fp.yourdomain.com'
    })
    
    // When you need the visitor identifier:
    fpPromise
      .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>

This code snippet is also available on the final page of the subdomain setup (beneath the A records) and will include your custom subdomain for easy access.

📘

Note:

The endpoint subdomain should match the domain of the website

SSL Certificate pricing

With each subscription, we provide one free SSL certificate which can hold up to 50 unique subdomains. If you would like to purchase additional SSL certificates, please let us know by messaging [email protected]

Updated 2 months ago



Subdomain setup


Suggested Edits are limited on API Reference Pages

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