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 20+

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, FixedSurfaceSlot } 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 FixedSurfaceSlot where you want a placement to appear:

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

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

          {/* RevTurbine renders an upgrade banner here — or nothing */}
          <FixedSurfaceSlot
            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 Type | Typical Use | |---|---| | navigate_to_plans | Go to pricing / plan comparison page | | open_checkout_modal | Open Stripe Checkout or your billing flow | | book_demo | Open a sales demo booking form | | custom_url | Navigate to an arbitrary URL | | open_upgrade_modal | Show an upgrade modal | | open_feature_tour | Launch a product tour | | dismiss | Close / 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”