Skip to content
RevTurbine RevTurbine SDK

Quickstart

This guide walks you through installing the SDK, running in local-only mode, and rendering your first placement — all client-side, no API keys or backend needed.

Before You Begin

Section titled “Before You Begin”
  • A React 18+ application
  • Node.js 22.13+

Steps

Section titled “Steps”

  1. Install the SDK

    @revturbine/sdk is published to the public npm registry — no auth, token, or registry configuration needed.

    Terminal window
    npm install @revturbine/sdk

  2. Add an exported config

    Export your exported_config.json from the RevTurbine dashboard and place it in your src/ directory.

    The exported config contains your plans, entitlements, placements, targeting rules, surface templates, and UI paths — everything the SDK needs to run locally.

  3. Wrap your app in RevTurbineProvider with local runtime

    src/App.tsx
    import { RevTurbineProvider, Slot } from '@revturbine/sdk';
    import exportedConfig from './exported_config.json';
    import { useMemo } from 'react';
    

    function App() {
      const options = useMemo(() => ({
        localRuntime: { exportedConfig },
        user: {
          id: 'user_123',
          context: { plan_handle: 'starter' },
        },
        uiPathResolvers: {
          navigate_to_plans: (ctx) => {
            window.location.href = '/pricing';
          },
          open_checkout_modal: (ctx) => {
            // Open your checkout flow, e.g. Stripe Checkout
            console.log('Checkout for plan:', ctx.plan_handle);
          },
          book_demo: (ctx) => {
            window.open(ctx.url ?? '/sales/demo', '_blank');
          },
          custom_url: (ctx) => {
            if (ctx.url) window.location.href = ctx.url;
          },
        },
      }), []);
    

      return (
        <RevTurbineProvider options={options}>
          <YourApp />
        </RevTurbineProvider>
      );
    }

  4. Add a placement slot

    Drop a <Slot> where you want a placement to appear:

    src/components/Dashboard.tsx
    import { Slot } from '@revturbine/sdk';
    

    function Dashboard() {
      return (
        <div>
          <h1>Dashboard</h1>
    

          {/* RevTurbine renders an upgrade banner here — or nothing */}
          <Slot
            id="dashboard_top_banner"
            surfaceTemplateIds={["banner_placement"]}
          />
    

          {/* Rest of your dashboard */}
        </div>
      );
    }

  5. Verify it works

    Start your dev server. The SDK evaluates targeting rules from the exported config and renders the matching placement for each slot. If no placement matches the current user context, the component renders nothing — that’s the additive principle at work.

What Are UI Paths?

Section titled “What Are UI Paths?”

A UI path is the bridge between a RevTurbine placement and your application’s navigation. When a user clicks a CTA button inside a placement (e.g., “Upgrade Now” or “View Plans”), the SDK doesn’t navigate directly — instead, it invokes a UI path resolver function that you provide, giving your app full control over what happens next.

Each UI path has an action_type that identifies the intent:

Action TypeTypical Use
navigate_to_plansGo to pricing / plan comparison page
open_checkout_modalOpen Stripe Checkout or your billing flow
book_demoOpen a sales demo booking form
custom_urlNavigate to an arbitrary URL
open_upgrade_modalShow an upgrade modal
open_feature_tourLaunch a product tour
dismissClose / dismiss the placement

The resolver receives a context object with any metadata attached in the config (e.g., plan_handle, url, promotion_id). This keeps your conversion flows decoupled from placement content — marketers can change CTA copy and targeting without code changes.

Expected Output

Section titled “Expected Output”

When a placement is configured and the user matches targeting rules, the slot renders the appropriate component — a banner, modal, button, toast, or other surface. When no placement is eligible, it renders nothing.

Next Steps

Section titled “Next Steps”