Install with Cloudflare

Connect Cloudflare to start Switchfrog on selected hostnames without changing application code.

Before you start

You need:

• a Switchfrog Site that contains each hostname you want to select;
• Team owner or admin access in Switchfrog; and
• a proxied Cloudflare A, AAAA, or CNAME record for each hostname.

Hostname selection is exact. Selecting one hostname does not include its apex, siblings, or subdomains. You can select several hostnames in one zone. To cover another zone, including one in the same Cloudflare account, add another installation. To change hostnames in the same zone, edit the existing installation.

Switchfrog does not change DNS, proxy status, Workers, Web Application Firewall (WAF) settings, or application source code.

Install and publish

1. Open Onboarding in the Switchfrog console.
2. Under Install Switchfrog, select Cloudflare.
3. Select Connect Cloudflare, then review and authorize access to the Cloudflare account that contains your zone. You do not create or paste a Cloudflare credential.
4. Select the Cloudflare zone and the exact Hostnames where Switchfrog should load.
5. Select Install and publish.

Verified now confirms that Switchfrog found the published Cloudflare configuration. Open a selected hostname in another tab. The onboarding page changes from Waiting for activity to Activity received for this Site when Switchfrog receives browser activity.

Switchfrog starts anonymously. You do not add a script tag, copy a publishable key, or configure Zaraz by hand.

Identify signed-in users with Zaraz

Identity is optional. After your application knows the signed-in user or account, send stable internal IDs:

await zaraz.track("switchfrog.identify", {
  userId,
  accountId,
})

Set a missing user or account ID to null. Provide at least one ID.

These values are browser-observed context. They do not verify identity or authorize an action. Do not send email addresses, access tokens, session IDs, or secrets. Use the authenticated POST /v1/identify endpoint when your backend must attach server-verified identity.

Use the Browser SDK client

Cloudflare starts the Browser SDK with the Site's publishable key and endpoint. Access its client after the browser's load event:

const client = window.Switchfrog.getClient()
const sessionToken = await client.getSessionToken()

Send the session token only to your backend with the protected action. Your backend must authenticate the user and call POST /v1/verify before it permits the action. Do not put the token in Zaraz fields, the DOM, a data layer, logs, or another global.

Reset when the user or account changes

Call reset() from the application code that owns logout or account changes, before a different user or account uses the same page. Reset retires the current local identity boundary. The next use starts a new one. Reset does not revoke the previous token or delete activity already accepted by Switchfrog.

await client.reset()

After reset resolves, send the switchfrog.identify event above for the replacement user or account.

See the Browser SDK guide for the complete client and identity lifecycle.

Change or remove the installation

• Select Change hostnames, update the exact selection, then select Save and publish.
• Select Add another zone to install Switchfrog in another authorized Cloudflare zone.
• Select Remove from Cloudflare, then Remove and publish. This removes the Site's managed configuration from that zone but keeps the Team's Cloudflare connection.
• Select Update Cloudflare access when you need access to different zones.
• Select Refresh Cloudflare when the connection says Refresh required.
• If refresh does not restore the connection, select Reconnect Cloudflare and authorize access again.
• Remove every Cloudflare installation in the Team before you select Disconnect Cloudflare. Disconnecting removes the Team's shared Cloudflare access. A Site can reconnect later.

Troubleshoot by symptom

No hostname appears

No eligible hostnames were found. Add a hostname to this Site in Switchfrog and proxy its A, AAAA, or CNAME DNS record in Cloudflare, then try again.

If another Switchfrog Site already uses the hostname, choose a different hostname and try again.

The connection says Refresh required

Select Refresh Cloudflare. If that does not restore the connection, select Reconnect Cloudflare and authorize access again.

The installation says Needs attention

Read the recovery message beside the affected zone. If Cloudflare has Zaraz changes that Switchfrog cannot overwrite, review that zone in Cloudflare before trying again.

The installation says Could not verify

Follow the recovery message in the affected installation row. Check the zone in Cloudflare before retrying only when that message says Cloudflare may have applied the change.

Verified now appears, but activity does not

Open a page on one of the selected exact hostnames. Confirm that the page's consent controls, privacy tools, Content Security Policy, proxy, or firewall do not block Switchfrog requests. Keep Onboarding open until it shows Activity received for this Site.