Skip to main content
https://cdn.usefoil.com/t.js always serves Foil’s latest release. If you want to decide when a new release reaches your pages, for example only after it has been public for 24 hours, load one release at its own address with its integrity hash instead, and move to newer releases from your deploy process. When you finish, your pages load one exact release of the SDK, the browser refuses any other bytes under that address, and you control when the release changes.

How releases work

Every release of the browser SDK is published at its own address, https://cdn.usefoil.com/t.<id>.js. The file at that address never changes, and Foil keeps it available at least until the release’s accepted_until time, which is at least 90 days after Foil last published the release. To pin a release, you load its address and give the browser its Subresource Integrity (SRI) hash. Foil’s API lists the releases you can pin, with their hashes.
Pin with the integrity hash, not the id in the file name. The id names the release but does not prove what the file contains; the hash does. The values on this page are examples. Always take script_url and integrity from the API.
Pages that load Foil through a first-party integration pin the same way, with the release served from your integration URL. See Pin through a first-party integration.

Before you begin

  • Create a live secret key with the sdk_releases:read scope. In the dashboard, open API Keys, select New secret key, choose Custom, select List SDK releases under SDK releases, and select Create key. A key with All scopes also works. The Recommended scopes do not include it.
  • Keep the key in your server or deploy pipeline. It is a secret key, so never send it to the browser.
  • If your site sets a Content Security Policy, the script-src source you already allow for Foil (https://cdn.usefoil.com) covers the pinned release’s file. The import map you add in Load the pinned release is an inline script, though, so your policy must allow it separately. See Content Security Policy.

List the releases you can pin

The response lists releases newest first:
The list holds every release Foil still accepts sessions from, so it is never paged. It starts with the releases published after Foil began recording integrity hashes in November 2026.

Choose a release

Pick the newest release that has been public long enough for your policy and that Foil has not rolled back. Releases come newest first, so the first match is the one you want. For a 24-hour delay:
Run this in your deploy pipeline or a scheduled job, and write release.script_url and release.integrity into your page template. Each time it runs, also check that the release you have pinned is still listed and is not rolled_back.

Load the pinned release

Replace https://cdn.usefoil.com/t.js with the release’s script_url everywhere your page loads Foil, and give the browser its integrity hash in an import map. Put the import map in the page’s <head>, before any module script runs:
Use the same address in the import map, the modulepreload link and the import() call. The rest of your integration does not change. If your Content Security Policy does not allow inline scripts, the browser blocks the import map, and the release loads without the integrity check. Allow it in one of two ways:
  • Give the import map the same nonce as your other inline scripts: <script type="importmap" nonce="your-nonce">. This keeps working when you move to a new release.
  • Add the import map’s hash to script-src, such as 'sha256-…'. The hash covers the import map’s exact text, so it changes with each release you pin, and you must update the policy each time.
A browser that supports integrity in import maps refuses to run the file if its bytes differ from the hash, so the import fails and Foil does not start. A browser without that support loads the file without the check. If you call verifyHuman(), the pinned release loads one more file from cdn.usefoil.com the first time you call it. That file is named by its own SHA-256 hash, and the import map’s integrity entry does not cover it.

Pin through a first-party integration

A first-party integration serves every release the API lists at your integration URL, with the same bytes as cdn.usefoil.com and the same integrity hash. To pin a release on pages that use the integration, build its address from your integration URL and the release’s id, <integration URL>/t.<id>.js, and use it with the release’s integrity hash. For the integration URL https://www.example.com/foil:
The SDK sends its collection requests through the integration URL it was loaded from, so you don’t need to set endpoint, and the page loads the SDK without contacting cdn.usefoil.com. The script-src source you already allow for the integration covers the pinned release’s file. The import map is still an inline script, so allow it as described in Load the pinned release. The integration’s own t.js keeps following the current release, and Redeploy and Roll back in the integration’s settings change only t.js. A pinned page keeps its release through both. Once the API stops listing a release, the integration answers 401 for its address and Foil does not start on the page, so keep your pin current as described below.

Keep your pin current

  • Move to a newer release before your pinned release’s accepted_until. After that time Foil refuses new sessions from the release with 426 transport.upgrade_required, and Foil does not start on your pages.
  • Move off a release that becomes rolled_back. Foil rolls back a release when it has a problem.
  • Move at least weekly. A pinned page does not receive Foil’s detection updates until you move it to a release that has them.

Errors

Every error response includes a request_id. Include it when you contact Foil support. See API errors.