Skip to main content
A first-party integration needs an edge that answers Foil’s routes on your domain and forwards them to Foil. Foil can deploy that edge for you on Cloudflare or AWS CloudFront. You can also run it yourself, in a Cloudflare Worker that already serves your site or on any other CDN or reverse proxy with the Custom proxy provider.

Compare deployments

When Foil deploys the edge, it needs access to your CDN account and keeps the edge up to date for you: When you run the edge, Foil needs no access to your CDN and deploys nothing; you keep the edge up to date: Deploying on AWS CloudFront with your own Terraform is coming soon. See AWS CloudFront with your Terraform. Whichever deployment you choose, Foil keeps the integration on the current SDK release. When Foil changes the edge adapter itself, it redeploys the edges it deployed. An edge you run changes only when you change it, and the integration page’s Edge adapter field shows when a newer version is available.

Before you begin

  • An owner or admin role in your Foil organization, with Integrations enabled.
  • A hostname your CDN already serves, such as www.example.com. It must resolve publicly over HTTPS.
  • A path on that hostname your application doesn’t use, such as /foil. Foil’s routes live under it.
  • Access to publish a TXT record in the DNS zone for that hostname.
  • A publishable key in the environment you plan to use. A Test integration accepts only pk_test_* keys and a Live integration only pk_live_* keys.

Create the integration

  1. In the Foil dashboard, open Integrations and select Add integration.
  2. Under Provider, select Cloudflare, AWS CloudFront, or Custom proxy.
  3. Under Who deploys it, choose who runs the edge. For Cloudflare, choose Foil or Your Worker. For AWS CloudFront, Foil deploys the edge. A custom proxy is always yours.
  4. Select the Test or Live environment.
  5. Enter a Name. The name appears only in the dashboard, and you can rename the integration later.
  6. In Domain, enter your site’s domain without https:// or a path, for example example.com.
  7. In Subdomain, enter the subdomain your pages load from, for example www. Leave it blank to use the domain itself.
  8. In Path, enter the path Foil’s routes live under, for example foil. The preview shows the resulting Site origin and Integration URL.
  9. Leave Serve every domain routed to this integration on, unless the integration should answer only on its own hostname. You can change this later. See Serve several domains.
  10. Complete the fields for your deployment, described in the following sections.
  11. Select Create integration.
The dashboard places the integration URL on the site origin’s hostname, for example https://www.example.com/foil. An organization can have up to 10 integrations at a time, and each integration URL can belong to only one integration.

Follow the integration page

The integration page is a checklist. Work through it in order: Below the checklist, the Manage area holds the settings you change after setup. See Manage an integration.

Add the DNS record

Step 1 lists a TXT record that proves you control the integration URL’s hostname: Publish it in your DNS provider, or select Add with Cloudflare on a Cloudflare integration whose token has DNS Edit. Keep the record in place for as long as the integration exists. Foil checks it every time it runs the integration’s checks, and an integration whose record disappears stops accepting new sessions until the record returns. Foil doesn’t reserve a hostname until ownership verifies. If another Foil organization has already verified the same integration URL, verification fails and you need to contact Foil support.

Cloudflare, deployed by Foil

Foil deploys a Worker named foil-<integration ID> to your account and a Worker route in your zone. The route is <hostname>/<path>/*, or *<zone>/<path>/* when the integration serves every domain, which covers the zone’s apex and every subdomain in it. The Worker forwards Foil’s routes and returns 404 for any other request on that route.

Cloudflare requirements

  • The integration hostname is in the Cloudflare zone you select and is proxied through Cloudflare, so Worker routes run on it.
  • No existing Worker route overlaps the integration route. A route such as www.example.com/* overlaps every path on the hostname, and Foil refuses to install rather than replace it. A zone-wide integration route overlaps any route on any hostname in the zone that covers the same path. If your site already runs a Worker on the hostname, choose Your Worker instead.
  • An API token with these permissions, scoped to the account and the site’s zone:
Foil stores the token encrypted. Find websites fails when the token can see more than 500 zones, so scope the token to the site rather than to every zone in the account.

Set up Cloudflare

  1. Under Who deploys it, choose Foil.
  2. In Account and zone, choose Automatic to paste the token and select Find websites, then pick the site from Website. Choose Manual to enter the account ID and zone ID yourself and add the token after you create the integration.
  3. Optionally let Foil add the DNS records to Cloudflare for you. Foil checks each record before writing it and doesn’t overwrite a conflicting record.
  4. Select Create integration.
  5. In step 1, publish the TXT record if Foil didn’t write it.
  6. In step 2, add the Cloudflare token if you chose Manual.
  7. In step 3, select Install integration. Foil verifies the TXT record, deploys the Worker and route, and runs the checks.
  8. Continue with Add Foil to your pages.

Cloudflare, with your Worker

Choose Your Worker when a Cloudflare Worker you operate already serves the integration hostname. Foil deploys nothing to your Cloudflare account and needs no token. Instead, the integration page generates a Worker module with the integration’s values filled in, and you call it first in your Worker’s fetch handler.
  1. Under Who deploys it, choose Your Worker, then select Create integration.
  2. In step 1, publish the TXT record.
  3. In step 2, copy the Worker module, store the proxy credential as a Worker secret, call the module from your fetch handler, and deploy your Worker. See Run inside an existing Cloudflare Worker. Your Worker’s routes must cover the integration path on every hostname that should load Foil.
  4. In step 3, select Start accepting traffic. Foil installs nothing on your Worker. It verifies the TXT record, starts accepting requests from your Worker, and runs the checks.
  5. Continue with Add Foil to your pages.
Foil rejects requests from your Worker until you select Start accepting traffic, so t.js on the integration URL returns 401 before then.

AWS CloudFront, deployed by Foil

Choose this option when Terraform or another tool doesn’t manage the distribution’s configuration, because Foil edits the distribution itself. If Terraform manages the distribution, the next terraform apply removes Foil’s changes. Foil deploys a Lambda@Edge function named foil-<integration ID> in us-east-1 and adds it to your distribution through a role in your AWS account. Foil stores no AWS access keys. It assumes your deployment role for each operation, with an external ID unique to the integration. On the distribution, Foil adds:
  • An origin named foil-<integration ID> that points to api.usefoil.com over HTTPS only. The origin carries two custom headers: the proxy credential and the integration’s public configuration.
  • Cache behaviors at the top of the behavior list that send Foil’s routes to that origin through the function on origin request: <path>/v2/collect/* and <path>/t*.js when the integration URL has a path, or /v2/collect/*, /t.js and /t.*.js when it’s the site root, so your own scripts keep their behaviors.
Foil never uses the default behavior, and it refuses to install when an existing behavior overlaps its path patterns. CloudFront matches cache behaviors on path alone, so two integrations on one distribution need different paths, and requests for the integration path on every alternate domain name of the distribution reach the integration. When the integration serves every domain, the Origin fallback is the domain each request arrived on. Otherwise, it’s the integration’s site origin for all of them.
The proxy credential is stored in the distribution’s origin configuration. Limit cloudfront:GetDistributionConfig in your account to the people and systems that need it.

CloudFront requirements

  • The integration hostname is an alternate domain name on the distribution.
  • A deployment role that Foil assumes. Step 2 of the integration page shows the integration’s external ID and two policy templates with it filled in, ready to copy:
    • A trust policy that lets Foil’s AWS principal assume the role only with the external ID. Its Principal is Foil’s AWS principal, which you get from Foil.
    • A permissions policy that lets the role update the selected distribution, manage the integration’s Lambda@Edge function in us-east-1, pass the execution role to it, and replicate it to edge locations.
  • A Lambda execution role that trusts lambda.amazonaws.com and edgelambda.amazonaws.com and grants only CloudWatch Logs permissions.

Set up CloudFront

  1. Create the Lambda execution role and a deployment role in your AWS account. The form asks for both ARNs. You replace the deployment role’s policies in step 2, once the integration has an external ID.
  2. Under Who deploys it, choose Foil.
  3. Enter the Distribution ID, Deployment role ARN, and Lambda execution role ARN.
  4. Select Create integration.
  5. In step 1, publish the TXT record.
  6. In step 2, copy the trust policy and the permissions policy, and apply them to the deployment role.
  7. In step 3, select Install integration. Foil verifies the TXT record, publishes the function, and updates the distribution. CloudFront takes several minutes to propagate the change, and Foil keeps retrying the checks until the distribution is deployed.
  8. Continue with Add Foil to your pages.

AWS CloudFront with your Terraform

Deploying Foil’s edge with a Terraform module, on a CloudFront distribution you already manage with Terraform, is coming soon. Until it’s available, the create form offers only Foil under Who deploys it for CloudFront and notes that your own Terraform is coming soon. If Terraform manages your distribution today, run the edge as a Custom proxy on the distribution, or contact Foil.

Custom proxy

Foil deploys nothing for a custom integration. You run the edge on your own CDN, load balancer, or reverse proxy and implement the custom edge contract: forward Foil’s routes to api.usefoil.com, forward only the allowlisted headers, and add the proxy credential, integration ID, and visitor IP.
  1. Select Create integration.
  2. In step 1, publish the TXT record.
  3. In step 2, select Reveal proxy config. The dashboard shows the Integration ID, Forward to, Integration URL, Site origin, Credential, and Edge adapter version. Deploy your edge with those values.
  4. In step 3, select Start accepting traffic. Foil installs nothing on your CDN. It verifies the TXT record, starts accepting requests from your edge, and runs the checks.
  5. Continue with Add Foil to your pages.
Foil rejects requests from your edge until you select Start accepting traffic, so t.js on the integration URL returns 401 before then.

Add Foil to your pages

Step 4 of the integration page takes you through three things in order:
  1. Pick a publishable key in the integration’s environment. The page shows whether the key’s allowed origins cover the site origin, or the https://*.<domain> wildcard when the integration serves every domain. If they don’t, select Add to allowed origins. To allow domains outside that wildcard, edit the key under API Keys.
  2. If your site sets a Content Security Policy, add the script-src and connect-src lines the page shows next to the install snippet. The snippet is an inline module script, so the policy must also allow it. See Content Security Policy.
  3. Copy the install snippet into the <head> of each page that should load Foil through the integration. It uses the value of the key you picked.
When the integration serves every domain, the snippet builds the integration URL from the page’s own origin, and its modulepreload link uses the path alone:
When the integration answers only on its own hostname, the snippet imports t.js from the integration URL and passes that URL as endpoint. See Load the SDK from your domain.

Verify the integration

  1. Request the SDK through the integration URL:
    The response has status 200 and no Set-Cookie header.
  2. Load a page that runs the install snippet, then reload it once.
  3. In step 5 of the integration page, confirm that Domain verified, SDK loading, and Secure cookie round-trip pass. The integration moves to Active the next time the checks run. Select Re-check setup to run them right away.
If a check fails, see Checks and troubleshooting.