# Install with Cloudflare

Connect Cloudflare from the dashboard and Telltale publishes a managed Cloudflare Zaraz installation for exact hostnames, without changing your application code.

## Before you start

- A Site whose website addresses include each HTTPS hostname you want (Settings › Channels › Website addresses).
- A workspace owner or admin in Telltale.
- A Cloudflare identity with access to the zone, Zaraz automatic script injection enabled, and a proxied A, AAAA or CNAME record for each hostname. Wildcard-only DNS is not eligible.
- An HTTPS collector origin. The server must be configured with Cloudflare OAuth (CLOUDFLARE_CLIENT_ID and CLOUDFLARE_CLIENT_SECRET).

Selection is exact: choosing app.example.com does not include example.com or other subdomains. Telltale does not change DNS, proxy status, Workers or firewall settings.

## Install and publish

1. In Settings › Channels, open Advanced and choose Connect Cloudflare, authorize, then select the connection for this workspace.
2. Choose the zone. Eligible hostnames are listed with the reason any hostname is not selectable. A hostname that another Site's Zaraz installation already targets is shown as unavailable ("Already installed for the Site …"; another workspace's Site is not named) and a preview that includes it is refused, because two loaders on one page would report every visit under two Site keys. Remove that installation first.
3. Preview the installation. The preview shows the exact entries that will be added (a custom HTML tool, a page-load trigger, and identify and reset triggers) and expires after five minutes.
4. Apply. The installer stages the reviewed change, publishes it and reads the published configuration back. Installed and verified means the published configuration matches; it does not mean a browser has loaded the script yet.
5. Open one of the selected hostnames in another tab. Settings › Channels changes from Waiting for the first session to Activity received when the Telltale server receives the first events from a Zaraz-started session on that hostname (initialization alone does not count; sessions started by another installer are listed separately).

Repeat for another zone. Editing a zone's hostnames replaces only Telltale's own entries after a new preview.

## Collection mode

The managed Zaraz installation starts collection automatically on the selected hostnames. It respects a refusal the SDK has already saved on that browser, but it does not synchronize with a consent manager. If your deployment needs consent-controlled collection, remove the Zaraz installation (Remove, then apply the removal preview) and use the direct held SDK with the Consent bridge, or Google Tag Manager with Let my CMP control collection. Never run both for the same Site.

## Content Security Policy

The managed installation is a Zaraz custom HTML tool, which needs Zaraz's execute_unsafe_scripts permission: Zaraz inserts the loader script into the page, and the loader then adds the Telltale server's /sdk.js. That only works when your policy trusts scripts inserted by Zaraz:

- Strict nonce policy: your policy must use 'strict-dynamic' and Zaraz's own injected script must carry your per-response nonce (check Cloudflare's current Zaraz CSP guidance for your plan). Scripts that a trusted script inserts are then allowed. connect-src must still list the collector origin.
- Host allowlist without 'strict-dynamic': the inline loader is blocked. Do not add 'unsafe-inline' or 'unsafe-eval' to make it work. Use the direct installation instead: load /sdk.js from your collector origin and initialize from a same-origin file, as in the [Content Security Policy guide](/docs/csp).

When a policy blocks the loader, nothing is collected and Settings › Channels keeps showing Waiting for the first session. Compatibility of the managed installation with a strict CSP has not been verified against live Cloudflare delivery; test with Content-Security-Policy-Report-Only first.

## Identify signed-in users

Identity is optional. After the SDK has initialized (window.Telltale?.getClient() succeeds), send stable internal IDs through Zaraz. The event names `'observatory.identify'` and `'observatory.reset'` are historical names, stable and kept on purpose so existing installs keep working ([Renamed names](/docs/sdk#renamed-names)); use them exactly as shown:

```javascript
await zaraz.track('observatory.identify', { userId: 'usr_123', accountId: null });
// On logout or account switch, before someone else uses the page:
await zaraz.track('observatory.reset');
```

These IDs are browser-supplied labels, not verified identity, and pass through Cloudflare: never send tokens, secrets or personal data you are not allowed to share.

You can send these events before the SDK has loaded. Each identify or reset event waits in page memory, in order, and is applied as soon as the managed installation has initialized the SDK on that page. At most 20 events wait; when more arrive, the oldest are dropped. Nothing is stored or sent while they wait. A queued identity is applied only if collection is allowed at that moment: when the browser has a saved refusal, or collection is withdrawn, queued events are discarded, not kept for later, and nothing is identified before collection is permitted. The queue lasts only for the page, so send identity again after a full navigation. For ordering-critical changes, you can also await the client directly: await client.reset() and then await client.identify(...). Use POST /api/v1/identify from your backend for server-verified identity.

## Use the client for protected actions

```javascript
const client = window.Telltale.getClient();
const sessionToken = await client.getSessionToken();
```

Send the token only to your own backend with the protected request, and verify it there (Quickstart). getClient() throws when the page has no initialized client or more than one; keep the result of init() in that case.

## Change or remove

- Change hostnames: choose the zone again, update the selection, preview and apply.
- Remove: preview removal for the zone and apply it. Only Telltale's entries are removed; the Cloudflare connection stays.

## Detach, remove or revoke the Cloudflare connection

None of these touches the published Zaraz configuration. Installed loaders keep running and collecting on their hostnames until you remove the installation (Remove, then apply the removal preview) while a working connection is selected.

| Action | Where | What changes | Installed scripts | To manage installations again |
| --- | --- | --- | --- | --- |
| Detach | Settings › Channels, Cloudflare connection (owner or admin) | The workspace no longer uses that connection. The connection itself stays with its owner. | Keep running unchanged. | Select a connection again. Selecting one first checks that it can reach every zone with an installation; if it cannot, the old selection stays. |
| Remove connection | Settings › Channels, by the connection's owner only | The stored Cloudflare tokens are deleted, and every workspace that had selected the connection is detached. | Keep running unchanged. | Connect Cloudflare again (or select another connection), then select it. |
| Revoke at Cloudflare | Your Cloudflare profile, where the authorized application can be revoked | Cloudflare stops accepting the stored tokens. Telltale marks the connection Reconnect required the next time a call or token refresh is refused. | Keep running unchanged. | Reconnect with the same Cloudflare identity, which updates the existing connection, then retry. |

To stop collection on a hostname, remove the installation before you detach, remove or revoke the connection. If the connection is already gone, delete Telltale's custom HTML tool and its triggers in the Zaraz dashboard yourself, or reconnect and apply a removal preview.
- Removing a hostname from the Site's website addresses is refused while a Zaraz installation still targets it; update the installation first.

## Troubleshooting

- No hostname listed: add the exact HTTPS origin to the Site, proxy its DNS record, then reload the zone.
- Needs attention: the published configuration differs from the reviewed installation, or automatic injection is disabled. Inspect the zone in Cloudflare before creating a new preview; do not retry a failed write blindly.
- Verified, but still Waiting for activity: open a selected hostname and check for CSP violations, privacy tools, a saved refusal on that browser or blocked requests to the Telltale server.
- Collection continues after a CMP change: the managed installation does not follow your CMP. Remove it and use consent-controlled collection.