Custom Proxy Integrations

Documentation Index

Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt

Use this file to discover all available pages before exploring further.

• 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 visitor IDs.
• Ad blockers, browser extensions, and VPNs will not block the Fingerprint client agent from loading and making identification requests. Connecting to a Fingerprint CDN and API is blocked by most ad blockers but connecting to the same site URL is allowed. To learn more, see Protecting the JavaScript agent from ad blockers.

​

Existing proxy integrations

• Custom subdomain setup — built-in proxy integration running entirely on Fingerprint infrastructure.
• Akamai Integration — uses Akamai property rules to proxy requests.
• Azure Integration— uses an Azure function as a proxy.
• AWS CloudFront Integration — uses a Lambda@Edge function as a proxy.
• Cloudflare Integration — uses Cloudflare Workers as a proxy.
• Fastly VCL Integration — uses Fastly CDN service VCL rules as a proxy.
• Fastly Compute@Edge Integration — uses Fastly Compute service as a proxy.

​

Custom proxy integration requirements

​

First-party context

• For example, if your website is yourwebsite.com, then yourwebsite.com/metrics or metrics.yourwebsite.com are both acceptable URLs.
• When choosing the endpoint URLs, don’t use fingerprint, fpjs, or other words related to fingerprinting that might get blocked by ad blockers. Pick generic words like metrics, data, or completely random strings.

​

Types of HTTP requests to proxy

​

1. Proxy the Agent download request (browsers only)

1. Create a GET server endpoint. Make it available on a /RANDOM_PATH/web/* path in your application, so that it will expect additional path segments. The random path segment is used to avoid detection by ad blockers.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   // Request handler for the agent-download request
   // Available on yourwebsite.com/RANDOM_PATH/web/*
   
   export async function GET(request: Request) {
     // Agent download proxy implementation
   }
   
2. Use the path segment after web to compile correct agent-download URL.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   const regex = /\/web(\/.*)?/; 
   // This will extract the path segment after "web"  
   const path = new URL(request.url).pathname.match(regex)?.[1];
   
   const agentDownloadUrl = new URL('https://api.fpjs.io');
   // Provide extracted path segments as the path of the download URL  
   agentDownloadUrl.pathname = `/web/${path}`  
   
3. Forward all existing query parameters and add aii monitoring parameter. Use this form for the ii parameter: custom-proxy-integration/<integration_version>/procdn. The ii parameter is necessary to display an integration usage chart in the dashboard. It will help you and the Fingerprint team monitor your integration and diagnose potential issues. Make sure to append, not set the ii parameter to avoid overwriting existing ii parameters.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   agentDownloadUrl.search = request.url.split('?')[1];
   agentDownloadUrl.searchParams.append('ii', `custom-proxy-integration/1.0.1/procdn`);
   
4. Forward all headers except the cookie header. Because the integration runs in the first-party context it has access to authentication cookies and other sensitive data. Remove all cookies before forwarding the agent download request to Fingerprint.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   const headers = new Headers();
   for (const [key, value] of request.headers.entries()) {
     headers.set(key, value);
   }
   headers.delete('cookie');
   
5. Request the JavaScript agent from Fingerprint CDN. Use the download URL and headers you have prepared.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   const agentResponse = await fetch(agentDownloadUrl, {
     headers,
   });
   
6. Set your own cache-control header if necessary. The integration should generally forward the cache-control header it gets from Fingerprint CDN to the client. However, these are GET requests that can end in .js and your cloud infrastructure setup or pre-existing cache mechanism might get in the way and overwrite the cache limits to excessively large values. This would result in the JavaScript agent getting out of date, leading to lower identification accuracy. You might need to experimentally verify if this is happening. If you are not sure, it’s safest to overwrite the cache-control header of the proxied response to ensure the JavaScript agent is not being cached for longer than one minute.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   // If you cannot properly forward the cache-control header, add one manually with low max-age values
   const updatedHeaders = new Headers(agentResponse.headers);
   updatedHeaders.set('cache-control', 'public, max-age=3600, s-maxage=60');
   
7. Delete encoding headers if necessary. If your HTTP library decompresses or decodes the response automatically (as fetch does in this example), you need to remove these headers to tell the client that the response is not compressed. Alternatively, depending on your HTTP library, you can disable the automatic decompression and keep the headers.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   updatedHeaders.delete('content-encoding');
   updatedHeaders.delete('transfer-encoding');
   
8. Return the response to the client. No error handling is needed, the proxy integration must return the response as received.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   return new Response(agentResponse.body, {
     status: agentResponse.status,
     statusText: agentResponse.statusText,
     headers: updatedHeaders,
   });
   
9. Handle internal errors. When the proxy integration itself throws an error, it should return HTTP 500. The response body is optional but recommended.
   src/app/RANDOM_PATH/web/[...path]/route.ts

   export async function GET(request: Request) {
     try {
       // Agent download proxy implementation from above
     } catch (error) {
       return new Response(`Agent download error: ${error} `, {
         status: 500,
       });
     }
   }
   

​

2. Proxy the Identification request

1. Create a POST server endpoint. In API v4, the identification path is base path, so it should be available on /RANDOM_PATH that is equal to the path used in the agent download request.
   src/app/RANDOM_PATH/route.ts

   // Request handler for the identification request
   // Available on POST yourwebsite.com/RANDOM_PATH
   
   export async function POST(request: Request) {
     // Identification request  proxy implementation
   }
   
2. Use the right identification URL — https://api.fpjs.io, https://eu.api.fpjs.io, or https://ap.api.fpjs.io depending on your workspace region.
   src/app/RANDOM_PATH/route.ts

   const identificationUrl = new URL(`https://api.fpjs.io`);
   
3. Forward all existing query parameters and add an ii monitoring parameter. Use this form for the ii parameter custom-proxy-integration/<integration_version>/ingress. The ii parameter is necessary to display an integration usage chart in the dashboard. It will help you and the Fingerprint team monitor your integration and diagnose potential issues. Make sure to append, not set the ii parameter to avoid overwriting existing ii parameters.
   src/app/RANDOM_PATH/route.ts

   identificationUrl.search = request.url.split('?')[1] ?? '';
   identificationUrl.searchParams.append('ii', `custom-proxy-integration/1.0/ingress`);
   
4. Forward all headers as they are, except thecookie header.
   src/app/RANDOM_PATH/route.ts

   const headers = new Headers();
   for (const [key, value] of request.headers.entries()) {
     headers.set(key, value);
   }
   headers.delete('cookie');
   
5. Delete all cookies except_iidt. Remove all cookies from the cookie header and include only the _iidt identification cookie if present. The _iidt cookie is set by the Fingerprint server and is needed to ensure high identification accuracy.
   src/app/RANDOM_PATH/route.ts

   const cookieMap = parseCookies(request.headers.get('cookie'));
   const _iidtCookie = cookieMap['_iidt'];
   if (_iidtCookie) {
     headers.set('cookie', `_iidt=${_iidtCookie}`);
   }
   
6. Add the necessary Fingerprint headers. Authenticate your request and forward the incoming request’s IP and host to the Fingerprint Identification API. Missing or invalid values of any of these headers will result in failure of the identification request.
   src/app/RANDOM_PATH/route.ts

   headers.set('FPJS-Proxy-Secret', PROXY_SECRET);
   headers.set('FPJS-Proxy-Client-IP', parseIp(request));
   headers.set('FPJS-Proxy-Forwarded-Host', parseHost(request));
   

   Header Key	Header Value
   FPJS-Proxy-Secret	Your Fingerprint workspace’s proxy secret. You can create one in the Fingerprint dashboard. You can choose to scope the proxy secret to a specific environment.
   FPJS-Proxy-Client-IP	The client IP address of the incoming request. Only accepts valid, public (not private or bogon) IPv4 or IPv6 addresses.
   FPJS-Proxy-Forwarded-Host	The URL host of the incoming request. Only accepts a valid Host string.

   Securely storing the proxy secretThe FPJS-Proxy-Secret header contains a sensitive proxy secret value. To ensure security, do not hard-code this value in the source code as plaintext . Instead, use encrypted environment variables or another secret storage mechanism available on your chosen deployment platform.
   Passing FPJS-Proxy-* header validationThe FPJS-Proxy-* headers sent by your integration are validated by the Fingerprint Identification API.

   • If the FPJS-Proxy-Secret is missing or does not contain a valid proxy secret associated with your Fingerprint workspace and environment, the identification request will fail with a 403 Forbidden status code.
   • If any of the other FPJS-Proxy-* headers is missing, duplicate, or contains an invalid value, the identification request will fail with a 422 Unprocessable Entity status code. For example:
     • FPJS-Proxy-Forwarded-Host is empty or it’s value is not a valid host string.
     • FPJS-Proxy-Client-IP is empty, contains multiple IP addresses, or contains a private or bogon IP address.

   The requirement to use an external IP in the FPJS-Proxy-Client-IP can cause issues when developing or testing your proxy integration on your machine. Even a correct implementation will end up passing a private IP address when running on a local network. To work around this, you can:

   • Temporarily hard-code the FPJS-Proxy-Client-IP header to your public IP address during development.
   • Deploy your integration to a staging environment on a public network for testing.
   • Use a tunneling library like ngrok or LocalTunnel to make your locally running integration available on a public URL and test it from there. Note that not all tunneling libraries correctly forward the true client’s IP address, but we tested both Ngrok and LocalTunnel and found them to work well.
7. Make the identification request. Use the identification URL and headers you have prepared above. Forward the incoming request’s body without change.
   src/app/RANDOM_PATH/route.ts

   const identificationResponse = await fetch(identificationUrl, {
     headers: headers,
     method: 'POST',
     body: await request.blob(),
   });
   
8. Remove the HSTS header if necessary. If your app needs to work using HTTP, remove the strict-transport-security header. Otherwise, forward all headers as they come.
   src/app/RANDOM_PATH/route.ts

   const updatedHeaders = new Headers(identificationResponse.headers);
   updatedHeaders.delete('strict-transport-security');
   
9. Return the response to the client. No error handling is needed, the proxy integration must return the response as received.
   src/app/RANDOM_PATH/route.ts

   return new Response(await identificationResponse.blob(), {
     status: identificationResponse.status,
     statusText: identificationResponse.statusText,
     headers: updatedHeaders,
   });
   
10. Handle internal errors. When the proxy integration itself throws an error, it should return HTTP 500 using a specific error format shown in the example implementation below.
    • error.message is the message provided by your integration.
    • requestId is a unique ID in the following format:<timestamp>.<id>. The id is a 6-character long string randomly picked from[a-zA-Z0-9]\.
    src/app/RANDOM_PATH/route.ts

    export async function POST(request: NextRequest) {
      try {
        // Proxy logic defined above
        return await proxyIdentificationRequest(request);
      } catch (error) {
        console.error(error);
        return getErrorResponse(request, error);
      }
    }
    
    const getErrorResponse = (request: Request, error: unknown): Response => {
      const message = isNativeError(error) ? error.message : error;
      const requestId = `${new Date().getTime()}.${randomShortString({ length: 6 })}`;
      console.error(message, requestId);
      return Response.json(
        {
          v: '2',
          error: {
            code: 'IntegrationFailed',
            // You can return a generic error here instead
            // if you don't want to leak information to the client
            message: `An identification error occurred with the custom integration. Reason: ${message}`,
          },
          requestId,
          products: {},
        },
        {
          status: 500,
          headers: {
            'Content-Type': 'application/json',
            'Access-Control-Allow-Origin':
              request.headers.get('origin') ?? new URL(request.url).origin,
            'Access-Control-Allow-Credentials': 'true',
          },
        }
      );
    };
    

​

3. Proxy the Browser cache request (browsers only)

1. Create a GET server endpoint. Make it available on the same path as the identification endpoint but expect additional random path segments. For example, if your identification endpoint is available on https://yourwebsite.com/RANDOM_PATH then the JavaScript agent will make GET browser cache requests to URLs like https://yourwebsite.com/RANDOM_PATH/abc345/xyz123.
   src/app/RANDOM_PATH/[...randomPathSegments]/route.ts

   // Request handler for the browser cache request
   // Available on yourwebsite.com/RANDOM_PATH/[...randomPathSegments]
   //  e.g. https://yourwebsite.com/RANDOM_PATH/abc345/xyz123
   
   export async function GET(
     request: Request,
     { params }: { params: { randomPathSegments: string[] } }
   ) {
     // Browser cache request proxy implementation
   }
   
2. Use the random path segments with the identification URL to get the right browser cache URL. For example, if the incoming request is https://yourwebsite.com/RANDOM_PATH/abc345/xyz123 and your identificationUrl was https://api.fpjs.io/ (global region) then the request to Fingerprint servers must have this URL: https://api.fpjs.io/abc345/xyz123.
   src/app/RANDOM_PATH/[...randomPathSegments]/route.ts

   const randomPath = params.randomPathSegments.join('/');
   const browserCacheUrl = new URL(`https://api.fpjs.io/${randomPath}`);
   
3. Forward all query parameters. You don’t need to add any parameters here.
   src/app/RANDOM_PATH/[...randomPathSegments]/route.ts

   browserCacheUrl.search = request.url.split('?')[1];
   
4. Forward all headers except thecookie header.
   src/app/RANDOM_PATH/[...randomPathSegments]/route.ts

   const headers = new Headers();
   for (const [key, value] of request.headers.entries()) {
     headers.set(key, value);
   }
   headers.delete('cookie');
   
5. Make the browser cache request. Use the browser cache URL and headers you have prepared above.
   src/app/RANDOM_PATH/[...randomPathSegments]/route.ts

   const browserCacheResponse = await fetch(browserCacheUrl, {
     headers,
   });
   
6. Return the fresh response to the client. No changes to the provided headers or error handling are necessary here. Make sure that the response is never cached. The response is unique for each browser, any caching could lead to false positives (returning the same visitor ID for different browsers).
   src/app/RANDOM_PATH/[...randomPathSegments]/route.ts

   return browserCacheResponse;
   
7. Handle internal errors. When the proxy integration itself throws an error, it should return HTTP 500. The response body is optional but recommended.
   src/app/RANDOM_PATH/[...randomPathSegments]/route.ts

   export async function GET(
     request: Request,
     { params }: { params: { randomPathSegments: string[] } }
   ) {
     try {
       // Browser cache request proxy implementation from above
     } catch (error) {
       return new Response(`Browser cache request error: ${error} `, {
         status: 500,
       });
     }
   }
   

​

4. Configure the Fingerprint client agent

• Set endpoints to the path of your identification proxy endpoint, for example, yourwebsite.com/RANDOM_PATH.

import * as Fingerprint from '@fingerprint/agent'

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

​

Fallback endpoints

​

5. Test and monitor your proxy integration

• The latest used integration version.
• How many identification requests are coming through the integration (and how many are not).

​

Migrating from v3 to v4

​

Server-side changes

1. Agent download endpoint — change from query parameter-based to path-based URL construction. In v4, the path is extracted from the request URL instead of using query parameters:

// v3: Query parameter-based URL construction
const queryParams = new URLSearchParams(request.url.split('?')[1]); 
const apiKey = queryParams.get('apiKey'); 
const version = queryParams.get('version') ?? 3; 
const loaderVersion = queryParams.get('loaderVersion'); 
const loaderParam = loaderVersion ? `/loader_v${loaderVersion}.js` : ''; 
const agentDownloadUrl = new URL(`https://fpcdn.io/v${version}/${apiKey}${loaderParam}`); 

// v4: Path-based URL construction
const regex = /\/web(\/.*)?/; 
const path = new URL(request.url).pathname.match(regex)?.[1]; 
const agentDownloadUrl = new URL('https://api.fpjs.io'); 
agentDownloadUrl.pathname = `/web/${path}`; 

2. Unified base path — in v4, the agent download and identification endpoints share a common base path instead of separate paths:

​

Client-side changes

import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'; 
import * as Fingerprint from '@fingerprint/agent'; 

const fpPromise = FingerprintJS.load({ 
const fp = Fingerprint.start({ 
  apiKey: 'PUBLIC_API_KEY',
  scriptUrlPattern: [ 
    'https://yourwebsite.com/metrics/YOUR_AGENT_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>', 
    FingerprintJS.defaultScriptUrlPattern, 
  ], 
  endpoint: [ 
    'https://yourwebsite.com/metrics/YOUR_IDENTIFICATION_PATH', 
    FingerprintJS.defaultEndpoint, 
  ], 
  endpoints: 'https://yourwebsite.com/RANDOM_PATH', 
});

const url = 'https://yourwebsite.com/metrics/YOUR_AGENT_PATH?apiKey=PUBLIC_API_KEY'; 
const url = 'https://yourwebsite.com/RANDOM_PATH/web/v4/PUBLIC_API_KEY'; 
const fpPromise = import(url).then((FingerprintJS) =>
  FingerprintJS.load({ 
const fpPromise = import(url).then((Fingerprint) =>
  Fingerprint.start({ 
    endpoint: [ 
      'https://yourwebsite.com/metrics/YOUR_IDENTIFICATION_PATH', 
      FingerprintJS.defaultEndpoint, 
    ], 
    endpoints: 'https://yourwebsite.com/RANDOM_PATH', 
  })
);