Proxy integrations

Content blockers and privacy extensions often refuse requests to third-party APIs. When they refuse Fingerly's, the visitor is simply not identified. A proxy integration sends the SDK's requests to a path on your own site instead, where they look like the rest of your traffic.

Why a Fingerly proxy is different

A naive reverse proxy would make every visitor arrive from your server's address, and every network signal would describe your server rather than the visitor. A Fingerly proxy authenticates with a proxy key, and only then may it tell Fingerly the visitor's real address, origin and user agent. A public key alone can never do that, so nobody can spoof those details with your public key.

Options

Proxy keys

Proxy keys look like fly_px_us_production_…. Owners and admins issue them for one environment in Integration > Proxy keys, and each key is shown once, when it is issued. Only owners and admins can see and revoke them. A proxy key only forwards client requests: it cannot read events, and it must match the public key's organization, environment and region.

Point the SDK at your path

import { load } from '@fingerly/web-js'

const fingerly = await load({
  apiKey: 'fly_pk_us_production_…',
  endpoints: '/metrics',                // your proxy's path
  fallbackToDefaultEndpoint: true,      // optional: try Fingerly directly if the proxy fails
})

The SDK appends /api/v1/identify to the path, and sends deferred reports to /api/v1/events/{request_id}/supplement under it. Omit fallbackToDefaultEndpoint to keep every request first-party.

Build your own proxy

Forward only the two client routes, as POST, to your region's API, and replace the visitor headers with values you resolved yourself.

• Do not forward cookies or Authorization headers, and strip Set-Cookie from responses.
• Refuse other paths and methods, and cap request bodies at 1 MiB.
• Do not follow redirects from the upstream.
• Answer CORS preflights if the page and the proxy are on different origins.

Data residency

A proxy never changes where data goes. The region is part of both keys, and a request forwarded to another region's API is refused.