> ## 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 CloudFront proxy integration to JavaScript Agent V4

This migration guide describes how to switch to JavaScript Agent V4 in your Fingerprint CloudFront integration with zero downtime and without the need to update the proxy path used by your [JavaScript Agent](/reference/js-agent).

## Migration overview

<Info>
  **Upgrade to v2 first**

  If your CloudFront integration is still on v1, follow the [migrating CloudFront proxy integration from v1 to v2 guide](/docs/v3/cloudfront-integration-migration-from-v1-to-v2) to upgrade to **2.2.0** (or later) first. Then, return to this guide to finish migrating to JavaScript Agent V4.
</Info>

1. Update your CloudFront Integration to the latest version that supports JavaScript Agent V4 (**2.2.0** or later) using your preferred deployment method.
2. Update your CloudFront distribution cache behavior path.
3. Verify that the updated integration works.
4. Switch from JavaScript Agent V3 to V4 in your application.

## Step 1: Update your CloudFront Integration's Lambda function

Follow the update guide for your deployment method:

* **CloudFormation**:
  * If you've enabled the [automatic updates](/docs/install-cloudfront-integration-using-cloudformation#step-6-enable-automatic-updates-in-the-fingerprint-dashboard) you should already be using the latest version of the Lambda function.
  * **Important**: Due to recent changes on AWS, you might need to update your Management Lambda function permissions. To do so, follow the [CloudFront Management Lambda permissions update](/docs/cloudfront-cloudformation-mgmt-lambda-permissions-update) guide.
  * If you are not using automatic updates, you need to [update the Lambda function manually](/docs/manually-updating-your-aws-cloudfront-integration-lambda-function).
* **Terraform**:
  * [Update the Lambda function in your Terraform configuration](/docs/aws-cloudfront-integration-via-terraform#updating-the-integration).

To verify the integration version, check your integration status page available at `https://yourwebsite.com/FPJS_BEHAVIOR_PATH/status`.

## Step 2: Update your CloudFront distribution cache behavior path

Depending on your deployment method, you need to update the cache behavior path in your CloudFront distribution in the following ways:

<Info>
  The latest version of the Lambda function maintains compatibility with your existing CloudFront
  configuration and JavaScript agent v3, but the following CloudFront configuration change is
  recommended before upgrading to JavaScript agent v4.
</Info>

### CloudFormation

1. Head to your CloudFront distribution in the AWS console.
2. Select the **Behaviors** tab and edit the **fpcdn.io** behavior.
3. Update the **Path Pattern** from `FPJS_BEHAVIOR_PATH/*` to `FPJS_BEHAVIOR_PATH*` (without the trailing slash):
   ```diff theme={"theme":"github-dark-dimmed"}
   - FPJS_BEHAVIOR_PATH/*
   + FPJS_BEHAVIOR_PATH*
   ```
4. Save the changes.
5. If your behavior path contains more than one segment (e.g. `ore54guier/vbcnkxb654`):
   1. Head to the **Origins** tab and edit the **fpcdn.io** origin.
   2. Add a custom header:
      * Set **Header name** to `FPJS_INTEGRATION_PATH_DEPTH`.
      * Set **Value** to the number of path segments in the behavior path, in our example it's `2`.
      ```
       Segment      Segment
          ↓            ↓
      ore54guier / vbcnkxb654 → 2 path segments
      ```
   3. Save the changes.

### Terraform

<Info>
  Ensure that you're using our Terraform Module version [v2.0.0](https://github.com/fingerprintjs/terraform-aws-fingerprint-cloudfront-proxy-integration/releases/tag/v2.0.0) or later.
</Info>

Update your CloudFront distribution cache behavior `path_pattern` from `FPJS_BEHAVIOR_PATH/*` to `FPJS_BEHAVIOR_PATH*` (without the trailing slash)

```terraform main.tf theme={"theme":"github-dark-dimmed"}
resource "aws_cloudfront_distribution" "cloudfront_dist" {
  ordered_cache_behavior {
    path_pattern = "FPJS_BEHAVIOR_PATH/*" // [!code --]
    path_pattern = "FPJS_BEHAVIOR_PATH*" // [!code ++]
  }
}
```

If your behavior path contains more than one segment (e.g. `ore54guier/vbcnkxb654`), you need to count the number of path segments in the behavior path and add the `integration_path_depth` parameter with value equal to the number of path segments:

```
 Segment      Segment
    ↓            ↓
ore54guier / vbcnkxb654 → 2 path segments
```

```terraform main.tf theme={"theme":"github-dark-dimmed"}
module "fingerprint_cloudfront_integration" {
  source = "fingerprintjs/fingerprint-cloudfront-proxy-integration/aws"

  fpjs_shared_secret       = "FPJS_PRE_SHARED_SECRET"
  // The number of path segments in the behavior path, in this case 2: ore54guier/vbcnkxb654 // [!code ++]
  integration_path_depth = 2 // [!code ++]
}

resource "aws_cloudfront_distribution" "cloudfront_dist" {
  // Your existing CloudFront configuration
  ordered_cache_behavior {
    path_pattern = "ore54guier/vbcnkxb654/*" // [!code --]
    path_pattern = "ore54guier/vbcnkxb654*" // [!code ++]
  }
}
```

Finally, apply the changes:

1. Run `terraform plan` to verify the planned configuration changes.
2. Run `terraform apply` to apply the changes.

## Step 3: Update your application to use the JavaScript Agent V4

At this point, you should have CloudFront integration running that will work with both v3 and v4 JavaScript agents.

Try using the integration with the V4 agent. For example:

```javascript JavaScript theme={"theme":"github-dark-dimmed"}
import * as Fingerprint from "@fingerprint/agent";

const fp = Fingerprint.start({
  apiKey: "PUBLIC_API_KEY",
  region: "us",
  endpoints: "https://yourwebsite.com/FPJS_BEHAVIOR_PATH/?region=us",
});

fp.get().then((result) => console.log(result));
```

All requests from the agent should go through your integration and resolve successfully. Confirm by using the Network tab in your browser Developer tools, as the JavaScript agent can fall back to default endpoints in case of an integration error.

## Step 4: Switch from JavaScript Agent V3 to 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_BEHAVIOR_PATH/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>",
  ],
  endpoint: ["https://yourwebsite.com/FPJS_BEHAVIOR_PATH/FPJS_GET_RESULT_PATH?region=us"],
});

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

## What's next

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