Custom subdomain setup

​

The benefits of using a custom subdomain

• Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox.
• Ad blockers can’t block the JavaScript agent. Most ad blockers stop requests sent to an external URL, but allow requests sent to an internal URL like a subdomain.
• Cookies are recognized as “first-party.” This means they can be saved in the visitor’s browser and used to reliably identify visitors when third-party cookies are blocked completely (for example, Safari blocks all third-party cookies).
• Fingerprint becomes harder to detect. Requests made directly to the Fingerprint domain are easy to detect. Routing through a subdomain on your own domain makes Fingerprint harder for automated blockers and fraudsters to detect.

​

1. Register your custom subdomain

• Use the subdomain only for sending requests to Fingerprint.
• Match the subdomain’s primary domain to the request origin. For example, use metrics.yourwebsite.com when you run Fingerprint on yourwebsite.com.
• Avoid the words fingerprint and fp in the subdomain name. Names like fingerprint.yourwebsite.com or fp.yourwebsite.com are easier for ad blockers to detect and block. Use a neutral name like metrics.yourwebsite.com instead.

​

2. Add DNS records

• One CNAME record verifies that you own the domain.
• Two A records route identification traffic to Fingerprint.

metrics.yourwebsite.com. CAA 0 issue "pki.goog"

​

Subdomain statuses

• Pending: Fingerprint is validating your DNS records and issuing the SSL certificate. This can take up to 24 hours. To confirm a record was added correctly, run dig HOST +short in your terminal, using the host value of the record. If the record is set up correctly, its value is returned.
• Active: Your records are validated and the certificate is issued. Your subdomain is ready to use.
• Failed: The records were found, but the certificate can’t be issued. This usually happens when a conflicting CAA record blocks Fingerprint’s SSL provider (Cloudflare) from issuing certificates. Add the CAA record shown in the dashboard, wait for it to propagate, then delete the failed subdomain and add it again.

​

3. Configure the JavaScript agent

• Update the endpoint property.
• Update the URL pattern used to download the agent (scriptUrlPattern for NPM packages or the import URL when using the CDN directly).

<script>
  // Initialize the agent at application startup:
  // The JavaScript agent will now download from your new subdomain
  const fpPromise = import('https://metrics.yourwebsite.com/web/v3/PUBLIC_API_KEY')
    .then(FingerprintJS => FingerprintJS.load({
      endpoint: [
        'https://metrics.yourwebsite.com',
        FingerprintJS.defaultEndpoint, // The default endpoint as fallback
      ]
    }));

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

import FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize the agent at application startup:
const fpPromise = FingerprintJS.load({
  apiKey: 'PUBLIC_API_KEY',
  scriptUrlPattern: [
    // Leave the path as show here, only replace the domain
    // All the parameters like <apiKey> are filled automatically by the package
    // /reference/v3/js-agent-load-function#scripturlpattern
    'https://metrics.yourwebsite.com/web/v<version>/<apiKey>/loader_v<loaderVersion>.js',
    FingerprintJS.defaultScriptUrlPattern, // Use the default endpoint as fallback
  ],
  endpoint: [
    'https://metrics.yourwebsite.com',
    FingerprintJS.defaultEndpoint, // The default endpoint as fallback
  ]
})

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

​

Frequently asked questions

​

I completed the setup. How can I add more subdomains?

1. Go to Settings > Subdomains and select New subdomain.
2. Repeat the setup steps for each new subdomain.