Headless Integration

Use a headless integration when your application owns the full UI and Fanfare supplies the public journey contract. This is the right path for custom storefronts, non-React frameworks, canvas experiences, or any app where the default widget is not the product experience you want to show. Headless integrations should render from JourneyView, call only actions exposed by the current view, and hand admitted customers to your trusted checkout flow without exposing grants in URLs, logs, or third-party analytics.

Install

pnpm add @fanfare-io/fanfare-sdk-core

Initialize Once

Create the SDK in the browser area that owns the customer experience.

import initFanfare from "@fanfare-io/fanfare-sdk-core";

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

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

Call sdk.destroy() only when that application area unmounts permanently.

Render From The Public View

The view is the stable UI contract. It includes the public state and the actions that are valid for that state.

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

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

function renderJourney(view: JourneyView) {
  if (view.journeyStage === "ready") {
    mountStartButton(() => view.start());
    return;
  }

  if (view.journeyStage === "routing") {
    mountLoading();
    return;
  }

  if (view.journeyStage === "gated") {
    mountGate({
      gates: view.gates,
      onAccessCode: (accessCode) => view.reroute({ accessCode }),
      onRetry: () => view.retry(),
    });
    return;
  }

  renderSequence(view.sequence);
}

function renderSequence(sequence: SequenceView) {
  switch (sequence.phase) {
    case "unavailable":
      mountUnavailable();
      return;
    case "scheduled":
      mountUpcoming({ startsAt: sequence.startsAt });
      return;
    case "enterable":
      if ("enter" in sequence) {
        mountEnterButton(() => sequence.enter());
      } else if ("bid" in sequence) {
        mountBidForm((amount) => sequence.bid(amount));
      } else if ("book" in sequence) {
        mountAppointmentPicker((slotId, locationId) =>
          sequence.book(slotId, locationId)
        );
      } else {
        mountUnavailable();
      }
      return;
    case "participating":
      mountParticipation({
        type: sequence.mechanism,
        onLeave: "leave" in sequence ? () => sequence.leave() : undefined,
      });
      return;
    case "settling":
      mountSettling(sequence);
      return;
    case "granted":
      mountCheckout(sequence.grant.token);
      return;
    case "ended":
      mountEnded({ reason: sequence.outcome.type });
  }
}

When your page no longer needs updates, call unsubscribe().

Framework Adapter Pattern

For Vue, Svelte, or vanilla state stores, keep the SDK wrapper small and pass the current view into your application renderer.

export function connectExperience(experienceId: string, onView: (view: JourneyView) => void) {
  const journey = sdk.journeys.get(experienceId);
  const unsubscribe = journey.view$.listen(onView);

  return {
    disconnect: unsubscribe,
  };
}

Your UI layer should still branch on the current view before showing actions.

Admission Handoff

When the view reaches an admitted sequence, send the admission grant to your own backend or trusted checkout boundary.

async function handleAdmission(admissionGrant: string) {
  await fetch("/api/fanfare/admission", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ admissionGrant }),
  });

  window.location.assign("/checkout");
}

Do not put the grant in query strings, screenshots, debug logs, or analytics payloads.

What To Test

Every public state your experience can render.
The presence or absence of buttons based on the current view.
Gated flows with generic customer-safe copy.
Admission handoff through your app boundary.
Cleanup when a route or embedded surface unmounts.

Avoid undocumented SDK mock helpers. For recommended app-boundary testing patterns, see Testing Your Integration and SDK Testing.

Overview

Integration Patterns

Authentication

Checkout Integration

Platform Integrations

Use Cases

Advanced

Install

Initialize Once

Render From The Public View

Framework Adapter Pattern

Admission Handoff

What To Test

Next Steps

​Install

​Initialize Once

​Render From The Public View

​Framework Adapter Pattern

​Admission Handoff

​What To Test

​Next Steps

Install

Initialize Once

Render From The Public View

Framework Adapter Pattern

Admission Handoff

What To Test

Next Steps