Migrating CloudFront proxy integration to JavaScript Agent V4

​

Migration overview

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

• CloudFormation:
  • If you’ve enabled the automatic updates 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 guide.
  • If you are not using automatic updates, you need to update the Lambda function manually.
• Terraform:
  • Update the Lambda function in your Terraform configuration.

​

Step 2: Update your CloudFront distribution cache behavior path

​

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):
   - 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

resource "aws_cloudfront_distribution" "cloudfront_dist" {
  ordered_cache_behavior {
    path_pattern = "FPJS_BEHAVIOR_PATH/*"
    path_pattern = "FPJS_BEHAVIOR_PATH*"
  }
}

 Segment      Segment
    ↓            ↓
ore54guier / vbcnkxb654 → 2 path segments

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
  integration_path_depth = 2
}

resource "aws_cloudfront_distribution" "cloudfront_dist" {
  // Your existing CloudFront configuration
  ordered_cache_behavior {
    path_pattern = "ore54guier/vbcnkxb654/*"
    path_pattern = "ore54guier/vbcnkxb654*"
  }
}

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

import * as Fingerprint from "@fingerprint/agent";

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

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

​

Step 4: Switch from JavaScript Agent V3 to V4

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_BEHAVIOR_PATH/FPJS_AGENT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>",
  ],
  endpoint: ["https://yourwebsite.com/FPJS_BEHAVIOR_PATH/FPJS_GET_RESULT_PATH"],
});

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

​

What’s next