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.

​

Set up in the dashboard

​

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.

​

One-click setup with Domain Connect

• Cloudflare

1. Select Connect. The dashboard redirects you to your DNS provider.
2. Sign in to your DNS provider if you aren’t signed in already.
3. Review the consent page. It lists the exact CNAME and A records Fingerprint adds. With Cloudflare, the records are shown as DNS only, make sure that proxying stays off.
4. Select Authorize. Your DNS provider adds the records right away and returns you to the dashboard.

​

Add DNS records manually

​

Conflicting CAA records

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

​

Verify your records

​

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.
• Timed out: DNS validation timed out because the required records weren’t added in time. Add the DNS records, then restart verification.
• 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

<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/v4/PUBLIC_API_KEY')
    .then(Fingerprint => Fingerprint.start({
      endpoints: 'https://metrics.yourwebsite.com',
    }));

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

</script>

import Fingerprint from '@fingerprint/agent';

// Initialize the agent at application startup:
const fp = Fingerprint.start({
  apiKey: 'PUBLIC_API_KEY',
  endpoints: 'https://metrics.yourwebsite.com',
});

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

​

Set up with the CLI

npx fingerprint integrate --subdomain metrics.yourwebsite.com

​

Manage subdomains with the Management API

​

Available endpoints

• Register a subdomain (POST /subdomains): Registers the subdomain and returns every DNS record you need, the verification CNAME and the routing A records, in a single response.
• List subdomains (GET /subdomains): Lists every subdomain in the workspace and its status. Filter by status to find, for example, subdomains still in the pending state.
• Get subdomain (GET /subdomains/{id}): Retrieves a single subdomain with its DNS records and current status.
• Create Domain Connect URL (POST /subdomains/{id}/domain-connect): Returns a signed DNS-provider authorization link that redirects to your local callback listener.
• Verify subdomain (POST /subdomains/{id}/verify): Triggers an on-demand DNS check instead of waiting for the next background check. Use this right after you add your DNS records.
• Delete subdomain (DELETE /subdomains/{id}): Deletes the subdomain and revokes its SSL certificate.

​

Typical flow

​

Frequently asked questions

​

My DNS provider doesn’t offer one-click setup. What should I do?

​

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.

​

What’s next

• Start your free workspace now