> ## Documentation Index
> Fetch the complete documentation index at: https://usefoil.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Choose a deployment

> Set up a Foil first-party integration on Cloudflare, AWS CloudFront, your own Cloudflare Worker, or an edge you run yourself, from creating the integration to loading the SDK.

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:

| | Cloudflare, deployed by Foil | AWS CloudFront, deployed by Foil |
| - | - | - |
| What Foil deploys | A Worker and a Worker route in your zone | A Lambda\@Edge function and cache behaviors for Foil's routes on your distribution |
| What Foil needs from you | A Cloudflare API token scoped to the site | A deployment role and a Lambda execution role in your AWS account |
| Ownership DNS record | Foil can write it with a token that has **DNS Edit** | You publish it |
| Step 3 on the integration page | **Install integration** | **Install integration** |
| When the proxy credential rotates | Foil deploys the new credential | Foil deploys the new credential |
| When the edge adapter changes | Foil redeploys the edge | Foil redeploys the edge |
| Domains when serving every domain | Every hostname in the zone | Every alternate domain name on the distribution |

When you run the edge, Foil needs no access to your CDN and deploys nothing; you keep the edge up to date:

| | Cloudflare, your Worker | Custom proxy |
| - | - | - |
| What you deploy | A module Foil generates, called from a Worker you already run | The edge contract, on your own CDN or proxy |
| What Foil needs from you | Nothing | Nothing |
| Ownership DNS record | You publish it | You publish it |
| Step 3 on the integration page | **Start accepting traffic** | **Start accepting traffic** |
| When the proxy credential rotates | You update the Worker secret | You deploy the new credential |
| When the edge adapter changes | You copy the updated module from the integration page | You update your edge |
| Domains when serving every domain | Every domain your Worker routes to the integration path | Every domain your edge routes to the integration path |

Deploying on AWS CloudFront with your own Terraform is coming soon. See [AWS CloudFront with your Terraform](#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](https://usefoil.com/docs/first-party/multiple-domains.md).
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:

| Step | What you do |
| - | - |
| 1. Add the DNS record | Publish the ownership TXT record. See [Add the DNS record](#add-the-dns-record). |
| 2. Deploy the edge | Give Foil what it needs to deploy the edge, or deploy it yourself. The step's title names your deployment: **Connect Cloudflare**, **Add Foil to your Worker**, **Set up the AWS roles**, or **Deploy your edge**. The following sections describe it for each deployment. |
| 3. Install integration, or Start accepting traffic | Foil deploys the edge, or starts accepting requests from an edge you run, and runs the checks. |
| 4. Add Foil to your pages | Check the publishable key's allowed origins, update your Content Security Policy, and copy the install snippet. See [Add Foil to your pages](#add-foil-to-your-pages). |
| 5. Verify | Confirm the three checks pass. See [Verify the integration](#verify-the-integration). |

Below the checklist, the **Manage** area holds the settings you change after setup. See [Manage an integration](https://usefoil.com/docs/first-party/manage.md).

## Add the DNS record

Step 1 lists a TXT record that proves you control the integration URL's hostname:

| Type | Name | Value |
| - | - | - |
| `TXT` | `_foil.<integration hostname>`, for example `_foil.www.example.com` | `foil-verification=` followed by a token unique to the integration |

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](#cloudflare-with-your-worker) instead.
* An API token with these permissions, scoped to the account and the site's zone:

| Scope | Permission | Why |
| - | - | - |
| Account | **Workers Scripts: Edit** | Upload the Worker |
| Zone | **Workers Routes: Edit** | Create the Worker route |
| Zone | **Zone: Read** | Find the zone and confirm the hostname belongs to it |
| Zone | **DNS: Edit** (optional) | Write the ownership TXT record for you |

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](https://usefoil.com/docs/first-party/checks.md).
8. Continue with [Add Foil to your pages](#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](https://usefoil.com/docs/first-party/edge-contract.md#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](https://usefoil.com/docs/first-party/checks.md).
5. Continue with [Add Foil to your pages](#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.

> [!WARNING]
>
> 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](#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](#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](https://usefoil.com/docs/first-party/edge-contract.md): 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](https://usefoil.com/docs/first-party/checks.md).
5. Continue with [Add Foil to your pages](#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](https://usefoil.com/docs/content-security-policy.md#first-party-integrations).
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:

```html theme={"dark"}
<link rel="modulepreload" href="/foil/t.js" crossorigin>
<script type="module">
  const endpoint = location.origin + "/foil";
  const foil = await import(endpoint + "/t.js").then((Foil) =>
    Foil.start({
      publishableKey: "pk_live_your_publishable_key",
      endpoint,
    }),
  );
</script>
```

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](https://usefoil.com/docs/first-party/overview.md#load-the-sdk-from-your-domain).

## Verify the integration

1. Request the SDK through the integration URL:

   ```bash theme={"dark"}
   curl -sS -o /dev/null -D - https://www.example.com/foil/t.js
   ```

   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](https://usefoil.com/docs/first-party/checks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.