Skip to main content
Welcome! This guide helps you migrate your Fastly VCL integration from API v3 to API v4. You will first gather your existing integration details, then upgrade your Fastly VCL config 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 temporary migration paths 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 variable (the one you already use with the v3 guide) PROXY_SECRET
  • Your current integration path variables (the ones you already use with the v3 guide)
    • INTEGRATION_PATH
    • AGENT_SCRIPT_DOWNLOAD_PATH
    • GET_RESULT_PATH
    • Note: once migration is complete and your website is fully on agent v4, AGENT_SCRIPT_DOWNLOAD_PATH and GET_RESULT_PATH are no longer required
  • Your public API key
  • Your region (example: us, eu, ap)

​
Step 1: Upgrade your Fastly VCL integration first

Update the VCL asset / configuration to a version that supports agent v4. The steps below are for the manual deployment method. For Terraform, run terraform apply to update to the latest version.

​
1.1 Get the latest VCL file from GitHub

​
1.2 Update your Fastly service

  • In Fastly, open your CDN service and clone the active version.
  • Replace the corresponding VCL file with the contents of the downloaded VCL file.
    • If you see a separate fingerprint related file you should update that.
    • If you only have main.vcl file you can just replace it.
  • Publish (activate) the new version.

​
1.3 Verify

Acceptance criteria:
  • The integration can still serve the v3 agent download path and v3 identification path.
  • The integration can also route v4 requests, for example requests under /web/v4/....
Verification ideas:
  • Open https://INTEGRATION_DOMAIN/INTEGRATION_PATH/status and confirm the integration is healthy.
  • Confirm your existing (v3) production client still works and can identify.
  • Validate your v4 traffic through the proxy. Try the code snippet below.
    NPM
    import * as Fingerprint from '@fingerprint/agent';

const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: ['https://metrics.yourwebsite.com/INTEGRATION_PATH?region=us'], // Replace "?region" query param with your region as well
});

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: 
// Replace `region` query param with your region
// Replace `PUBLIC_API_KEY` with your public API key
// Replace `INTEGRATION_PATH` with your integration path
import * as Fingerprint from '@fingerprint/agent';

const fp = Fingerprint.start({
    apiKey: 'PUBLIC_API_KEY',
    region: 'us',
    endpoints: ['https://metrics.yourwebsite.com/INTEGRATION_PATH?region=us'], // Replace "?region" query param with your region as well
})

fp.get()
.then((result) => {
    console.log(result);
})
.catch((err) => {
    // Optional: log errors; endpoint fallback is controlled via the `endpoints` option
    console.error(err);
});

​
Step 4: Monitor and finalize

After rollout:
  • Monitor proxied traffic and error rate from the integration status UI
  • 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 simplify any v3-specific configuration
    • You may remove the AGENT_SCRIPT_DOWNLOAD_PATH and GET_RESULT_PATH variables from your dictionary.