Installation
Add this snippet before the closing</body> tag. This creates a lightweight stub that queues calls until the full Outlit Browser SDK loads, without blocking page load:
<head>. Calls to outlit.track() or outlit.user.identify() will be queued and processed once the SDK loads.
Simple version
If you prefer a cleaner script tag and don’t need to call tracking methods before the SDK loads:string
required
Your organization’s public key. Find it in Settings → Website Visitors.
string
Custom API host. Defaults to
https://app.outlit.ai.string
Set to
"false" to disable automatic pageview tracking.string
Set to
"false" to disable automatic form capture.string
Controls when tracking starts.
"auto" (default when the attribute is absent) asks the Outlit edge endpoint whether the visitor’s region requires opt-in consent: tracking enables automatically outside the EEA, UK, and Switzerland, and stays off in those regions, when the region can’t be determined, or when the check fails. "true" enables tracking immediately on load; "false" waits for window.outlit.enableTracking(). A persisted opt-in or opt-out decision always takes precedence.string
Set to
"false" to disable automatic user identification from form submissions. When enabled (default), submitting a form with an email field automatically calls identify() with the extracted email and name. See Auto-identify for details.string
Set to
"false" to disable automatic tracking of calendar bookings from Cal.com and Calendly embeds. See Calendar embed tracking for details.trackEngagement) and the idle timeout (idleTimeout) are not configurable via data-* attributes — use the npm package if you need to change them (init() options).
Consent management
The default"auto" behavior already keeps tracking off for visitors in regions that require opt-in consent (EEA, UK, Switzerland, or unknown) — no cookies or localStorage keys are written until tracking is enabled. When your consent management platform reports acceptance, call window.outlit.enableTracking().
If you want tracking to wait for enableTracking() instead — unless a previous opt-in is stored — pass false as the last parameter:
With popular CMPs
- OneTrust
Check tracking status
Automatic tracking
Once installed, the tracker automatically captures:Pageviews
Every page navigation is tracked, including:- Full URL and path
- Page title
- Referrer
- UTM parameters (
utm_source,utm_medium,utm_campaign,utm_term,utm_content)
For single-page applications, the tracker automatically detects navigation via
pushState, replaceState, and popstate events.Form submissions
When a form is submitted, the tracker captures:- Form ID or name
- All field values (except sensitive fields)
- Passwords (
password,passwd,pwd) - Credit card numbers (
credit_card,cc_number,cvv) - Social Security numbers (
ssn,social_security) - API keys and tokens (
api_key,token,secret)
Manual tracking
Use the globalwindow.outlit object to track custom events:
Track custom events
string
required
The name of the event. Use snake_case for consistency.
object
Optional properties to attach to the event.
Identify visitors
When a visitor provides their email (signup, login, contact form), identify them:string
The visitor’s email address.
string
Your internal user ID (from Supabase, Auth0, Firebase, etc.).
object
Additional properties about the user.
email or userId; without either, identify() has no effect.
Set user identity
For SPA applications where you know the user’s identity after authentication:setUser() can be called before tracking is enabled (with data-auto-track="false"). The identity is queued and applied when enableTracking() is called.Clear user identity
Call when the user logs out:Activation event
Track your value milestone as an ordinary event once it succeeds:Get visitor ID
Access the current visitor’s ID (useful for server-side correlation). Returnsnull until tracking is enabled:
Queued commands
The IIFE snippet creates stub methods that queue all tracking calls until the SDK fully loads. This means you can calloutlit.track(), outlit.identify(), or any other method immediately—even in inline scripts before the SDK has finished loading:
Event batching
For performance, events are batched and sent:- Every 5 seconds (if there are pending events)
- When the queue reaches 10 events
- When the page is about to unload (using
sendBeacon)
Example: full integration
Troubleshooting
Events not appearing in the Outlit app
Events not appearing in the Outlit app
- Check your public key is correct
- Verify the domain is in your allowlist (Settings → Website Visitors)
- Open DevTools → Network and check for errors in
/api/i/v1/requests - Ensure the script loads without errors (check Console)
Form data not captured
Form data not captured
- Form must have a submit event (not prevented with
e.preventDefault()before capture) - Check if field names match the denylist (they may be filtered for security)
- Ensure
data-track-formsis not set to"false"
Pageviews not tracking on SPA
Pageviews not tracking on SPA
The tracker automatically listens for
pushState/replaceState. If using a custom router that doesn’t use these, manually track:Next steps
npm package
Use the npm package for more control
React integration
First-class React support with hooks
Calendar embeds
Track Cal.com and Calendly bookings
