Methods

Every facade method is crash-safe: the SDK never throws into the host app. Before init() resolves, calls become no-ops rather than failing.

Index#

Properties#

Reference#

whenReady#

ScaleBun.whenReady(): Promise<void>

Resolves once init() has SETTLED — succeeded or failed. Await it before reaching for a feature controller from component code.

init#

ScaleBun.init(config: ScaleBunInitConfig): Promise<void>

Initialize the SDK. Builds config → pipeline → features → starts capture.

setConsent#

ScaleBun.setConsent(granted: boolean): void

Resolve consent-mode (GDPR/CIPA) — call from your CMP's grant/deny callback. With requireConsent:true, the SDK captures + sends nothing until setConsent(true). Safe to call before init() (the decision is stashed and applied once ready).

track#

ScaleBun.track(name: string, props?: Record<string, unknown>): void

Track a custom event. Fans out to the replay/session lane (correlation) AND the product-analytics lane (Event → funnels/events dashboards), and feeds Engage custom_event triggers.

register#

ScaleBun.register(props: Record<string, unknown>): void

A1 — register global "super" properties merged into every subsequent event (persisted).

unregister#

ScaleBun.unregister(key: string): void

A1 — remove a previously-registered super-property.

group#

ScaleBun.group(groupType: string, groupKey: string, traits?: Record<string, unknown>): void

A1 — associate the user with a B2B group (account/workspace). Stamps groups on every event + emits a $group on both lanes so the backend upserts the group profile.

alias#

ScaleBun.alias(newUserId: string, previousId?: string): void

A1 — link the current identity to a prior id (anon→known / cross-device merge).

reset#

ScaleBun.reset(): void

A1 — logout: mint a fresh anonymous id + clear user/super-props/groups so the next user's events aren't attributed to the previous one.

trackPurchase#

ScaleBun.trackPurchase(input: RevenueInput): void

A4 — record revenue (one-time / subscription / refund). Normalized revenue/currency + LTV props to the analytics lane (server-deduped by transactionId) + a purchase event on the session lane for replay/CWV-revenue correlation. Group attribution rides the stamped groups.

trackSubscription#

ScaleBun.trackSubscription(input: SubscriptionInput): void

W2 — record a subscription lifecycle change (trial/started/renewed/plan_changed/canceled/…) so the backend derives REAL MRR/ARR/churn/trials from an event-sourced ledger (not approximated from purchases). For production truth prefer posting from your billing webhook to the s2s endpoint; this client method is for billing-UI-driven changes. Validate-or-drop (invalid input is ignored).

trackScreen#

ScaleBun.trackScreen(name: string, props?: Record<string, unknown>): void

Report the current route/screen name — used by the framework adapters (router→route-name) to supply real route names instead of raw pathnames. Emits a SCREEN_VIEW with a top-level screenName so flows/funnels/journey pick it up.

identify#

ScaleBun.identify(userId: string, traits?: Record<string, unknown>): void

Attach user identity to the session + stamp it onto the analytics lane (links the profile).

setUser#

ScaleBun.setUser(user: ScaleBunUser): void

Set / merge the current user.

captureError#

ScaleBun.captureError(error: unknown, info?: { componentStack?: string; level?: ErrorLevel; tags?: Record<string, string>; context?: Record<string, unknown>; fingerprint?: string; }): void

Manually capture a handled error — routed through ErrorsFeature so normalization is shared. info.componentStack (from a React error boundary) rides along on the error item's metadata.

addBreadcrumb#

ScaleBun.addBreadcrumb(crumb: { message?: string; category?: string; level?: BreadcrumbLevel; type?: string; data?: Record<string, unknown>; }): void

Record a manual breadcrumb — an app-level milestone (e.g. "checkout: payment submitted") that joins the auto-captured trail (console/network/navigation/clicks) attached to the next error. Messages are scrubbed; the ring is bounded, so this is safe to call liberally.

setTag#

ScaleBun.setTag(key: string, value: string): void

Set a searchable tag merged into every subsequent error (e.g. setTag('plan','enterprise')).

setContext#

ScaleBun.setContext(key: string, value: unknown): void

Attach arbitrary structured context merged into every subsequent error.

setErrorLevel#

ScaleBun.setErrorLevel(level: ErrorLevel): void

Set the default severity for subsequent errors (a captureError level overrides per-call).

submitRating#

ScaleBun.submitRating(score: number, comment?: string, surveyId?: string): void

Submit an in-app rating (an item in the same session). Rejects invalid scores (1–5).

registerInAppSlot#

ScaleBun.registerInAppSlot(name: string, el: HTMLElement): Promise<() => void>

Declare where INLINE in-app messages may render.

reportBug#

ScaleBun.reportBug(input: { message: string; title?: string; email?: string }): Promise<string | null>

flush#

ScaleBun.flush(): Promise<void>

Force an immediate flush of BOTH egress lanes (session pipeline + analytics /batch).

errorStats#

ScaleBun.errorStats(): ErrorStats | null

The SDK's own error-pipeline health (captured / dropped / by-type / breadcrumb count).

perfStats#

ScaleBun.perfStats(): PerfStats | null

The SDK's own RUM health (transactions / dropped / resources / jank / sample rate).

networkStats#

ScaleBun.networkStats(): NetworkStats | null

The SDK's own network-capture health (captured / by-protocol / by-failure / dropped / bodies).

close#

ScaleBun.close(): Promise<void>

End the session and stop capture.

egressStats#

ScaleBun.egressStats(): { pending: number; dropped: number }

Egress telemetry for debugging / a Dev Panel: items still waiting to send, and items dropped (queue overflow or stale-on-reload), summed across the session pipeline + analytics lane.

analyticsStats#

ScaleBun.analyticsStats(): { pending: number; dropped: number; sampledOut: number; flushes: number; sampleRate: number } | null

A7 — product-analytics lane observability: events pending/dropped/sampled-out, successful flushes, and the active sample rate. Null when analytics isn't running.

inbox#

ScaleBun.inbox(): InboxController

The persistent message inbox. Returns a stable headless controller (reactive subscribe + verbs). When features.inbox is off (default until GA) this is a safe no-op so hosts never crash.

coachmarks#

ScaleBun.coachmarks(): CoachController

Coachmark tours — start/next/back/skip/end, subscribe to $coachmark_* events, or notify() a custom-event advance. Every step is replayCoord-stamped (watch the frame a user abandoned a step).

enablePush#

ScaleBun.enablePush(opts?: PushEnableOptions): Promise<PushEnableStatus>

E4 — opt into Web Push. MUST be called from a user gesture (browsers gate the notification prompt). Feature-detects + fetches the tenant VAPID key, registers the host-served service worker (/scalebun-push-sw.js), subscribes, and registers the browser PushSubscription with the backend. Resolves a status string — never throws. No-op ('unsupported'/'not-configured'/'denied') when the browser lacks support, the tenant hasn't set Web Push up, or the user declined.

onNotificationOpened#

ScaleBun.onNotificationOpened(cb: (payload: { data: Record<string, unknown>; action: string | null }) => void): () => void

E4 — subscribe to notification-open events (fired when the user clicks a push). Safe to call before enablePush(): the callback is buffered and attached once the push module loads. Returns an unsubscribe function.