Skip to main content
Fanfare configuration starts with three values:
ValuePurpose
organizationIdYour Fanfare organization ID from the dashboard.
publishableKeyA browser-safe publishable key for your integration.
experienceIdThe 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:
PropUse for
organizationIdRequired organization ID.
publishableKeyRequired browser-safe key.
autoRestoreRestore local session on mount. Defaults to true.
autoResumeResume known journeys after restore. Defaults to true.
loadingComponentUI shown while the provider initializes.
localeLocale for built-in component text.
translationsPartial copy overrides.
debugDevelopment 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:
PropUse for
experienceIdRequired experience ID.
autoStartStart the journey when the widget is ready.
checkoutUrlDefault destination after a grant.
onGrantedCustom server handoff or app routing after a grant.
slotsOverride specific journey states.
themePer-widget theme values.
variantSupported widget visual variant.
accessCodeProvide an access code when your page already has one.
autoEnterWaitlistEnter 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

Register web components once before rendering custom elements. 
<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:
FrameworkPrefix
Next.jsNEXT_PUBLIC_
ViteVITE_
AstroPUBLIC_
Create React AppREACT_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