Runtime Modes

The SDK supports three runtime modes. Start with local_only to get up and running without any backend. It evaluates the full Playbook client-side and is production-capable on its own — a server mode is not a prerequisite for “real” decisions, it adds live config updates, server-authoritative usage, experiments, and centralized analytics.

Decision Tree

1. Are you getting started, building a demo, or need offline-first behavior?
   • Yes → local_only (recommended starting point)
   • No → continue
2. Do you need to route SDK calls through customer-owned endpoints?
   • Yes → custom_endpoints
   • No → revturbine_server

Mode Comparison

Mode	Best for	Network dependency	Required config
local_only	Getting started, offline, and production when a bundled Playbook is enough	None	localRuntime: { playbook }
revturbine_server	Production with live A/B testing	RevTurbine edge endpoints	tenantId, apiKey, endpoint
custom_endpoints	Customer proxy/service boundaries	Customer endpoints	Base config + endpointOverrides

Set the mode with the typed RuntimeMode constant rather than a raw string:

import { RuntimeMode } from '@revturbine/sdk';
// runtimeMode: RuntimeMode.LocalOnly | RuntimeMode.Server | RuntimeMode.CustomEndpoints

local_only makes no server calls at all — no config fetches and no telemetry (neither the /api/track clickstream nor the keyless SDK-init beacon). That makes it the right mode for demos, examples, and tests, which must never report events.

Copy-Paste Setup

Local-only (start here)

import { initRevTurbine, createLocalRuntimeConfig } from '@revturbine/sdk';
import playbook from './playbook.json';

const sdk = initRevTurbine(
  createLocalRuntimeConfig({
    tenantId: 'my-app',
    apiKey: 'local',
    endpoint: 'http://localhost',
    mode: 'react',
    localRuntime: {
      playbook,
      storageKey: 'my-app:revturbine-local-runtime',
    },
  }),
);

Tip

In local_only mode the SDK evaluates all targeting rules, entitlements, and placement decisions client-side using the exported config — no network calls for decisioning, and clickstream events stay in localStorage. The one exception is a keyless, anonymous sdk_init adoption beacon fired once at startup (config-shape counts only, never user data); opt out with anonymousTelemetry: false, or set previewMode: true for a docs/example render.

Server runtime

import { initRevTurbine, createServerRuntimeConfig } from '@revturbine/sdk';

const sdk = initRevTurbine(
  createServerRuntimeConfig({
    tenantId: 'tenant_abc',
    apiKey: 'rt_live_xxx',
    endpoint: 'https://revturbine.com/app',
    mode: 'react',
  }),
);

Custom endpoints

import { initRevTurbine, createCustomEndpointRuntimeConfig } from '@revturbine/sdk';

const sdk = initRevTurbine(
  createCustomEndpointRuntimeConfig({
    tenantId: 'tenant_abc',
    apiKey: 'rt_live_xxx',
    endpoint: 'https://proxy.example.com',
    mode: 'react',
    endpointOverrides: {
      decideContext: '/decisioning/decide-context',
      bootstrapContext: '/decisioning/bootstrap',
      checkEntitlement: '/entitlements/check',
      ingestEvents: '/events/ingest',
      touchpointTransition: '/touchpoints/transition',
    },
  }),
);

Migrating from Local to Server Mode

When you’re ready for production, the change is a single config swap. Your component code stays the same:

<RevTurbineProvider
  options={{
    tenantId: 'my-app',
    apiKey: 'local',
    endpoint: 'http://localhost',
    runtimeMode: RuntimeMode.LocalOnly,
    localRuntime: { playbook },
    tenantId: process.env.REVTURBINE_TENANT_ID!,
    apiKey: process.env.REVTURBINE_API_KEY!,
    endpoint: 'https://revturbine.com/app',
    runtimeMode: RuntimeMode.Server,
  }}
  defaultUserId="user_123"
>

Provider Fallback Strategy

Provider fallbacks are orthogonal to runtime mode. You can configure them in any mode when you want explicit provider-chain control.

Available options:

• provider: primary provider.
• providerFallbacks: ordered fallback provider list.
• providerFailureSlotBehavior: 'invisible' (default) or 'placeholder'.

Behavior:

1. SDK calls primary provider first.
2. If primary fails, SDK logs a warning and executes fallbacks in order.
3. If all configured providers fail for a method, SDK disables itself.
4. Disabled SDK returns hidden or placeholder placement output based on providerFailureSlotBehavior.

Recommendation by Mode

1. revturbine_server: add at least one fallback provider for resilience.
2. custom_endpoints: strongly recommend fallbacks because proxy integrations can be brittle during deploys.
3. local_only: provider fallbacks are optional; local runtime resolvers are often sufficient.

Server Runtime with Fallback

import { initRevTurbine, createServerRuntimeConfig } from '@revturbine/sdk';

const sdk = initRevTurbine({
  ...createServerRuntimeConfig({
    tenantId: 'tenant_abc',
    apiKey: 'rt_live_xxx',
    endpoint: 'https://revturbine.com/app',
    mode: 'react',
  }),
  provider: primaryProvider,
  providerFallbacks: [fallbackProviderA, fallbackProviderB],
  providerFailureSlotBehavior: 'placeholder',
});

Production Checklist

1. Start with local_only to validate your integration and placement slots.
2. When ready, switch to RuntimeMode.Server and provide real credentials.
3. Configure a primary RT provider first in the chain.
4. Add at least one fallback provider in providerFallbacks.
5. Keep fallback providers ordered by trust and operational readiness.
6. Choose providerFailureSlotBehavior intentionally per surface criticality.
7. Monitor console warnings for provider-chain failures.
8. Assume fail-closed behavior: if all providers fail, SDK disables itself and slots render placeholder or invisible output.