Guides
Sign Up
Start typing to search…

Cloudflare Proxy integration - Manual setup

If your website is running on a subdomain, using a Cloudflare partial CNAME setup, you will not be able to install the Fingerprint Cloudflare proxy integration using the installation wizard in the Dashboard.

In this case, this guide will help you manually create and configure the proxy worker in your Cloudflare account.

Step 1: Issue a proxy secret

Your integration needs a proxy secret to authenticate requests from your Cloudflare worker to Fingerprint servers.

  1. Go to the Fingerprint Dashboard and select your application in the top left.
  2. Navigate to App settings > API Keys.
  3. Click Create proxy key.
  4. Name it something like Cloudflare integration.
  5. Click Create API key.
  6. Save the secret value somewhere. You will use later as the PROXY_SECRET variable.

Step 2: Create path variables

Set the path variables you will use in your worker configuration and the JavaScript agent configuration on your website. These values are arbitrary. Just decide what your values are and write them down somewhere.

In this guide, we will use readable values corresponding to the variable names to make it easier to follow:

WORKER_PATH="WORKER_PATH"
AGENT_SCRIPT_DOWNLOAD_PATH="AGENT_SCRIPT_DOWNLOAD_PATH"
GET_RESULT_PATH="GET_RESULT_PATH"

However, your values used in production should look more like random strings:

WORKER_PATH="ore54guier"
AGENT_SCRIPT_DOWNLOAD_PATH="vbcnkxb654"
GET_RESULT_PATH="5yt489hgfj"

That is because some adblockers might automatically block requests from any URL containing fingerprint-related terms like "fingerprint", "fpjs", "track", etc. Random strings are the safest. So whenever you see a value like GET_RESULT_PATH in this guide, you should use your random value instead.


Step 3: Deploy a Fingeprint proxy worker in your Cloudflare account

  1. Go to the Cloudflare Dashboard.
  2. Choose your account.
  3. In the left menu, go to Workers & Pages.
  4. Click Create > Create Worker.
  5. Give it a name like fingerprint-proxy-integration.
  6. Click Deploy.
  7. Click Edit code.
    1. In a new tab, go to the latest release of Fingerprint Pro Cloudflare Worker on Github and download the fingerprintjs-pro-cloudflare-worker.esm.js file.
    2. Replace the "Hello world" worker code with the content of the fingerprintjs-pro-cloudflare-worker.esm.js file.
  8. Click Deploy.
  9. Go back to Workers & Pages > fingerprint-proxy-integration > Settings > Variables.
  10. Under Environment variables, add the following variables:
    1. PROXY_SECRET - the proxy secret you issued in Step 1.
    2. WORKER_PATH - defined in Step 2.
    3. AGENT_SCRIPT_DOWNLOAD_PATH - defined in Step 2.
    4. GET_RESULT_PATH - defined in Step 2.
  11. Click Deploy.

Your worker should now be deployed and functional.

You can verify this by clicking Visit to go the Cloudflare-issued worker URL and going to /status. For example: https://fingerprint-proxy-integration.your-cf-account.workers.dev/status.

You should be seeing the worker's status page saying all environment variables are set.

Step 4: Add a custom domain to your worker


  1. Navigate to to Workers & Pages > fingerprint-proxy-integration > Settings > Triggers.
  2. Click Add Custom Domain.
  3. Choose a domain from which to serve your worker, for example yourwebsite.com or metrics.yourwebsite.com.
  4. Click Add custom domain.
  5. Allow some time for a new certificate to be issues and the DNS record to propagate.

Your proxy worker should now be accessible from your domain. You can check by going to metrics.yourwebsite.com/YOUR_WORKET_PATH/status.

Step 5: Configure the Fingerprint JavaScript agent on your client

Use the path variables created in Step 2 to construct the agent-download and result-endpoint URLs.

If you deployed your proxy worker on your main domain, the JavaScript Agent configuration will use randomized paths inside your domain, for example:

import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize the agent at application startup.
const fpPromise = FingerprintJS.load({
  apiKey: 'PUBLIC_API_KEY',
  scriptUrlPattern: [
    'https://yourwebsite.com/WORKER_PATH/AGENT_SCRIPT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    'https://yourwebsite.com/WORKER_PATH/GET_RESULT_PATH?region=us',
    FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
  ],
});
const url = 'https://yourwebsite.com/WORKER_PATH/AGENT_SCRIPT_DOWNLOAD_PATH?apiKey=<PUBLIC_API_KEY>';
const fpPromise = import(url)
  .then(FingerprintJS => FingerprintJS.load({
    endpoint: [
      'https://yourwebsite.com/WORKER_PATH/GET_RESULT_PATH?region=us',
      FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
    ]
  }));

If you deployed your proxy worker on a subdomain, the JavaScript Agent configuration will use that subdomain to interact with Fingerprint, for example:

import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'

// Initialize the agent at application startup.
const fpPromise = FingerprintJS.load({
  apiKey: 'PUBLIC_API_KEY',
  scriptUrlPattern: [
    'https://metrics.yourwebsite.com/WORKER_PATH/AGENT_SCRIPT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    'https://metrics.yourwebsite.com/WORKER_PATH/GET_RESULT_PATH?region=us',
    FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
  ],
});
const url = 'https://metrics.yourwebsite.com/WORKER_PATH/AGENT_SCRIPT_DOWNLOAD_PATH?apiKey=<PUBLIC_API_KEY>';
const fpPromise = import(url)
  .then(FingerprintJS => FingerprintJS.load({
    endpoint: [
      'https://metrics.yourwebsite.com/WORKER_PATH/GET_RESULT_PATH?region=us',
      FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
    ]
  }));

📘

Parameter URL nuances

  • Note that the import url for the CDN installation method and scriptUrlPattern used by the NPM package are similar but different and cannot be used interchangeably.
  • Pay attention to differences in query parameters:
    • Pass region to the endpoint parameters in the following format: ?region=eu. The value needs to reflect the region of you application.
    • Leave thescriptUrlParam parameter as displayed here: ?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>. The apiKey version and loaderVersion parameters will be replaced by the values in the NPM package automatically. Do not alter them manually.

If everything is configured correctly, you should receive data through your Cloudflare proxy worker successfully.

Updated 2 months ago