Configuration

Fanfare configuration starts with three values:

Value	Purpose
`organizationId`	Your Fanfare organization ID from the dashboard.
`publishableKey`	A browser-safe publishable key for your integration.
`experienceId`	The experience your page should render.

Keep secret keys on your server. Client SDK integrations should use publishable keys only.

React Provider

Most React apps configure Fanfare once near the route or app area that renders the experience.

import { FanfareProvider } from "@fanfare-io/fanfare-sdk-react";
import "@fanfare-io/fanfare-sdk-react/styles";

export function App() {
  return (
    <FanfareProvider
      organizationId="org_123"
      publishableKey="pk_live_123"
      locale="en"
    >
      <ProductLaunchPage />
    </FanfareProvider>
  );
}

FanfareProvider initializes the core SDK, restores local session state by default, and provides SDK access to components and hooks below it. Common provider props:

Prop	Use for
`organizationId`	Required organization ID.
`publishableKey`	Required browser-safe key.
`autoRestore`	Restore local session on mount. Defaults to `true`.
`autoResume`	Resume known journeys after restore. Defaults to `true`.
`loadingComponent`	UI shown while the provider initializes.
`locale`	Locale for built-in component text.
`translations`	Partial copy overrides.
`debug`	Development troubleshooting only.

See Configuration Reference for the full public option list.

ExperienceWidget

Configure the journey UI with ExperienceWidget.

import { ExperienceWidget } from "@fanfare-io/fanfare-sdk-react";

export function ProductLaunchPage() {
  return (
    <ExperienceWidget
      experienceId="exp_123"
      autoStart
      checkoutUrl="/checkout"
      variant="clean"
    />
  );
}

Common widget props:

Prop	Use for
`experienceId`	Required experience ID.
`autoStart`	Start the journey when the widget is ready.
`checkoutUrl`	Default destination after a grant.
`onGranted`	Custom server handoff or app routing after a grant.
`slots`	Override specific journey states.
`theme`	Per-widget theme values.
`variant`	Supported widget visual variant.
`accessCode`	Provide an access code when your page already has one.
`autoEnterWaitlist`	Enter waitlist automatically when that public action is available.

Use onGranted when checkout needs a trusted handoff:

<ExperienceWidget
  experienceId="exp_123"
  autoStart
  onGranted={async (admissionGrant) => {
    await fetch("/api/fanfare/admission", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ admissionGrant }),
    });
    window.location.assign("/checkout");
  }}
/>

Copy And Theme

Use provider-level locale and translations for shared copy. Use widget theme, variant, and slots for per-page customization.

<FanfareProvider
  organizationId="org_123"
  publishableKey="pk_live_123"
  locale="en"
  translations={{
    "queue.enter": "Join the launch",
    "granted.cta": "Continue",
  }}
>
  <ExperienceWidget
    experienceId="exp_123"
    variant="rounded"
    theme={{
      primary: "#0F766E",
      fontFamily: "Inter, system-ui, sans-serif",
    }}
  />
</FanfareProvider>

For targeted UI ownership, use slots:

<ExperienceWidget
  experienceId="exp_123"
  slots={{
    granted: ({ grant, expiresAt }) => (
      <CheckoutPanel
        admissionGrant={grant}
        admissionGrantExpiresAt={expiresAt}
      />
    ),
  }}
/>

Core SDK

Use the core SDK when your application owns every screen.

import initFanfare from "@fanfare-io/fanfare-sdk-core";
import type { JourneyView } from "@fanfare-io/fanfare-sdk-core/experiences";

const sdk = await initFanfare({
  organizationId: "org_123",
  publishableKey: "pk_live_123",
});

const journey = sdk.journeys.get("exp_123");

const unsubscribe = journey.view$.listen((view: JourneyView) => {
  renderJourney(view);
});

Call sdk.destroy() when the application area that owns the SDK permanently unmounts.

Web Components

<script type="module">
  import { registerWebComponents } from "@fanfare-io/fanfare-sdk-solid";

  registerWebComponents({
    organizationId: "org_123",
    publishableKey: "pk_live_123",
    locale: "en",
  });
</script>

<fanfare-experience-widget
  experience-id="exp_123"
  auto-start
  checkout-url="/checkout"
></fanfare-experience-widget>

Listen for granted events when the host page needs a custom handoff:

<script>
  const widget = document.querySelector("fanfare-experience-widget");

  widget.addEventListener("fanfare-granted", async (event) => {
    await fetch("/api/fanfare/admission", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ admissionGrant: event.detail.grant }),
    });

    window.location.assign("/checkout");
  });
</script>

Avoid logging admission grants or raw journey snapshots to third-party tools.

Environment Variables

Use framework-supported public environment variables for browser credentials.

NEXT_PUBLIC_FANFARE_ORG_ID=org_123
NEXT_PUBLIC_FANFARE_PUBLISHABLE_KEY=pk_live_123

<FanfareProvider
  organizationId={process.env.NEXT_PUBLIC_FANFARE_ORG_ID!}
  publishableKey={process.env.NEXT_PUBLIC_FANFARE_PUBLISHABLE_KEY!}
>
  <ProductLaunchPage />
</FanfareProvider>

Common public prefixes:

Framework	Prefix
Next.js	`NEXT_PUBLIC_`
Vite	`VITE_`
Astro	`PUBLIC_`
Create React App	`REACT_APP_`

Development And Production

Use test credentials for development and live credentials for production.

const isProduction = process.env.NODE_ENV === "production";

<FanfareProvider
  organizationId={process.env.NEXT_PUBLIC_FANFARE_ORG_ID!}
  publishableKey={
    isProduction
      ? process.env.NEXT_PUBLIC_FANFARE_LIVE_KEY!
      : process.env.NEXT_PUBLIC_FANFARE_TEST_KEY!
  }
>
  <ProductLaunchPage />
</FanfareProvider>;

The SDK chooses its supported public environment by default. Do not set environment or API URL overrides unless your Fanfare contact explicitly asks you to. Only enable debug logging during guided troubleshooting.

Next Steps

Quickstart - Render the first experience.
Testing - Test public journey states.
Configuration Reference - Review the full public option list.

Getting Started

Core Concepts

Distribution Types

React Provider

ExperienceWidget

Copy And Theme

Core SDK

Web Components

Environment Variables

Development And Production

Next Steps

​React Provider

​ExperienceWidget

​Copy And Theme

​Core SDK

​Web Components

​Environment Variables

​Development And Production

​Next Steps

React Provider

ExperienceWidget

Copy And Theme

Core SDK

Web Components

Environment Variables

Development And Production

Next Steps