Reference

Script Configuration

Complete reference for the ChurnFast tracking script attributes, JavaScript API, and behavior.

Script tag

<script
  src="https://yourapp.churnfa.st/e/app.js"
  data-site="YOUR_SITE_ID"
  data-email="user@example.com">
</script>

html

Attributes

Attribute	Required	Description
`data-site`	Yes	Your website's unique UUID. Found on the Integrations page in ChurnFast.
`data-email`	Yes	The current user's email address. Required to link activity to Stripe customers. SHA-256 hashed client-side before sending — the plaintext email never leaves the browser.

JavaScript API

The script exposes a global window._cf object:

`_cf.identify(email)`

Identify the current user by their email address. Use this when the email isn't available at page load time — for example, after a login or registration flow in a single-page app.

// Call after the user logs in
window._cf.identify('user@example.com');

javascript

Parameter	Type	Description
`email`	string	The user's email address. Lowercased, trimmed, and hashed via SHA-256 before transmission.

What's tracked

Page views

The script automatically records a page_view event for the initial page load and every subsequent navigation. Only the pathname is recorded.

Session durations

Each session is assigned a unique ID stored in sessionStorage (key: cf_sid). The session persists across page loads within the same tab but resets when the tab is closed. ChurnFast uses timestamps on page view events to calculate session durations.

SPA navigation

Client-side navigation is detected by intercepting history.pushState, history.replaceState, and the popstate event. This covers React Router, Next.js, Vue Router, Inertia.js, and most SPA frameworks.

Email hashing

When an email is provided via data-email or _cf.identify(), it is lowercased, trimmed, and hashed with SHA-256 using the Web Crypto API. The hash is stored in sessionStorage (key: cf_ehash) and included in all subsequent event batches. ChurnFast never receives the plaintext email.

Event batching

Events are queued in memory and sent in batches for efficiency:

Trigger	Description
Batch size	Events flush when the queue reaches 10 events.
Timer	Events flush every 30 seconds regardless of queue size.
Page hidden	Events flush when the page visibility changes to hidden (tab switch, close, or minimize).

Note

Events are sent using navigator.sendBeacon() for reliability, with a fallback to fetch() with keepalive: true. This ensures events are delivered even when the page is closing.

Event payload

Each batch is sent as a POST request to /e/data with the following JSON structure:

{
  "site": "your-site-uuid",
  "email_hash": "sha256-hex-string",
  "session_id": "uuid-v4",
  "events": [
    {
      "type": "page_view",
      "url": "/dashboard",
      "ts": 1711324800
    },
    {
      "type": "page_view",
      "url": "/settings",
      "ts": 1711324860
    }
  ]
}

json

React component

A pre-built React component is available for React and Next.js applications. It handles script loading, cleanup, and email re-identification automatically:

import { ChurnFast } from './components/churnfast';

// Render once in your app root
<ChurnFast siteId="YOUR_SITE_ID" email={user.email} />

tsx

See the Next.js and React installation guides for the full component source code.

Cookies

The script reads (but does not set) the following cookie:

Cookie	Description
`datafast_visitor_id`	An optional visitor ID for acquisition channel tracking. If present, it is included in the event payload and associated with the customer record.