SdkSession

A fully-initialized SDK session with convenience methods for creating placement and entitlement controllers, updating user context, and accessing the underlying SDK instance.

This is the recommended entry point for headless (non-React) consumers.

Example

const session = await initRevTurbine({
  tenantId: 'tenant_abc',
  apiKey: 'rt_live_xxx',
  endpoint: 'https://api.revturbine.io',
  user: { id: 'user_123', plan: { id: 'pro' } },
});

// Get a placement by slot ID
const banner = session.placement({ surfaceSlot: { id: 'upsell_banner' } });
const decision = await banner.load();

// Check an entitlement with auto-gate
const gate = session.entitlement({ handle: 'brand_kit', autoGate: true });
await gate.check();

// Update user context (works in any runtime mode)
session.identify('user_456', { plan: { id: 'enterprise' } });
session.setUserContext({ personalization: { company: 'Acme' } });

Properties

sdk

readonly sdk: RevTurbineCustomerSdk

The underlying SDK instance. Use for advanced/direct operations.

---

theme

readonly theme: RevTurbineTheme

Resolved theme.

Methods

checkEntitlement()

checkEntitlement(handle, context?): Promise<{ }>

One-shot entitlement check. For auto-gating or reactive updates, prefer entitlement which returns a full controller.

Parameters

handle

string

context?

RevTurbineEntitlementContext

Returns

Promise<{ }>

---

entitlement()

entitlement(options): EntitlementGate

Create an EntitlementGate bound to this session’s SDK.

Parameters

options

EntitlementGateOptions

Returns

EntitlementGate

Example

const gate = session.entitlement({ handle: 'brand_kit', autoGate: true });
await gate.check();
if (gate.denied) { showGate(gate.gatedPlacement); }

---

fetchUserContext()

fetchUserContext(userId): Promise<UserTargetingContext>

Fetch full user context from the server (server runtime mode).

Parameters

userId

string

Returns

Promise<UserTargetingContext>

---

getPlacement()

getPlacement(config): Promise<{ } | null>

Get a raw placement output by request config (slot, entitlement, plan, or chained). Returns the full PlacementOutput or null.

Parameters

config

RevTurbinePlacementRequestConfig

Returns

Promise<{ } | null>

---

getPlacementBySlotId()

getPlacementBySlotId(slotId, options?): Promise<RevTurbinePlacementDecision | null>

One-shot: register a surface slot, fetch a decision, and return it.

For repeated use or interaction tracking, prefer placement which returns a full controller.

Parameters

slotId

string

options?

Omit<PlacementControllerOptions, "placement" | "surfaceSlot">

Returns

Promise<RevTurbinePlacementDecision | null>

---

getTrialStatus()

getTrialStatus(): Promise<{ }>

Get the current trial status.

Returns

Promise<{ }>

---

getUsage()

getUsage(): RevTurbineUsageSnapshot

Get a snapshot of current usage balances.

Returns

RevTurbineUsageSnapshot

---

getUserContext()

getUserContext(): object

Get the current resolved user context (includes tenant_id, user_id).

Returns

object

---

identify()

identify(userId, contextOrTraits?): void

Identify a user and optionally set traits/context. Triggers segment re-evaluation and clears decision cache.

Parameters

userId

string

contextOrTraits?

UserContextInput | SdkTraits

Returns

void

---

placement()

placement(options): PlacementController

Create a PlacementController bound to this session’s SDK.

Parameters

options

PlacementControllerOptions

Returns

PlacementController

Example

const banner = session.placement({ surfaceSlot: { id: 'upsell_banner' } });
await banner.load();
if (banner.visible) { renderBanner(banner.content); }

---

resetIdentity()

resetIdentity(): void

Reset to anonymous user state.

Returns

void

---

resetUserContext()

resetUserContext(): void

Hard-reset the user context to a blank slate (no anonymous inference) — removes every user-context value plus usage balances and clears the decision cache, interaction state, and impression history. Mostly for demo / fixture flows. See RevTurbineCustomerSdk.resetUserContext.

Returns

void

---

setUserContext()

setUserContext(context): void

Merge fields into the current user context. Triggers segment re-evaluation.

Parameters

context

RevTurbineUserContext

Returns

void

---

trackEvent()

trackEvent(name, data?): Promise<void>

Track a custom event.

Parameters

name

string

data?

Record<string, JsonValue>

Returns

Promise<void>

---

updateUsage()

updateUsage(balances): void

Update usage balances (e.g. after a meter event).

Parameters

balances

UsageBalances

Returns

void