Custom subdomain setup

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

The benefits of using a custom subdomain

  • Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox.
  • 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 sending identification API requests to our server. Sending data to an external URL will be stopped by most ad blockers while sending data to a an internal URL (like a subdomain) is allowed.
  • Fingerprint becomes harder to detect. Requests made directly to our website domain can be easily detected. By routing through a subdomain on your domain, Fingerprint becomes harder for automated blockers and fraudsters to detect.


Limitations of the subdomain integration

  • Even though setting a custom subdomain will help you with making the API requests in the browser, ad blockers and some browsers may still block our CDN and prevent the JS agent from being downloaded to the web page. To work around that, you can use a proxy integration like Cloudflare or Cloudfront.
  • To obtain a TLS fingerprint of the browser, Fingerprint Pro also makes a separate request to our TLS endpoint. Due to technical limitations, this request is also not protected by the custom subdomain and can be blocked by ad blockers. While the TLS data is useful, Fingerprint Pro can still generate an accurate visitor identifier without it. A custom TLS endpoint domain is available for enterprise subscriptions, contact our support for more details.


A note on DNS setup:

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 custom subdomains

In order to use a custom 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 navigating to App Settings -> Subdomain and clicking Add Certificate.


Screenshot of the Custom Subdomain setup in the Fingerprint dashboard

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


Screenshot of the SSL Certificate Creation in the Fingerprint dashboard

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.: “” where “” is the website where you want to set up FingerprintJS).
  • Do not use “” or “” as your subdomain. Instead, use a subdomain like “” or “”. 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 Fingerprint 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 “”.


Screenshot of CNAME records in the Fingerprint 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 the 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 first adding the following CAA record to your DNS (replace <> with your subdomain): <>. CAA 0 issue ""

    Once the CAA record propagates, return to the Fingerprint Dashboard, delete the Invalid certificate, and repeat step 1.

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



Using Cloudflare as your DNS provider?

  1. Make sure to disable DNS Proxying for all records associated with your subdomain.
  2. Be aware that Cloudflare sometimes adds CAA records that are not visible in the DNS panel. To see these records, you can run the command below (just replace <> with your domain):

$ dig caa <>

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 process

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

Each subdomain has two corresponding A records. While only one is necessary to make the connection, we recommend adding both records to ensure coverage if one is temporarily unavailable.



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:

  // Initialize the agent at application startup.
  const fpPromise = import('<<browserToken>>')
    .then(FingerprintJS => FingerprintJS.load({
      endpoint: ''

  // When you need the visitor identifier:
    .then(fp => fp.get())
    .then(result => console.log(result.visitorId));
import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

const fpPromise = FingerprintJS.load({
  apiKey: '<<browserToken>>',
  endpoint: ''

// When you need the visitor identifier:
  .then(fp => fp.get())
  .then(result => console.log(result.visitorId))

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.



The endpoint subdomain should match the domain of the website



If you use a Content Security Policy on your website, don't forget to add the custom subdomain to the connect-src directive of your policy. See the CSP guide for more details.

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]