> ## 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.

# Migrating Azure Proxy integration from v1 to v2

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.

<Note>
  **Improvements over v1**

  * **New runtime and consumption plan**: The functions now run using the new [Flex Consumption plan](https://learn.microsoft.com/en-us/azure/azure-functions/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](/reference/js-agent) while maintaining backward compatibility with the [JavaScript agent v3](/reference/v3/javascript-agent).
</Note>

<Warning>
  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](https://learn.microsoft.com/en-us/azure/azure-functions/consumption-plan).

  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](/reference/js-agent).
</Warning>

## 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](/reference/js-agent).
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](https://dashboard.fingerprint.com/) 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.](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2Ffingerprintjs%2Fazure-frontdoor-proxy%2Fmain%2Fazuredeploy.json/createUIDefinitionUri/https%3A%2F%2Fraw.githubusercontent.com%2Ffingerprintjs%2Fazure-frontdoor-proxy%2Fmain%2FcreateUiDefinition.json)

**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](#step-2-verify-that-the-integration-works) and [Step 5](#step-5-remove-the-old-integration).

## 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 JavaScript theme={"theme":"github-dark-dimmed"}
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>', // [!code --]
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>', // [!code ++]
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX/FPJS_GET_RESULT_PATH?region=us', // [!code --]
    'https://yourwebsite.com/FPJS_ROUTE_PREFIX_v2/FPJS_GET_RESULT_PATH?region=us', // [!code ++]
    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.

### Option A: Update your client agent to use the v2 Front Door path (recommended)

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](https://www.npmjs.com/package/@fingerprintjs/fingerprintjs-pro) or [client library](/docs/frontend-libraries), you can even use the v1 integration as a fallback for v2:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
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>', // [!code ++]
   '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', // [!code ++]
    '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 JavaScript theme={"theme":"github-dark-dimmed"}
import * as FingerprintJS from "@fingerprintjs/fingerprintjs-pro"; // [!code --]
import * as Fingerprint from "@fingerprint/agent"; // [!code ++]

// [!code --:10]
const fpPromise = FingerprintJS.load({
  apiKey: "PUBLIC_API_KEY",
  region: "us",
  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?region=us"],
});

// [!code ++:10]
const fp = Fingerprint.start({
  apiKey: "PUBLIC_API_KEY",
  region: "us",
  endpoints: "https://yourwebsite.com/FPJS_ROUTE_PREFIX/?region=us",
});
```

To learn more, see the [JavaScript agent v4 migration guide](/reference/migrating-from-v3-to-v4).

## 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**.