NPM Package

Installation

npm install --save @outlit/browser

pnpm add @outlit/browser

yarn add @outlit/browser

bun add @outlit/browser

Initialization

Initialize the tracker once at app startup, typically in your entry point:

import outlit from '@outlit/browser'

outlit.init({
  publicKey: 'pk_your_public_key',
  // Optional configuration
  trackPageviews: true,
  trackForms: true,
  trackEngagement: true,
  flushInterval: 5000, // ms
})

Configuration Options

publicKey

string

required

Your organization’s public key from Settings → Website Tracking.

apiHost

string

default:"https://app.outlit.ai"

The API endpoint for sending events. Override for self-hosted or proxy setups.

trackPageviews

boolean

default:"true"

Automatically track pageviews on navigation.

trackForms

boolean

default:"true"

Automatically capture form submissions.

formFieldDenylist

string[]

Additional field names to exclude from form capture.

flushInterval

number

default:"5000"

How often to send batched events (in milliseconds).

autoTrack

boolean

default:"true"

Whether to start tracking automatically on init. Set to false if you need to wait for user consent. Call enableTracking() after consent is obtained.

autoIdentify

boolean

default:"true"

Automatically identify users when they submit forms containing an email field. Extracts email and name using field name heuristics. Set to false to call identify() manually. See Auto-Identify for details.

trackEngagement

boolean

default:"true"

Track engagement metrics (active time on page). Emits engagement events on page exit and SPA navigation capturing how long users actively engaged with each page.

idleTimeout

number

default:"30000"

Idle timeout in milliseconds for engagement tracking. After this period of no user interaction, the user is considered idle and active time stops accumulating.

trackCalendarEmbeds

boolean

default:"true"

Track booking events from calendar embeds (Cal.com, Calendly). Fires a calendar event when bookings are detected.

If you need to wait for user consent before tracking:

import outlit from '@outlit/browser'

// Initialize without auto-tracking
outlit.init({
  publicKey: 'pk_your_public_key',
  autoTrack: false, // Don't track until consent
})

// When user accepts cookies/tracking
function onConsentAccepted() {
  outlit.enableTracking()
}

// When user declines
function onConsentDeclined() {
  outlit.disableTracking()
}

Check Tracking Status

import { isTrackingEnabled } from '@outlit/browser'

if (isTrackingEnabled()) {
  console.log('Tracking is active')
}

API Reference

`outlit.init(options)`

Initialize the tracker. Must be called before other methods.

import outlit from '@outlit/browser'

outlit.init({ publicKey: 'pk_xxx' })

`outlit.track(eventName, properties?)`

Track a custom event.

outlit.track('feature_used', {
  feature: 'export',
  format: 'csv',
  rowCount: 1500
})

eventName

string

required

A descriptive name for the event. Use snake_case.

properties

Record<string, string | number | boolean | null>

Additional data to attach to the event.

`outlit.identify(options)`

Identify the current visitor. Links their anonymous history to a known profile.

outlit.identify({
  email: 'jane@acme.com',
  userId: 'usr_12345',
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  traits: {
    name: 'Jane Doe',
    role: 'Engineering Manager',
  },
  customerTraits: {
    plan: 'enterprise'
  }
})

string

The visitor’s email address. Primary identifier.

userId

string

Your internal user ID (from Supabase, Auth0, etc.).

traits

Record<string, string | number | boolean | null>

Additional properties about the user.

customerId

string

Your system-owned customer/account/workspace ID. Send this when the visitor belongs to a known account.

customerTraits

Record<string, string | number | boolean | null>

Additional properties about the customer/account profile.

`outlit.setUser(identity)`

Set the current user identity. Ideal for SPA applications where you know the user’s identity after authentication. Can be called before tracking is enabled—the identity is queued and applied when enableTracking() is called.

// After user logs in
outlit.setUser({
  email: 'jane@acme.com',
  userId: 'usr_12345',
  customerId: 'cust_123', // Your app's account/workspace/customer ID
  traits: {
    name: 'Jane Doe',
  },
  customerTraits: {
    plan: 'pro'
  }
})

Both setUser() and identify() link the visitor to a known profile. The difference is setUser() can be called before tracking is enabled (identity is queued), while identify() requires tracking to be enabled first.

`outlit.clearUser()`

Clear the current user identity. Call this when the user logs out.

// On logout
outlit.clearUser()

Activation event

Track the ordinary event selected as your activation signal after the milestone succeeds:

outlit.track('onboarding_completed', { flow: 'onboarding', step: 'completed' })

Configure this event as your activation signal. Outlit Core derives activation, engagement, and inactivity from ordinary events. Billing status comes from verified integrations such as Stripe. See Customer Journey.

`outlit.getInstance()`

Get the singleton tracker instance.

const tracker = outlit.getInstance()
const visitorId = tracker.getVisitorId()

`outlit.enableTracking()`

Enable tracking after consent. Only needed if autoTrack: false was set during init.

import outlit, { enableTracking } from '@outlit/browser'

// Initialize with autoTrack: false
outlit.init({ publicKey: 'pk_xxx', autoTrack: false })

// Later, after consent
enableTracking()
// or
outlit.enableTracking()

`outlit.disableTracking()`

Disable tracking and flush any pending events. Use this when a user declines or revokes consent.

// When user declines or revokes consent
outlit.disableTracking()

`outlit.isTrackingEnabled()`

Check if tracking is currently enabled.

import { isTrackingEnabled } from '@outlit/browser'

if (isTrackingEnabled()) {
  // Tracking is active
}

TypeScript Support

The package is written in TypeScript and includes full type definitions:

import outlit, {
  type OutlitOptions,
  type BrowserTrackOptions,
  type BrowserIdentifyOptions,
  type UserIdentity,
} from '@outlit/browser'

// Full type safety
outlit.init({
  publicKey: 'pk_xxx',
  trackPageviews: true,
})

outlit.track('purchase_completed', {
  orderId: 'ord_123',
  amount: 99.99,
  currency: 'USD',
})

Framework Examples

Next.js (App Router)

// app/providers.tsx
'use client'

import { useEffect } from 'react'
import outlit from '@outlit/browser'

export function OutlitInit() {
  useEffect(() => {
    outlit.init({ publicKey: process.env.NEXT_PUBLIC_OUTLIT_KEY! })
  }, [])

  return null
}

// app/layout.tsx
import { OutlitInit } from './providers'

export default function RootLayout({ children }) {
  return (
    <html>
      <body>
        <OutlitInit />
        {children}
      </body>
    </html>
  )
}

Vue.js

// main.ts
import { createApp } from 'vue'
import App from './App.vue'
import outlit from '@outlit/browser'

outlit.init({ publicKey: import.meta.env.VITE_OUTLIT_KEY })

createApp(App).mount('#app')

<!-- Component.vue -->
<script setup>
import outlit from '@outlit/browser'

function handleClick() {
  outlit.track('button_clicked', { id: 'cta' })
}
</script>

Svelte

// +layout.ts
import outlit from '@outlit/browser'

outlit.init({ publicKey: import.meta.env.VITE_OUTLIT_KEY })

<!-- Component.svelte -->
<script>
import outlit from '@outlit/browser'

function handleClick() {
  outlit.track('button_clicked', { id: 'cta' })
}
</script>

Advanced Usage

Manual Flush

Force immediate sending of queued events:

await outlit.getInstance().flush()

Shutdown

Gracefully shutdown the tracker (flushes remaining events):

await outlit.getInstance().shutdown()

Access Visitor ID

Get the current visitor’s ID for server-side correlation:

const visitorId = outlit.getInstance().getVisitorId()

// Send to your backend
fetch('/api/correlate', {
  body: JSON.stringify({ visitorId, data: '...' })
})

Engagement Tracking

Engagement tracking captures how long users actively spend on each page. It’s enabled by default and works automatically.

How It Works

Active time is tracked when the page is visible and the user is interacting (mouse movement, clicks, scrolling, typing)
Idle detection pauses active time after 30 seconds of no interaction (configurable via idleTimeout)
Engagement events are automatically sent when the user navigates to a new page or leaves the site

Engagement Data

Each engagement event includes:

Property	Description
`activeTimeMs`	Time in milliseconds the user was actively engaged
`totalTimeMs`	Total wall-clock time on the page
`sessionId`	Session ID for grouping page views

Disabling Engagement Tracking

outlit.init({
  publicKey: 'pk_xxx',
  trackEngagement: false, // Disable engagement tracking
})

Getting Started

Concepts

Browser SDKs

Server SDKs

CLI

AI Integrations

Use Cases

Installation

Initialization

Configuration Options

Check Tracking Status

API Reference

`outlit.init(options)`

`outlit.track(eventName, properties?)`

`outlit.identify(options)`

`outlit.setUser(identity)`

`outlit.clearUser()`

Activation event

`outlit.getInstance()`

`outlit.enableTracking()`

`outlit.disableTracking()`

`outlit.isTrackingEnabled()`

TypeScript Support

Framework Examples

Next.js (App Router)

Vue.js

Svelte

Advanced Usage

Manual Flush

Shutdown

Access Visitor ID

Engagement Tracking

How It Works

Engagement Data

Disabling Engagement Tracking

Next Steps

React Integration

Server-Side

​Installation

​Initialization

​Configuration Options

​Consent Management

​Check Tracking Status

​API Reference

​outlit.init(options)

​outlit.track(eventName, properties?)

​outlit.identify(options)

​outlit.setUser(identity)

​outlit.clearUser()

​Activation event

​outlit.getInstance()

​outlit.enableTracking()

​outlit.disableTracking()

​outlit.isTrackingEnabled()

​TypeScript Support

​Framework Examples

​Next.js (App Router)

​Vue.js

​Svelte

​Advanced Usage

​Manual Flush

​Shutdown

​Access Visitor ID

​Engagement Tracking

​How It Works

​Engagement Data

​Disabling Engagement Tracking

​Next Steps

React Integration

Server-Side

Installation

Initialization

Configuration Options

Consent Management

Check Tracking Status

API Reference

`outlit.init(options)`

`outlit.track(eventName, properties?)`

`outlit.identify(options)`

`outlit.setUser(identity)`

`outlit.clearUser()`

Activation event

`outlit.getInstance()`

`outlit.enableTracking()`

`outlit.disableTracking()`

`outlit.isTrackingEnabled()`

TypeScript Support

Framework Examples

Next.js (App Router)

Vue.js

Svelte

Advanced Usage

Manual Flush

Shutdown

Access Visitor ID

Engagement Tracking

How It Works

Engagement Data

Disabling Engagement Tracking

Next Steps