fingerprint-proxy-integration

name	fingerprint-proxy-integration
description	Protect the Fingerprint JS Agent (v4) against ad blockers and improve identification accuracy by routing it through a first-party custom subdomain or a proxy integration (Cloudflare, CloudFront, Azure, Nginx) using the v4 `endpoints` option. Use to maximize accuracy after basic identification works, or when requests to the default Fingerprint domain are being blocked.

Fingerprint — Protect against ad blockers (custom subdomain / proxy)

Maps to the dashboard "Protect against ad blockers" Get Started step. By default the JS Agent loads its script and sends requests to Fingerprint's domain, which some browsers and ad blockers block — dropping identification accuracy. Routing the agent through your own domain makes the traffic first-party so it isn't blocked.

This API changed in v4. The old scriptUrlPattern, endpoint (singular), tlsEndpoint, and disableTls options were removed and consolidated into a single endpoints option. Docs: https://docs.fingerprint.com/docs/custom-subdomain-setup · https://docs.fingerprint.com/reference/migrating-from-v3-to-v4.

There are two approaches, both configured in the dashboard and then pointed at from code:

Approach	Effort	Accuracy	When
Custom subdomain	Low — one DNS CNAME	Good	Simplest setup; quick win
Proxy integration	Higher — deploy a proxy	Best	Maximum accuracy; you control the edge

You can start with a subdomain and move to a proxy later — both change only where the agent loads its script from and the endpoints value, not your application logic.

The v4 endpoints option

• endpoints sets where the agent sends identification requests. It takes a single string (your subdomain/proxy origin); an array can be supplied when fallbacks are required.
• The script download URL is set separately:
  • CDN: it's the import URL — https://metrics.yourdomain.com/web/v4/<PUBLIC_API_KEY>.
  • NPM / framework SDKs: pass endpoints to the provider/start options (e.g. the FingerprintProvider endpoints prop). See snippets/subdomain-options.js.

Custom subdomain

1. In the dashboard, go to Settings → Subdomains → Add subdomain and register a custom subdomain (e.g. metrics.yourdomain.com) — it must be on the same site as your app.
2. Add the CNAME record it gives you at your DNS provider to verify domain ownership and let the SSL certificate be issued. Once the certificate shows Issued, add the two A records the dashboard provides to finish the connection. (You can sanity-check with dig <host> +short.)
3. Set endpoints to your subdomain (and, for CDN installs, import the script from it). See snippets/subdomain-options.js.

DNS/cert validation can take up to 24 hours, and the subdomain expires if records aren't set within 14 days. This DNS step is outside the SDK — if the user is blocked on verification, it's a DNS-provider/propagation issue, not a code problem; they can set endpoints once it verifies.

Proxy integration (max accuracy)

1. Deploy one of Fingerprint's proxy integrations at your edge — Cloudflare Worker, AWS CloudFront + Lambda@Edge, Azure, or Nginx — using the official integration package for your platform. It forwards a path on your domain to the Fingerprint ingest API with your proxy secret.
2. Configure the proxy secret in the dashboard for that environment.
3. Set endpoints to your proxy origin. Same code shape as the subdomain case — only the URL differs.

How to apply (code side)

• The only code change is in the provider/start options where you already pass the public key and region: add endpoints pointing at your subdomain/proxy. See snippets/subdomain-options.js.
• Keep the value in an env var (e.g. FINGERPRINT_ENDPOINTS) so dev/staging/prod can differ without code edits.
• Region still must match the workspace region.
• Verify in the browser devtools Network tab that agent requests now go to your domain and return 200.

Best practices

• Prefer the subdomain for a fast first step; graduate to a proxy when you need maximum accuracy.
• Don't expose the proxy secret to the browser — it lives only in your edge proxy config.
• If a request to your subdomain/proxy fails, the agent can fall back to Fingerprint's default endpoints; still handle identify errors so the flow degrades gracefully.