📈 Open source, privacy-first web analytics — a cookie-less Google Analytics alternative with built-in error tracking and performance monitoring. Self-host it or use our cloud. Get started for free!
TypeScript chartsclickhousedockergdprgoogle-analyticsmetricsmonitoringmysqlnestjsprivacyredisself-hostedselfhostedstatisticstailwindcssweb-analyticswebanalyticswebsite
import {
Lib,
LibOptions,
TrackEventOptions,
PageViewsOptions,
ErrorOptions,
PageActions,
ErrorActions,
defaultActions,
IErrorEventPayload,
IPageViewPayload,
FeatureFlagsOptions,
ExperimentOptions,
SessionReplayOptions,
SessionReplayActions,
defaultSessionReplayActions,
Traits,
} from './Lib.js'
export type { AutoCaptureOptions, OutboundLinksOptions } from './Lib.js'
export let LIB_INSTANCE: Lib | null = null
/**
* Initialise the tracking library instance (other methods won't work if the library is not initialised).
*
* @param {string} pid The Project ID to link the instance of Swetrix.js to.
* @param {LibOptions} options Options related to the tracking.
* @returns {Lib} Instance of the Swetrix.js.
*/
export function init(pid: string, options?: LibOptions): Lib {
if (!LIB_INSTANCE) {
LIB_INSTANCE = new Lib(pid, options)
}
return LIB_INSTANCE
}
/**
* With this function you are able to track any custom events you want.
* You should never send any identifiable data (like User ID, email, session cookie, etc.) as an event name.
* The total number of track calls and their conversion rate will be saved.
*
* @param {TrackEventOptions} event The options related to the custom event.
*/
export async function track(event: TrackEventOptions): Promise<void> {
if (!LIB_INSTANCE) return
await LIB_INSTANCE.track(event)
}
/**
* With this function you are able to automatically track pageviews across your application.
*
* @param {PageViewsOptions} options Pageviews tracking options.
* @returns {PageActions} The actions related to the tracking. Used to stop tracking pages.
*/
export function trackViews(options?: PageViewsOptions): Promise<PageActions> {
return new Promise((resolve) => {
if (!LIB_INSTANCE) {
resolve(defaultActions)
return
}
// We need to verify that document.readyState is complete for the performance stats to be collected correctly.
if (typeof document === 'undefined' || document.readyState === 'complete') {
resolve(LIB_INSTANCE.trackPageViews(options))
} else {
window.addEventListener('load', () => {
// @ts-ignore
resolve(LIB_INSTANCE.trackPageViews(options))
})
}
})
}
/**
* This function is used to set up automatic error events tracking.
* It set's up an error listener, and whenever an error happens, it gets tracked.
*
* @returns {ErrorActions} The actions related to the tracking. Used to stop tracking errors.
*/
export function trackErrors(options?: ErrorOptions): ErrorActions {
if (!LIB_INSTANCE) {
return defaultActions
}
return LIB_INSTANCE.trackErrors(options)
}
export function stopAutoCapture(): void {
LIB_INSTANCE?.stopAutoCapture()
}
export function startSessionReplay(options?: SessionReplayOptions): Promise<SessionReplayActions> {
if (!LIB_INSTANCE) {
return Promise.resolve(defaultSessionReplayActions)
}
return LIB_INSTANCE.startSessionReplay(options)
}
/**
* This function is used to manually track an error event.
* It's useful if you want to track specific errors in your application.
*
* @param payload Swetrix error object to send.
* @returns void
*/
export function trackError(payload: IErrorEventPayload): void {
if (!LIB_INSTANCE) return
LIB_INSTANCE.submitError(payload, false)
}
/**
* This function is used to manually track a page view event.
* It's useful if your application uses esoteric routing which is not supported by Swetrix by default.
*
* @deprecated This function is deprecated and will be removed soon, please use the `pageview` instead.
* @param pg Path of the page to track (this will be sent to the Swetrix API and displayed in the dashboard).
* @param _prev Path of the previous page (deprecated and ignored).
* @param unique If set to `true`, only 1 event with the same ID will be saved per user session.
* @returns void
*/
export function trackPageview(pg: string, _prev?: string, unique?: boolean): void {
if (!LIB_INSTANCE) return
LIB_INSTANCE.submitPageView({ pg }, Boolean(unique), {})
}
export interface IPageviewOptions {
payload: Partial<IPageViewPayload>
unique?: boolean
}
export function pageview(options: IPageviewOptions): void {
if (!LIB_INSTANCE) return
LIB_INSTANCE.submitPageView(options.payload, Boolean(options.unique), {})
}
/**
* Fetches all feature flags for the project.
* Results are cached for 5 minutes by default and share a cache with experiments.
*
* @param options - Options for evaluating feature flags (`profileId` only).
* @param forceRefresh - If true, bypasses the cache and fetches fresh flags.
* @returns A promise that resolves to a record of flag keys to boolean values.
*
* @example
* ```typescript
* const flags = await getFeatureFlags({
* profileId: 'user-123'
* })
*
* if (flags['new-checkout']) {
* // Show new checkout flow
* }
* ```
*/
export async function getFeatureFlags(
options?: FeatureFlagsOptions,
forceRefresh?: boolean,
): Promise<Record<string, boolean>> {
if (!LIB_INSTANCE) return {}
return LIB_INSTANCE.getFeatureFlags(options, forceRefresh)
}
/**
* Gets the value of a single feature flag.
*
* @param key - The feature flag key.
* @param options - Options for evaluating the feature flag (`profileId` only).
* @param defaultValue - Optional default value to return if the flag is not found. Defaults to false.
* @returns A promise that resolves to the boolean value of the flag.
*
* @example
* ```typescript
* const isEnabled = await getFeatureFlag('dark-mode', { profileId: 'user-123' })
*
* if (isEnabled) {
* // Enable dark mode
* }
* ```
*/
export async function getFeatureFlag(
key: string,
options?: FeatureFlagsOptions,
defaultValue: boolean = false,
): Promise<boolean> {
if (!LIB_INSTANCE) return defaultValue
return LIB_INSTANCE.getFeatureFlag(key, options, defaultValue)
}
/**
* Clears the cached feature flags and experiments, forcing a fresh fetch on the next call.
* Useful when you know the user's profile has changed.
*/
export function clearFeatureFlagsCache(): void {
if (!LIB_INSTANCE) return
LIB_INSTANCE.clearFeatureFlagsCache()
}
/**
* Fetches variant assignments for running A/B test experiments returned by feature flag evaluation.
* Results are cached for 5 minutes by default (shared cache with feature flags).
*
* @param options - Options for evaluating experiments (`profileId` only).
* @param forceRefresh - If true, bypasses the cache and fetches fresh data.
* @returns A promise that resolves to a record of experiment IDs to variant keys.
*
* @example
* ```typescript
* const experiments = await getExperiments()
* // experiments = { 'exp-123': 'variant-a', 'exp-456': 'control' }
*
* // Use the assigned variant
* const checkoutVariant = experiments['checkout-experiment-id']
* if (checkoutVariant === 'new-checkout') {
* showNewCheckout()
* } else {
* showOriginalCheckout()
* }
* ```
*/
export async function getExperiments(
options?: ExperimentOptions,
forceRefresh?: boolean,
): Promise<Record<string, string>> {
if (!LIB_INSTANCE) return {}
return LIB_INSTANCE.getExperiments(options, forceRefresh)
}
/**
* Gets the variant key for a specific A/B test experiment.
*
* @param experimentId - The experiment ID.
* @param options - Options for evaluating the experiment (`profileId` only).
* @param defaultVariant - Optional default variant key to return if the experiment is not found. Defaults to null.
* @returns A promise that resolves to the variant key assigned to this user, or defaultVariant if not found.
*
* @example
* ```typescript
* const variant = await getExperiment('checkout-redesign-experiment-id', { profileId: 'user-123' })
*
* // Optional fallback variant:
* const variantWithFallback = await getExperiment('checkout-redesign-experiment-id', undefined, 'control')
*
* if (variant === 'new-checkout') {
* // Show new checkout flow
* showNewCheckout()
* } else if (variant === 'control') {
* // Show original checkout (control group)
* showOriginalCheckout()
* } else {
* // Experiment not running or user not included
* showOriginalCheckout()
* }
* ```
*/
export async function getExperiment(
experimentId: string,
options?: ExperimentOptions,
defaultVariant: string | null = null,
): Promise<string | null> {
if (!LIB_INSTANCE) return defaultVariant
return LIB_INSTANCE.getExperiment(experimentId, options, defaultVariant)
}
/**
* Clears the cached experiments, forcing a fresh fetch on the next call.
* This is an alias for clearFeatureFlagsCache since experiments and flags share the same cache.
*/
export function clearExperimentsCache(): void {
if (!LIB_INSTANCE) return
LIB_INSTANCE.clearExperimentsCache()
}
/**
* Identify the current visitor with your own user ID (e.g. after they log in).
*
* The visitor's current anonymous profile gets linked to the identified profile
* server-side, so their pre-login activity is attributed to it. All events sent
* after this call are associated with the identified profile.
*
* Swetrix stores nothing in the browser, so call identify() on every page load
* while the user is logged in. Call reset() when they log out.
*
* @param profileId A unique, stable identifier of the user, e.g. an internal
* user ID. It's stored as you provide it, so don't pass values you wouldn't
* want to see in your dashboard.
* @param traits Optional key / value metadata to show on the user's profile,
* e.g. their email, plan or signup date. Traits are merged with the ones
* already stored; pass `null` to remove one.
*
* @example
* ```typescript
* // After the user logs in (or on page load if they're already logged in)
* swetrix.identify('user-12345', {
* email: '[email protected]',
* plan: 'premium',
* })
*
* // On logout
* swetrix.reset()
* ```
*/
export async function identify(profileId: string, traits?: Traits): Promise<void> {
if (!LIB_INSTANCE) return
await LIB_INSTANCE.identify(profileId, traits)
}
/**
* Updates the traits of the already identified visitor without having to
* repeat their user ID. Only the keys you pass are touched; pass `null` to
* remove a trait.
*
* @example
* ```typescript
* swetrix.setTraits({ plan: 'enterprise', trialEndsAt: null })
* ```
*/
export async function setTraits(traits: Traits): Promise<void> {
if (!LIB_INSTANCE) return
await LIB_INSTANCE.setTraits(traits)
}
/**
* Resets the visitor's identity set via identify() (e.g. after they log out),
* so subsequent events are tracked anonymously again. Important on shared
* devices - otherwise the next visitor would be tracked under the previous
* user's identity.
*/
export function reset(): void {
if (!LIB_INSTANCE) return
LIB_INSTANCE.reset()
}
/**
* Gets the anonymous profile ID for the current visitor.
* If profileId was set via init options, returns that.
* Otherwise, requests server to generate one from IP/UA hash.
*
* This ID can be used for revenue attribution with payment providers like Paddle.
*
* @returns A promise that resolves to the profile ID string, or null on error.
*
* @example
* ```typescript
* const profileId = await getProfileId()
*
* // Pass to Paddle Checkout for revenue attribution
* Paddle.Checkout.open({
* items: [{ priceId: 'pri_01234567890', quantity: 1 }],
* customData: {
* swetrix_profile_id: profileId,
* swetrix_session_id: await getSessionId()
* }
* })
* ```
*/
export async function getProfileId(): Promise<string | null> {
if (!LIB_INSTANCE) return null
return LIB_INSTANCE.getProfileId()
}
/**
* Gets the current session ID for the visitor.
* Session IDs are generated server-side based on IP and user agent.
*
* This ID can be used for revenue attribution with payment providers like Paddle.
*
* @returns A promise that resolves to the session ID string, or null on error.
*
* @example
* ```typescript
* const sessionId = await getSessionId()
*
* // Pass to Paddle Checkout for revenue attribution
* Paddle.Checkout.open({
* items: [{ priceId: 'pri_01234567890', quantity: 1 }],
* customData: {
* swetrix_profile_id: await getProfileId(),
* swetrix_session_id: sessionId
* }
* })
* ```
*/
export async function getSessionId(): Promise<string | null> {
if (!LIB_INSTANCE) return null
return LIB_INSTANCE.getSessionId()
}
export {
LibOptions,
TrackEventOptions,
PageViewsOptions,
ErrorOptions,
PageActions,
ErrorActions,
IErrorEventPayload,
IPageViewPayload,
FeatureFlagsOptions,
ExperimentOptions,
Traits,
}