Guides
Sign Up
Start typing to search…

Akamai Proxy Integration

Fingerprint JS agent v3.6.0 or later is required.

Fingerprint Akamai Proxy Integration is responsible for proxying identification and agent-download requests between your website and Fingerprint through your Akamai infrastructure. The integration consists of a set of property rules you need to add to your Akamai property configuration. The property rules template is available on GitHub.

🚧

Limitations and expectations

Integration in Beta

This integration is in Beta. Please report any issues to our support team.

Limited to Enterprise plan

Support for the Akamai Proxy Integration is provided only to customers on the Enterprise Plan. Other customers are encouraged to use Custom subdomain setup or Cloudflare Proxy Integration.

Manual updates occasionally required

The underlying data contract in the identification logic can change to keep up with browser and device releases. Using the Akamai Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.

The benefits of using the Akamai Proxy Integration

  • Significant increase in accuracy in browsers with strict privacy features such as Safari or Firefox.
  • Cookies are now recognized as “first-party.” This means they can live longer in the browser and extend the lifetime of visitor IDs.
  • Ad blockers will not block our Fingerprint JS agent from loading. Attempts to connect to an external URL will be stopped by most ad blockers while attempts to connect to the same site URL will be allowed.
  • Ad blockers will not block our identification requests since they are sent to the specific path or subdomain that belongs to the same site.
  • Insight and control over the identification requests that can be combined with other Akamai features like property rules and traffic reports.
  • With the Akamai Proxy Integration, you can manage unlimited subdomains and paths and provide Fingerprint services to all your customers at any scale while benefiting from all the 1st-party integration improvements.
  • Cookie security: Akamai Proxy Integration drops all the cookies sent from the origin website. The source is open-source so this behavior can be transparently verified and audited.
  • Easy to meet compliance and auditing requirements.

Integration setup overview

The integration setup consists of the following three steps. Each step is described in detail below.

  1. Issue a proxy secret in the Fingerprint dashboard.
  2. Apply Fingerprint property rules and property variables to your Terraform configuration file.
  3. Configure the Fingerprint JavaScript agent on your website.

🚧

Requirements: Terraform setup and latest rule format expected

This guide assumes you use Terraform to manage your site infrastructure on Akamai and that your site uses the latest Akamai rule format. If your Akamai property uses a different rule format or a different deployment method, please contact our support team.

Step 1: Issue a Fingerprint proxy secret

Issue a Fingerprint proxy secret to authenticate requests from your Akamai infrastructure.

  1. Go to the Fingerprint dashboard and select your workspace.
  2. In the left menu, navigate to API keys.
  3. Click Create Proxy Key.
  4. Give it a name, for example, Akamai proxy integration.
  5. Click Create API Key.

You will use the proxy secret value in the following step, so store it somewhere safe.

Step 2: Apply Fingerprint property rules and property variables

Adjust your Terraform configuration to incorporate the variable blocks, property rules, and property variables required by the integration.

Step 2.1: Add variable blocks to your rules template

🚧

Note: Rules template expected

The following section assumes you are using the Rules template to manage your Akamai property rules. If you are using a plain JSON file instead, reach out to our support team.

Specify three randomized path values and the Fingerprint proxy secret you have created in Step 1:

  • fpjs_integration_path
  • fpjs_agent_path
  • fpjs_result_path
  • fpjs_proxy_secret

For the path values, pick any random strings that are valid URL paths. Be careful not to include words often blocked by ad blockers, such as fingerprint or fpjs. You can use any random value generator or Terraform's Random Provider if you prefer.

Find the akamai_property_rules_template data block in your Terraform configuration file and add the four variables:

data "akamai_property_rules_template" "rules" {
      # Assuming this is property's rules file
      template_file = "/rules/main.json" 
      variables {
        name  = "fpjs_integration_path"
        value = "YOUR_INTEGRATION_PATH_HERE"
        type = "string"
      }
      variables {
        name  = "fpjs_agent_path"
        value = "YOUR_AGENT_PATH_HERE"
        type = "string"
      }
      variables {
        name  = "fpjs_result_path"
        value = "YOUR_RESULT_PATH_HERE"
        type = "string"
      }
      variables {
        name  = "fpjs_proxy_secret"
        value = "YOUR_PROXY_SECRET_HERE"
        type = "string"
      }
}

🚧

Notice: Upcoming changes to proxy integration authentication

  • Currently, proxied identification requests without a valid proxy secret still work, but provide a less accurate result.
  • In the future, proxied identification requests without a valid proxy secret will result in a proxy integration error and not receive identification results.

The goal of this change is to prevent a proxy integration misconfiguration from silently degrading your identification accuracy.

  • You can go to Dashboard > Integrations & SDKs > Akamai to verify that you don’t have any Proxy secret errors in your usage chart.
  • If your proxy secret is not configured correctly, follow Step 1 and Step 2.1 to fix your integration. Contact our support team if you have any questions.

Step 2.2: Add Fingerprint property rules

  1. Go to the integration's latest releases on GitHub.
  2. Download the terraform/fingerprint-property-rules.json file.
  3. Add it to your Terraform project's rules directory as fingerprint-property-rules.json.
  4. Reference the file in rules/main.json like below:
// rules/main.json
{
  "rules": {
    "name": "default",
    "behaviors": [
      // ...
    ],
    "children": [
      // ...other rule files 
      // Add the downloaded rules file 
      "#include:fingerprint-property-rules.json" 
    ],
    // ...
  }
}

Step 2.3: Add Fingerprint property variables

  1. Go to the integration's latest releases on GitHub.
  2. Download the terraform/fingerprint-property-variables.json file.
  3. Add it to your Terraform project's rules directory as fingerprint-property-variables.json.
  4. Reference the file in rules/main.json:
  • If you don't have a variables field, add the variables: "#include:fingerprint-property-variables.json" line.
  • If you already have a variables field, merge fingerprint-property-variables.json with your existing variables file.
// rules/main.json
{
  "rules": {
    "name": "default",
    "behaviors": [
      // ...
    ],
    "children": [
      //...
      "#include:fingerprint-property-rules.json" 
    ],
    // Add the downloaded variables file (or merge it with existing variables file)
    "variables": "#include:fingerprint-property-variables.json"
    // ...
  }
}

📘

Property variables vs Terraform variable blocks

Note that the Akamai property variables added in Step 2.3 are different from the Terraform variable blocks added in Step 2.1.

  • Property variables are used by property rules and you cannot change them.
  • You can change the variable block values (randomized paths and the proxy secret) according to your needs.

Step 2.4: Apply Terraform changes

  1. Run terraform plan to review your changes.
  2. Run terraform apply.

After your property deploys, you can access Fingerprint CDN and API through the chosen paths on your website.

Step 3: Configure Fingerprint Pro Agent

  1. Use the random path variables created in Step 2.1 to construct the scriptUrlPattern (agent download) and endpoint (get result) URLs.
  2. Configure the Fingerprint JS Agent on your website accordingly:
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/YOUR_INTEGRATION_PATH_HERE/YOUR_AGENT_PATH_HERE?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>',
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    'https://yourwebsite.com/YOUR_INTEGRATION_PATH_HERE/YOUR_RESULT_PATH_HERE?region=us',
    FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
  ],
});
const url = 'https://yourwebsite.com/YOUR_INTEGRATION_PATH_HERE/YOUR_AGENT_PATH_HERE?apiKey=<PUBLIC_API_KEY>';
const fpPromise = import(url)
  .then(FingerprintJS => FingerprintJS.load({
    endpoint: [
      'https://yourwebsite.com/YOUR_INTEGRATION_PATH_HERE/YOUR_RESULT_PATH_HERE?region=us',
      FingerprintJS.defaultEndpoint // Fallback to default endpoint in case of error
    ]
  }));

📘

Parameter URL nuances

  • Note that the import url for the CDN installation method and scriptUrlPattern used by NPM packages are similar but different and cannot be used interchangeably.
  • Pay attention to differences in query parameters:
    • Pass region to the endpoint parameters in the following format: ?region=eu. The value needs to reflect the region of you workspace.
    • Leave thescriptUrlParam parameter as displayed here: ?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>. The apiKey version and loaderVersion parameters will be replaced by the values in the NPM package automatically. Do not alter them manually.

If everything is configured correctly, you should receive the latest Fingerprint client-side script and the identification result through your Akamai integration. If you have any questions, reach out to our support team.

Monitoring the integration

Go to Dashboard > SDKs & integrations > Akamai to see the status of your integration. Here you can monitor:

  • If the integration is up to date.
  • How many identification requests are coming through the integration (and how many are not).
  • The error rate of proxied identification requests (caused by missing or incorrect proxy secret).

The information on the status page is cached so allow a few minutes for the latest data points to be reflected.

Updated 12 days ago