Guides
Sign Up

Fastly VCL Proxy Integration

Suggest Edits

Fingerprint Fastly VCL (Varnish Configuration Language) Proxy Integration is responsible for proxying identification and agent-download requests between your website and Fingerprint through your Fastly infrastructure. The integration consists of a set of VCL rules you can add to your Fastly CDN Service. The VCL template is available on GitHub.

🚧

Limitations and expectations

Limited to Enterprise plan

Support for the Fastly VCL Proxy Integration is supported only for 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 Fastly VCL 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 Fastly VCL 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, but 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 Fastly features like VCL and traffic reports.
  • With the Fastly VCL 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: Fastly VCL Proxy Integration drops all the cookies sent from the origin website. The code 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. Create integration path variables.
  3. Apply Fingerprint VCL and configuration values to your Fastly CDN Service.
  4. Configure the Fingerprint JavaScript agent on your website.

Step 1: Create a Fingerprint proxy secret

Issue a Fingerprint proxy secret to authenticate requests from your Fastly 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, Fastly VCL proxy integration.
  5. Click Create API Key.

You will use the proxy secret value in Step 3.1, so store it somewhere safe.

Step 2: Create path variables

You need to set the path variables you will use throughout your Fastly configuration (Step 3.1) and the JS agent configuration on your website (Step 4). These values are arbitrary. Just decide what your values are and write them down somewhere.

In this guide, we will use readable values corresponding to the variable names to make it easier to follow: 

INTEGRATION_PATH="INTEGRATION_PATH"
AGENT_SCRIPT_DOWNLOAD_PATH="AGENT_SCRIPT_DOWNLOAD_PATH"
GET_RESULT_PATH="GET_RESULT_PATH"

However, your values used in production should look more like random strings: 

INTEGRATION_PATH="ore54guier"
AGENT_SCRIPT_DOWNLOAD_PATH="vbcnkxb654"
GET_RESULT_PATH="5yt489hgfj"

That is because some adblockers might automatically block requests from any URL containing fingerprint-related terms like "fingerprint", "fpjs", "track", etc. Random strings are the safest. So whenever you see a value like INTEGRATION_PATH in this guide, you should use your random value instead.

Step 3: Add Fingerprint VCL to your Fastly CDN Service

The recommended setup is to add the VCL template to your existing Fastly CDN Service serving your website. If your website is running on Fastly CDN, skip to Step 3.1.

If your website is not running on Fastly, you can still use the Fastly proxy integration by creating a dedicated Fastly CDN Service for it and hosting it on the subdomain of your website. If so, please follow Step 3.0 to create a new Fastly CDN Service.

📘

Safari accuracy on non-Fastly websites

For maximum accuracy, both your website and your proxy integration should be served by Fastly.

You can use the Fastly VCL proxy integration even if your website is not served by Fastly, but this setup will likely limit Safari cookie lifetime to 7 days, resulting in lower accuracy. Because your website and the proxy integration will likely have different IP ranges, Safari will apply the same cookie lifetime cap as for third-party CNAME cloaking. This is still an improvement over third-party cookies getting blocked entirely by Safari.

Step 3.0 Create a new Fastly CDN Service (if required)

  1. Go to Fastly > CDN Services and click Create Service in the top right.
  2. Fill in the form:
    1. Set Name to something descriptive, for example: Fingerprint Proxy Integration.
    2. Set Domain to the subdomain you have chosen for the integration, for example metrics.yourwebsite.com. Avoid terms commonly blocked by ad blockers like fingerprint, fpjs, etc.
    3. Set Origin to something like metrics-origin.yourwebsite.com. This origin does not need to exist because the VCL template will forward all valid requests to the appropriate Fingerprint servers.
    4. If your website needs to be accessible on HTTP (not just HTTPS), disable Force TLS & HSTS.
  3. Click Activate.
  4. Using the left-hand menu, go to Security > TLS Management > Domains.
  5. Click Secure my domain and pick Use certificates Fastly obtains for you.
  6. Enter your domain (for example, metrics.yourwebsite.com and click Add.
  7. Keep the default settings and click Submit.
  8. Follow the instructions on the screen to verify ownership of your domain. This usually involves creating a CNAME DNS record on your domain like _acme-challenge.metrics.yourwebsite.com. Give Fastly some time to verify the DNS record. After verification is completed, Fastly will issue a certificate for your domain and display a green Active status.
  9. Once your domain is verified and active, you need to choose the right hostname for your DNS record.
    1. Your hostname is likely TLS-enabled so you can go to Security > TLS Management > Domains.
    2. Find your domain and click View details.
    3. The CNAME records section contains the value for your CNAME record, for example: t.sni.global.fastly.net.
  10. Add a subdomain CNAME record to your domain's DNS and point it to the Fastly hostname from the previous step. For example: 
    metrics.yourwebsite.com.    3600    CNAME    t.sni.global.fastly.net.

Step 3.1: Create Dictionary for your CDN Service

In this step, you are going to create a dictionary for your CDN Service and use it to store the configuration of your proxy integration.

  1. Navigate to CDN > CDN Services and find your CDN service.
  2. If you don't have an editable version of your service, click Edit Configuration > Clone version to edit
  3. Using the left-hand Service menu, navigate to Data > Dictionaries.
  4. Click Create Dictionary.
  5. Set the name to fingerprint_config and click Add. The default VCL template relies on this exact name.
  6. Click Add Item to add the following key-value pairs:
    1. Set PROXY_SECRET to the proxy secret you created in the Fingerprint Dashboard in Step 1.
    2. Set INTEGRATION_PATH to the random string you defined in Step 2.
    3. Set AGENT_SCRIPT_DOWNLOAD_PATH to the random string you defined in Step 2.
    4. Set GET_RESULT_PATH to the random string you defined in Step 2.

🚧

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 > Fastly VCL 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 3.1 to fix your integration. Contact our support team if you have any questions.

Step 3.2: Download Fastly VCL Template

Go to the latest integration release on GitHub, and download the artifact named fingerprint-pro-fastly-vcl-integration.vcl.

Step 3.3: Upload VCL Template

  1. Using the left-hand Service menu, navigate to Custom VCL and click Upload VCL file.
  2. Set a name that suits you, for example fingerprint_proxy_integration.
  3. Upload the fingerprint-pro-fastly-vcl-integration.vcl file that you've downloaded in the previous step.
  4. Click Create.

Step 3.4: Activate your version and verify your setup

  1. Scroll up to the Service version toolbar and click Activate to deploy your changes.
  2. Go to https://yourwebsite.com/INTEGRATION_PATH/status. You should see an integration status page showing the template version and a checklist of the set dictionary variables.

Step 4: Configure the Fingerprint JavaScript agent on your client

Use the path variables created in Step 2 to construct the script download and identification endpoint URLs.

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_INTTEGRATION_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',
      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 application.
    • Leave the scriptUrlParam 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 Fastly VCL integration. If you have any questions, reach out to our support team.

Monitoring and troubleshooting the integration

Go to Dashboard > SDKs & integrations > Fastly VCL 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.

If you run into problems:

  1. Go to the integration's status page at https://yourwebsite.com/INTEGRATION_PATH/status to check if the integration is running and all required configuration variables have been set correctly.
  2. When contacting our support team, please provide them with the VCL file of your CDN service.
    1. Navigate to CDN > CDN Services, open your CDN service, and pick the Active version.
    2. Click Show VCL and then Download.

Cost Calculation

The resources required by the proxy integration fit within the Fastly Free Tier:

  • The integration uses 4 out of the 5 available Origins per CDN Service.
  • The integration uses 4 out of the 1000 available Dictionary Items.
  • By default, the integration uses 200 out of the 1000 theoretically available connections per CDN service. Please contact our support team if you need to configure this value.

For more details and other limitations affecting your setup, please see Fastly Network services resource limits.

Updated 1 day ago