Core concepts

Eight terms carry most of the meaning across the SDK, the API and the dashboard. Getting these straight makes the rest of the documentation much easier to read.

Tenancy#

Organization → Project → App → AppEnvironment → SdkKey

An organization is the billing and membership boundary. A project groups related apps. An app is one product. An app environment is one deployment target of that app, and it owns the credentials.

The practical consequence: you do not switch environments with a config flag. You switch by using a different environment's key.

Environment#

A named deployment target — typically development, staging and production. Each one issues its own client key and secret key, and the client key's prefix tells you which environment it belongs to (skb_test_ck_, skb_staging_ck_, skb_live_ck_).

Session#

A period of product use. It is the unit almost everything else hangs off: events, screens, replay frames, performance metrics and errors are all attributed to a session.

Sessions start automatically on both platforms. They end after an idle timeout, or when you end one explicitly.

ScaleBun.sessionId;   // the current session idawait ScaleBun.close(); // end the session and stop capture

ScaleBun.session.start({ source: 'deep-link' });ScaleBun.session.end('ended');

Identity#

Before you call identify(), activity is attributed to a device. After, it is attributed to a user, and prior device activity is linked to that user.

ScaleBun.identify('user_123', { plan: 'pro' });

Call it after sign-in. On sign-out, clear the identity so a shared device does not attribute one person's activity to another — ScaleBun.reset() on the web, which also mints a fresh anonymous id and drops super-properties, and clearUser() on React Native. See Identity.

Event#

A named thing that happened, with optional properties.

ScaleBun.track('checkout_started', { cartValue: 42.5, currency: 'USD' });

Some events are emitted for you. React Native sends first_open, app_open and session_start; the web SDK reserves a $-prefixed vocabulary instead — $pageview, $autocapture, $rageclick and others. The two sets do not overlap, so a query that matches on a literal name is platform-specific.

The rest you define, and the names you choose become your analytics schema, so choose them deliberately. See Event naming.

Envelope#

The wire format. Captured data is wrapped in an envelope, batched with others, and persisted to an on-device outbox before any network call.

That is what makes offline capture work: the envelope survives an app kill, and the outbox drains with retry and backoff when connectivity returns. You never wait on the network, and a failed request does not lose data.

Flag, rollout, experiment#

Three related things delivered by the same runtime config payload:

All three resolve locally against cached config, so they are synchronous and safe to call during render. They return conservative defaults (false / null) before config has been fetched.

Entitlement#

What your plan permits. Entitlements are enforced twice: the SDK does not register a collector for a capability you are not entitled to, and the backend rejects data for it. The first is a cost optimisation; the second is the actual boundary.

Related#

• Architecture — how these fit together.

• Quick start — put them to use.

• Events — designing an event schema.