Deploy Fastly VCL Manually

📘
Before you start: Read the general Fastly VCL guide
This document only covers deploying the Fingerprint Fastly VCL proxy integration using the Fastly web interface. It assumes you have already read the general Fastly VCL guide and completed the following steps:

Step 1: You have issued a proxy secret in the Fingerprint Dashboard (PROXY_SECRET).

Step 2: You have defined the path variables for the integration (INTEGRATION_PATH,AGENT_SCRIPT_DOWNLOAD_PATH, GET_RESULT_PATH)

If you want to use Terraform instead of the Fastly web interface to install the integration, see Deploy Fastly VCL using Terraform.

🚧
Limitations
This integration is exclusively supported for customers on the Enterprise Plan. Other customers are encouraged to use Custom subdomain setup or Cloudflare Proxy Integration.

Step 3: Deploy Fastly VCL Manually

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)

Go to Fastly > CDN Services and click Create Service in the top right.
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.
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.
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.
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 a 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.
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:
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.

📘
Note: Proxy secret required
Proxied identification requests without a valid proxy secret will result in an authentication error and not receive identification results.

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 client agent

Go back to the general Fastly VCL guide to Configure the Fingerprint client agent to use your service.