Fastly VCL Proxy Integration
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.
![](https://files.readme.io/bd86812-fastly-integration-diagram.png)
Limitations and expectations
Limited to Enterprise planSupport 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 requiredThe 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.
- Issue a proxy secret in the Fingerprint dashboard.
- Create integration path variables.
- Apply Fingerprint VCL and configuration values to your Fastly CDN Service.
- 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.
- Go to the Fingerprint dashboard and select your application.
- In the left menu, navigate to App settings > API keys.
- Click Create Proxy Key.
- Give it a name, for example,
Fastly VCL proxy integration
. - Click Create API Key.
You will use the proxy secret value in the following step, 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 that is the case, please follow Step 3.0 to create a new Fastly CDN Service.
Safari accuracy of subdomain proxy integrations
For maximum accuracy, it is reccomended to serve your proxy integration from a path of your main domain like
yourwebsite.com/metrics
. This will allow Safari to store identificatrion cookies for up to one year.If this is not an option, you can serve the proxy integration from a subdomain of your website like
metrics.yourwebsite.com
The subdomain setup limits Safari cookie lifetime to 7 days. Because your website and the proxy function 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)
- Go to Fastly > CDN Services and click Create Service in the top right.
- Fill in the form:
- Set Name to something descriptive, for example:
Fingerprint Proxy Integration
. - Set Domain to the subdomain you have chosen for the integration, for example
metrics.yourwebsite.com
. Avoid terms commonly blocked by ad blockers likefingerprint
,fpjs
, etc. - 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. - If your website needs to be accessible on HTTP (not just HTTPS), disable Force TLS & HSTS.
- Set Name to something descriptive, for example:
- Click Activate.
- Using the left-hand menu, go to Security > TLS Management > Domains.
- Click Secure my domain and pick Use certificates Fastly obtains for you.
- Enter your domain (for example,
metrics.yourwebsite.com
and click Add. - Keep the default settings and click Submit.
- 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. - Once your domain is verified and active, you need to choose the right hostname for your DNS record.
- Your hostname is likely TLS-enabled so you can go to Security > TLS Management > Domains.
- Find your domain and click View details.
- The CNAME records section contains the value for your CNAME record, for example:
t.sni.global.fastly.net
.
- 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.
- Navigate to CDN > CDN Services and find your CDN service.
- If you don't have an editable version of your service, click Edit Configuration > Clone version to edit
- Using the left-hand Service menu, navigate to Data > Dictionaries.
- Click Create Dictionary a
- Set the name to
fingerprint_config
and click Add. The default VCL template relies on this exact name. - Click Add Item to add the following key-value pairs:
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
- Using the left-hand Service menu, navigate to Custom VCL and click Upload VCL file.
- Set a name that suits you, for example
fingerprint_proxy_integration
. - Upload the
fingerprint-pro-fastly-vcl-integration.vcl
file that you've downloaded in the previous step. - Click Create.
Step 3.4: Activate your version and verify your setup
- Scroll up to the Service version toolbar and click Activate to deploy your changes.
- 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 andscriptUrlPattern
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>
. TheapiKey
version
andloaderVersion
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.
Troubleshooting
If you run into problems:
- 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. - When contacting our support team, please provide them with the VCL file of your CDN service.
- Navigate to CDN > CDN Services, open your CDN service, and pick the Active version.
- 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 12 days ago