Skip to content

📈 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!

12.3 KB
Raw Blame
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,
}