Guides
Sign Up

Fastly Compute Proxy integration

Suggest Edits

Fingerprint Fastly Compute Proxy Integration is responsible for proxying identification and agent-download requests between your website and Fingerprint through your Fastly infrastructure. Your website does not strictly need to be behind Fastly to use this proxy integration, although that is optimal for maximum accuracy benefits.

The integration is a JavaScript WebAssembly Compute Service you can deploy to your Fastly account. The source code is available on GitHub.

🚧

Limitations and expectations

Integration in Beta

This integration is currently in Beta. If you find any issues, please contact our support team.

Limited to Enterprise plan

Support for the Fastly Compute Proxy Integration is provided 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 Compute 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 Compute 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 the Fingerprint JavaScript agent from loading. Requests to Fingerprint domains are stopped by most ad blockers, but requests to same-site URLs are always allowed.
  • Ad blockers will not block Fingerprint identification requests since they are sent to a subdomain that belongs to the same site.
  • Insight and control over the identification requests that can be combined with other Fastly features like Compute and traffic reports.
  • Cookie security: Fastly Compute Proxy Integration drops all the cookies sent from the origin website. The code is open-source, so you can transparently verify this behavior.
  • 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. Deploy Fingerprint proxy integration Compute service in your Fastly account.
  4. Configure the Fingerprint client agent on your website or mobile app.

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, click API keys.
  3. Click Create Proxy Key.
  4. Give it a name, for example, Fastly Compute proxy integration.
  5. Click Create API Key.

You will use the proxy secret value in the following steps, 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.4) and the JavaScript 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:

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:

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 AGENT_SCRIPT_DOWNLOAD_PATH in this guide, you should use your random value instead.

Step 3: Deploy the proxy integration Compute service

Follow the steps below to create, configure, and deploy a Fastly Compute service for your Fingerprint proxy integration.

Step 3.1: Create a Compute Service

Create a Compute service in your Fastly account.

  1. Go to Fastly Compute services.
  2. Click Create service > Create an empty service.
  3. On the top of the page, click Options > Edit service name.
  4. Give it a name we will remember in the future, for example, fingerprint-fastly-compute-proxy-integration, and click Apply.

Step 3.2: Add a domain to the service

To get the proxy integration’s accuracy benefits, we recommend using a subdomain of the website you want to use Fingerprint on, for example, metrics.yourwebsite.com.

To avoid ad blockers, do not use subdomains like fingerprint, fpjs, and other fingerprint-related terms.

  1. Inside the service configuration left-hand menu, click Domains.
  2. Input your domain for the proxy integration, for example, metrics.yourwebsite.com.
  3. Click Add to save changes.

📘

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 Compute 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.3: Configure the service backends in Fastly

You need to add at least two backends to your Fastly service — Fingerprint CDN and the Fingerprint API.

Fingerprint API is available in three different regions: api.fpjs.io (Global), eu.api.fpjs.io (EU), and ap.api.fpjs.io (Asia). Use the right regional hostname depending on your Fingerprint workspace data region.

  1. Go back to Compute services and open the configuration of your service.
  2. Inside the service configuration left-hand menu, click Origins.
  3. First, create the Fingerprint CDN host. Under Hosts, type fpcdn.io, and click Add.
  4. Click Edit on the previously created host.
    1. Change its name to fpcdn.io. Use the hostname exactly, the hostnames are hard-coded in the service code.
    2. Scroll down and set Override host to fpcdn.io.
    3. Click Update to save changes.
  5. Second, create the Fingerprint API host. Click Create a host, type api.fpjs.io (or a regional equivalent), and click Add.
  6. Click Edit on the previously created host.
    • Change its name to api.fpjs.io (or a regional equivalent). Use the hostname exactly, the hostnames are hard-coded in the service code.
    • Scroll down and set Override host to api.fpjs.io (or a regional equivalent).
    • Click Update to save changes.

Step 3.4: Add a config store to the service

Provide the proxy secret and your chosen resource paths to the service.

  1. In Fastly, navigate to Resources > Config stores.
  2. Click Create a config store.
  3. Name the config store Fingerprint_Compute_Config_Store_<SERVICE_ID>, where the suffix is your proxy integration's Compute Service ID. Make sure you don't have any spaces in the Config store name after copy-pasting your service ID.
  4. Click Add.
  5. Click Link to services and select fingerprint-fastly-compute-proxy-integration.
  6. Click Next, select the current (draft) version of your service, and click Link only.
  7. Click Finish.
  8. Find your new config store and click Key-value pairs to add the following values:
    1. Set AGENT_SCRIPT_DOWNLOAD_PATH to your chosen agent download path. It should be something random to avoid ad blockers, for example, 463n7-d0wnl04d.
    2. Set GET_RESULT_PATH to your chosen identification result path. It should be something random to avoid ad blockers, for example, 1d3n71f1c4710n-r35ul7.

Step 3.5: Add a secret store to the service

  1. In Fastly, navigaet to Resources > Secret stores.
  2. Click Create a secret store.
  3. Name the config store Fingerprint_Compute_Secret_Store_<SERVICE_ID>, where the suffix is your proxy integration's Compute Service ID. Make sure you don't have any spaces in the Secret store name after copy-pasting your service ID.
  4. Click Add.
  5. Click Link to services and select fingerprint-fastly-compute-proxy-integration.
  6. Click Next, select the current (draft) version of your service, and click Link only.
  7. Click Finish.
  8. Find your new Secret store and click Key-value pairs.
  9. Click Add item and set PROXY_SECRET to the proxy secret value you generated in Step 1.

Step 3.6: Deploy the proxy package and activate your service

Deploy the proxy service code to your Fastly Compute Service.

  1. Go to the latest release in the Fastly Compute Proxy Integration GitHub Repository.
  2. Download fingerprint-fastly-compute-proxy-integration.tar.gz to your computer.
  3. Inside Fastly, navigate to Compute > Compute services, open your proxy integration service, and switch to the Service configuration tab.
  4. In the left-hand menu, click Package.
  5. Upload the fingerprint-fastly-compute-proxy-integration.tar.gz package.
  6. Click Activate in the top right corner of the page (if you see Validating instead, wait for it to complete).

Wait a couple of minutes for the activation. You can go to metrics.yourwebsite.com/status to verify that your integration is running.

Step 3.7: Issue a TLS certificate for your subdomain

  1. Inside the Fastly Dashboard, navigate to Security > TLS Management > Domains.
  2. Click Secure domain or Secure another domain.
  3. Select Use certificates Fastly obtains for you.
  4. Enter your domain (for example metrics.yourwebsite.com) and click Add.
  5. Configure Certification Authority and TLS configuration according to your needs and click Submit.
  6. 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. Once verified, Fastly will issue a certificate for your domain and display a green Issued status.

Step 3.8: Point your subdomain to Fastly

Once your domain is verified and active, you need to choose the right hostname for your DNS record.

  1. Go to Security > TLS Management > Domains.
  2. Find your domain and under TLS configuration and DNS details, click View/Edit.
  3. The CNAME records section contains the value for your CNAME record, for example, t.sni.global.fastly.net.
  4. 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 4: Configure the Fingerprint client agent to use your service

  1. Use the path variables created in Step 2 to construct the script download and identification endpoint URLs.
  2. Configure the Fingerprint client agent on your website or mobile app accordingly:
// The same pattern applies to React SDK, Vue SDK, etc.
import * as FingerprintJS from "@fingerprintjs/fingerprintjs-pro";

const fpPromise = FingerprintJS.load({
  apiKey: PUBLIC_API_KEY,
  scriptUrlPattern: [
    "https://metrics.yourwebsite.com/AGENT_SCRIPT_DOWNLOAD_PATH?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>",
    FingerprintJS.defaultScriptUrlPattern, // Fallback to default CDN in case of error
  ],
  endpoint: [
    "https://metrics.yourwebsite.com/GET_RESULT_PATH?region=us",
    FingerprintJS.defaultEndpoint, // Fallback to default endpoint in case of error
  ],
});

const fpPromise = import(
  "https://metrics.yourwebsite.com/AGENT_SCRIPT_DOWNLOAD_PATH?apiKey=PUBLIC_API_KEY"
).then((FingerprintJS) =>
  FingerprintJS.load({
    endpoint: [
      "https://metrics.yourwebsite.com/GET_RESULT_PATH?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 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 Compute proxy integration.

Monitoring and troubleshooting the integration

You can go to the integration's status page at /status (for example https://metrics.yourwebsite.com/status) to check that the integration is running and all required configuration variables have been set correctly.

Inside your Fingerprint Dashboard, go to App Settings > Integrations > Fastly Compute to see the usage metrics 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 have any questions, reach out to our support team.

Fastly logging

If your integration isn't working as expected, it can be useful to look at the Fastly Compute service logs. Fastly offers a variety of logging options and integrations.

For simple debugging purposes, we recommend using Fastly log-tail:

  1. Install and configure the Fastly CLI on your machine.
  2. Run fastly log-tail --service-id <SERVICE_ID> to see a stream of log messages from the integration Compute service.

Keeping your integration up to date

The Fastly Compute proxy integration does not have automatic updates. To keep your integration up to date, you can periodically check the Releases on GitHub and deploy a new service package if necessary.

If there is a new major version or another reason you need to update your integration, our support team will get in touch with you.

Cost Calculation

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

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

For more details on limitations affecting your setup see Compute resource limits.

Using Open client response

Enabling Open client response for your Fingerprint workspace allows you to access the full deobfuscated device intelligence result in your proxy integration. This lowers latency and increases the security of your Fingerprint implementation.

Updated 9 days ago