Skip to main content
Welcome! This guide helps you migrate your Akamai integration from API v3 to API v4. You will first gather your existing integration details, then upgrade your Akamai property configuration so it can handle both v3 and v4 routes, validate v4 traffic through the proxy before changing production, update your app to JavaScript Agent v4, and finally monitor the rollout and clean up any v3-specific configuration once v3 traffic has fully stopped.
Follow the steps below in order. If you keep v3 working while you validate v4, you can roll forward safely and avoid user impact.

​
Step 0: Collect Inputs (no changes yet)

You should have:
  • Your current integration domain (example: https://metrics.yourwebsite.com)
  • Your current proxy secret (FPJS_PROXY_SECRET property sensitive variable)
  • Your current v3 integration path variables:
    • FPJS_INTEGRATION_PATH (found in the path match criteria of the Fingerprint rule)
    • FPJS_AGENT_PATH (found in the path match criteria of the Fingerprint > Origin for Agent rule)
    • FPJS_RESULT_PATH (found in the path match criteria of the Fingerprint > Origin for Ingress rule)
  • Your public API key
  • Your region (example: us, eu, ap)
After migration is complete and your website is fully on agent v4, only FPJS_INTEGRATION_PATH is needed. FPJS_AGENT_PATH and FPJS_RESULT_PATH related configs can be removed.

​
Step 1: Upgrade your Akamai integration

Update the Akamai property configuration to a version that supports JavaScript Agent v4. Choose your deployment method below.

​
1.1 Using Terraform

  1. Update your akamai_property_rules_template variable blocks:
    • Remove fpjs_agent_path and fpjs_result_path variables.
    • Add the new fpjs_integration_path_escaped variable.
    main.tf
    data "akamai_property_rules_template" "rules" {
      template_file = "/rules/main.json"
      variables {
        name  = "fpjs_integration_path"
        value = "FPJS_INTEGRATION_PATH"
        type = "string"
      }
      variables {
        name  = "fpjs_integration_path_escaped"
        value = "YOUR_INTEGRATION_PATH_ESCAPED" # same as FPJS_INTEGRATION_PATH but with / escaped as \\/ and . escaped as \.
        type = "string"
      }
      variables {
        name  = "fpjs_proxy_secret"
        value = "FPJS_PROXY_SECRET"
        type = "string"
      }
}
  2. Download the latest terraform-fingerprint-property-rules.json and terraform-fingerprint-property-variables.json files from the latest release and replace the existing ones in your rules directory.
  3. Run terraform plan to review your changes.
  4. Run terraform apply.
For full details, see Deploy Akamai proxy integration using Terraform.

​
1.2 Using Akamai Property Manager API (PAPI)

  1. Clone the Akamai proxy integration repository: 
    git clone git@github.com:fingerprintjs/akamai-proxy.git
  2. Install dependencies: 
    pnpm install
  3. Generate the patch body. Note that --agent-path and --result-path are no longer needed: 
    pnpm build --type patchBody \
    --integration-path "FPJS_INTEGRATION_PATH" \
    --proxy-secret "FPJS_PROXY_SECRET"
  4. Follow the PAPI deployment steps (clone property version, remove existing Fingerprint artifacts, patch, activate) as described in Deploy Akamai proxy integration using PAPI.

​
1.3 Verify

Acceptance criteria:
  • The integration can still serve v3 agent download and identification requests.
  • The integration can also route v4 requests, for example requests under /FPJS_INTEGRATION_PATH/web/v4/....
Verification ideas:
  • Open https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/status and confirm the integration is healthy.
  • Confirm your existing (v3) production client still works and can identify.
  • Validate v4 routing through the proxy with a quick test:
    NPM
    import * as Fingerprint from '@fingerprint/agent';

const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: ['https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
});

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

​
Step 2: Validate v4 routing before changing your production client

Before flipping your app, test v4 through the proxy. Options:
  • Use a staging site / feature flag to load agent v4.
  • Temporarily run agent v4 in a dev environment.
What to check:
  • The agent script loads through the proxy (no ad blocker or CDN errors)
    • You may use browser dev tools’ network tab to confirm the script is loaded from the proxy.
  • Identification requests go through the proxy (not directly to Fingerprint default endpoints)
  • Results are returned successfully

​
Step 3: Update your application to JavaScript Agent v4

Update your website to load and initialize agent v4 using your proxy base URL. Replace the placeholders with your values: 
import * as FingerprintJS from '@fingerprintjs/fingerprintjs-pro'; 
import * as Fingerprint from '@fingerprint/agent'; 

const fpPromise = FingerprintJS.load({
    apiKey: 'PUBLIC_API_KEY',
    scriptUrlPattern: [
        'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_AGENT_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
        FingerprintJS.defaultScriptUrlPattern,
    ],
    endpoint: [
        'https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH/FPJS_RESULT_PATH?region=us',
        FingerprintJS.defaultEndpoint,
    ],
});

const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: ['https://metrics.yourwebsite.com/FPJS_INTEGRATION_PATH?region=us'],
});
To learn more about JavaScript Agent v4 changes, see the JavaScript Agent v3 to v4 migration guide.

​
Step 4: Monitor and finalize

After rollout:
  • Monitor proxied traffic and error rate from the integration status page in the Fingerprint Dashboard.
  • Confirm the majority of traffic is using v4 paths.
Optional cleanup (later):
  • If you introduced any temporary parallel paths for testing, remove them.
  • When you are confident no clients use v3, you can remove v3-specific configuration:
    • Terraform: The fpjs_agent_path and fpjs_result_path variable blocks should already be removed from Step 1.
    • PAPI: The updated property rules no longer use FPJS_AGENT_PATH and FPJS_RESULT_PATH, so no additional cleanup is needed.