Cloudflare

This integration is currently in beta. Client agent 2.5.1 or later required.

Why

With cloudflare workers and our integration you can greatly increase your Safari identification accuracy rates.

The main reason why an integration with Cloudflare is required is Safari Intelligent Tracking Prevention (ITP). ITP was first introduced in 2017, when Safari 11 was released. The goal of ITP is to prevent cross-site tracking by placing limitations on cookies and other website data.

Since 2017, Apple has released several updates to ITP, the latest version being ITP 2.3. ITP has been very effective in preventing cross-site tracking by disabling 3rd-party cookies completely and capping the lifetime of all script-writeable website data. Script-writeable website data include cookies, set with document.cookie and local storage. The lifetime of the script-writeable data is limited to seven days by default, but can be further reduced to 24 hours if ITP detects that the client-side cookie was set by a tracking domain code. Apple specifically recommended website owners to use Secure, HttpOnly cookies, because they are not affected by the lifetime cap. The reason why Apple cannot limit the lifetime of Secure, HttpOnly cookies is because these cookies are used for authentication (log-in).

Because Fingerprint.js PRO uses 3rd-party (Secure, HttpOnly) cookies and client-side cookies (set with document.cookie ), the cookie-based identification was limited to 7 days in Safari. After cookie expiration, the identification had to rely only on fingerprinting, which is less accurate in Safari browsers. For this reason we created the integration with Cloudflare, that sets 1st-party, Secure and HttpOnly cookies that are not affected by ITP. This extends the cookie-based identification up to 1 year.

Who should use it?

If you're using Cloudflare, you should use this integration, because it significantly increases the identification accuracy in Safari browsers. This is particularly important on iPhones, as manual cookie clearing is uncommon on mobile devices, but ITP-based lifetime capping is prevalent. After implementing this integration, you should observe significantly better identification rates in both desktop and mobile Safari.

Even if you are not using Cloudflare, the benefits this integration provides alone should make you want to start using Cloudflare with your website.

How it works

It works by designating a path on your website that is processed by a Cloudflare worker. Note that only this particular path is processed by the worker, the rest of your website is not affected. Cloudflare worker code is 100% open-source and fully open for review. The worker code is hosted on GitHub.

As an example, you can create a worker, that's assigned to yourwebsite.com/metrics path. All HTTP requests, sent to /metrics, will be passed through the worker. Worker code will call the Fingerprint.js PRO API and set a 1st-party cookie (Secure and HttpOnly) with the VisitorID from the API response. This will guarantee, that the cookie value is not affected by ITP and can be used for identification safely for a period of up to 1 year. All subsequent requests to /metrics will have the cookie attached, which will be read by the worker and passed along to the Fingerprint.js PRO API for identification.

Installation (command line)

This command-line guide will use the official Cloudflare Wrangler CLI.

Start by cloning the project from GitHub:

git clone git@github.com:fpjspro/cloudflare-worker.git

Go into the cloned project directory: cd cloudflare-worker

Copy the wrangler.toml.example to wrangler.toml

cp wrangler.toml.example wrangler.toml

wrangler.toml is a file that contains all worker settings.

Now you need to replace some values in wrangler.toml

  • name the name of the worker. Give it a clear and descriptive name, e.g. fpjs-metrics

  • account_id use your cloudflare account ID, it can be found in your dashboard.

  • zone_id use your cloudflare zone ID, it can be found in your dashboard.

  • workers_dev set to true if you want to have a development version of the worker.

  • [env.production] route replace example.com and /metrics with your website and the route that you want to use. You can use any route name, /metrics is a good default value.

Now that you have configured the worker in wrangler.toml, you need to authenticate with Cloudflare. Head to the API tokens page in your Cloudflare dashboard and create a new token using Edit Cloudflare Workers template.

Grab the token that you just generated and authenticate wrangler with it:

wrangler config
Enter API token:

Now you're ready to publish your worker:

wrangler publish --env production

You can now go to your Cloudflare dashboard (workers tab) and see your worker successfully registered. All the traffic that goes to /metrics from the Fingerprint.js PRO agent, will be routed to the Fingerprint.js PRO API by the worker code.

JavaScript agent configuration

The last step is to change your JavaScript agent configuration. You need to specify the new route that you just registered with the worker. For CDN version, add a new endpoint configuration parameter:

<script>
window.fpLayer = window.fpLayer || [];
function fp() { fpLayer.push(arguments); }
fp('config', 'client', 'your-token');
fp('config', 'endpoint', '/metrics');
</script>
<script async src="https://cdn.fpjs.io/@2.5.1/fp.js"></script>

For NPM version, specify the endpoint parameter:

let fp = await FP.load({ client: "client-token", endpoint: "/metrics" });

That's all you need to do to implement the Cloudflare integration. After that the requests to your new endpoint will return a __cflvid cookie (HTTP only and Secure), which will be helping the identification accuracy.