Skip to main content

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.

This migration guide describes how to switch to Fingerprint Azure integration v2 if you are currently running the first version. The migration steps ensure zero downtime.
Improvements over v1
  • New runtime and consumption plan: The functions now run using the new Flex Consumption plan and runtime 4.x.
  • Updated Node runtime: The v1 functions run on Node 20. The v2 functions run on Node 24.
  • JavaScript agent v4 Support: The v2 version of the integration fully supports the JavaScript agent v4 while maintaining backward compatibility with the JavaScript agent v3.
Azure is sunsetting the old consumption plan and runtime 3.x. v1 of the Azure Proxy Integration will stop working after September 30, 2026. See the Azure Functions consumption plan documentation.We recommend updating to the v2 of the integration as soon as possible to avoid possible downtime. The v2 version of the proxy integration is also required to use the JavaScript agent v4.

​
Migration overview

  1. Deploy Azure integration v2 on a new path. You will have v1 and v2 running in parallel.
  2. Verify that the new integration works.
  3. Switch from v1 to v2 proxy integration.
  4. Optional: Migrate to JavaScript agent v4.
  5. Optional: Remove the old integration.

​
Step 1: Deploy Azure Proxy Integration v2 on a new path

​
Step 1.1: Issue a proxy secret

You need a proxy secret to authenticate requests to the Fingerprint API from your Azure function.
  1. Go to the Fingerprint dashboard and select your workspace.
  2. In the left-side menu, go to API keys.
  3. Click Create proxy key.
  4. Give it a name, for example, Azure proxy integration v2.
  5. Click Create API Key.
Store this value somewhere safe, you cannot retrieve it later.

​
Step 1.2: Choose a path variable

Choose a value for FPJS_ROUTE_PREFIX_v2 that is different from the one used by your v1 integration. Use a random string rather than a descriptive name, some ad blockers block URLs containing fingerprint-related terms like “fingerprint”, “fpjs”, or “track”. You will use this value in the deployment template and when configuring the JavaScript agent.

​
Step 1.3: Deploy the Azure function

Click here to open the template deployment dialog. Basics step
  1. Select your Azure Subscription.
  2. Select or create a Resource group. We suggest using a separate resource group for the v2 integration.
  3. Specify Region and Location.
  4. Set Function App Name, for example, azure-frontdoor-proxy-app-v2.
  5. Click Next.
Routing configuration step
  1. Set Route Prefix to your FPJS_ROUTE_PREFIX_v2 value.
  2. Click Next.
Security step
  1. Set Proxy Secret to the proxy secret generated in Step 1.1.
  2. Click Review + Create, then Create.

​
Step 1.4: Verify the deployment

  1. After deployment completes, click Go to resource group.
  2. In the resources list, find your Function App using the Type column and click it.
  3. Click Overview in the left-side menu and confirm that both the proxy and management functions are listed.
  4. Click proxy, then Get Function URL and copy the default (function key) URL.
  5. Build the status page URL by replacing {*restOfPath} with FPJS_ROUTE_PREFIX_v2/status and open it in your browser. If it says All environment variables are set, your function is running correctly.

​
Step 1.5: Add a route to your Front Door distribution

Since you already have a Front Door distribution from the v1 integration, add a new route to it for v2.
  1. Open your Front Door distribution.
  2. Go to Settings → Front Door manager.
  3. Inside your Front Door endpoint, click Add a route.
  4. Set Name to something descriptive, like fingerprint-integration-v2-route.
  5. Keep Enable route selected.
  6. Set Domains to the same domain used by your v1 integration.
  7. In Patterns to match, add /FPJS_ROUTE_PREFIX_v2/* and /FPJS_ROUTE_PREFIX_v2.
  8. Set Accepted protocols to HTTPS only.
  9. Keep Redirect all traffic to use HTTPS selected.
  10. Click Add a new origin group:
    1. Set Name to something descriptive, like fp-origin-group-v2.
    2. Click Add an origin:
      1. Set Name to something descriptive, like fp-origin-v2.
      2. Set Origin type to App services.
      3. Set Host name to the function app deployed in Step 1.3.
      4. Click Add to save the origin.
    3. Keep Enable health probes selected.
    4. Set health probe Path to /FPJS_ROUTE_PREFIX_v2/status.
    5. Set Protocol to HTTPS.
    6. Set Probe method to GET.
    7. Click Add to save the origin group.
  11. Set Forwarding protocol to HTTPS only.
  12. Click Add to save the route.
The route update may take up to 20 minutes to propagate. Do not configure the JavaScript agent yet, that is covered in Step 2 and Step 5.

​
Step 2: Verify that the integration works

At this point, you should have both v1 and v2 integration running side by side. You can go to their respective status pages to confirm:
  • yourwebsite.com/FPJS_ROUTE_PREFIX/status should display a status page of Azure integration v1.x.
  • yourwebsite.com/FPJS_ROUTE_PREFIX_v2/status should display a status page of Azure integration v2.x.
Try using the v2 integration with your client agent to test the integration. For example:
JavaScript
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/FPJS_ROUTE_PREFIX/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>', 
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>', 
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_GET_RESULT_PATH?region=us', 
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_GET_RESULT_PATH?region=us', 
    FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
  ],
});
All requests from the agent should go through v2 and resolve successfully. Confirm by using the Network tab in your browser’s developer tools, as the JavaScript agent can fall back to default endpoints in case of an integration error.

​
Step 3: Switch from v1 to v2

You have two options for migrating from your v1 integration to v2. Choose the one that suits you best depending on your deployment options:
  • Option A (recommended): Update your JavaScript agent configuration to point to the v2 path. If you can update your client-side code, choose this option: it is simple, requires no downtime, and is easy to roll back.
  • Option B: Update the Front Door distribution to route the v1 path to the v2 function. Choose this if you cannot update your client-side code, for example, because you are serving a mobile app and need to wait for users to upgrade.
Update your client agent to use the v2 integration on the new path, as shown in the previous step. Both integrations remain fully operational during the switch, making it easy to roll back in case of any problems. If you are using our NPM package or client library, you can even use the v1 integration as a fallback for v2:
JavaScript
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/FPJS_ROUTE_PREFIX_v2/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>', 
   'https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_GET_RESULT_PATH?region=us', 
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_GET_RESULT_PATH?region=us',
    FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
  ],
});

​
Option B: Update the existing v1 route to use the v2 function

If you can’t update your client-side code and can’t afford downtime, you can update your v1 proxy route configuration to match the v2 configuration in the Azure UI.
  1. Navigate to the deployed v2 function app in the Azure portal.
  2. In the left sidebar, expand Settings and click Environment Variables.
  3. Locate fpjs_route_prefix variable and set it to the same value used by your v1 integration. (FPJS_ROUTE_PREFIX).
  4. Click Save.
  5. Go to your Front Door distribution.
  6. On the right side in the Properties tab, locate your Endpoint hostname and click it.
  7. Locate the route of your Azure Integration v1 and click it.
  8. Add an additional pattern in the Patterns to match: /FPJS_ROUTE_PREFIX
  9. Replace Origin group with the new origin group that you’ve created for your v2 integration.
  10. If you have caching enabled, set Query string caching behavior to Ignore Query String.
  11. Click Update.
Requests coming to the original v1 route prefix are now being processed by the v2 function. Updating the Front Door distribution may take up to 20 minutes.

​
Step 4: Migrate to JavaScript agent v4

At this point, you can start migrating your application to use the new JavaScript agent v4.
JavaScript
import * as FingerprintJS from "@fingerprintjs/fingerprintjs-pro"; 
import * as Fingerprint from "@fingerprint/agent"; 

const fpPromise = FingerprintJS.load({
  apiKey: "PUBLIC_API_KEY",
  scriptUrlPattern: [
    "https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>",
  ],
  endpoint: ["https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_GET_RESULT_PATH"],
});

const fp = Fingerprint.start({
  apiKey: "PUBLIC_API_KEY",
  endpoints: "https://yourwebsite.com/FPJS_ROUTE_PREFIX/",
});
To learn more, see the JavaScript agent v4 migration guide.

​
Step 5: Remove the old integration

When all your client application agents use the new integration, you can remove the old integration.
  1. In your Front Door distribution, remove the origin group of the v1 integration. If you went with option A, you can also remove the route of the v1 integration.
  2. Locate the resource group of the v1 integration.
    • If during the v1 deployment you created a new resource group and use it only for the v1 integration, simply delete it.
    • Otherwise follow steps below to only delete the v1 resources without deleting the resource group:
      1. In the resource group page, in the left sidebar expand Settings and click Deployments.
      2. Locate the deployment of the v1 integration, select the checkbox and click Delete.