Documentation Index

Fetch the complete documentation index at: https://docs.fanfare.io/llms.txt

Use this file to discover all available pages before exploring further.

​

Common Issues

​

SDK Initialization Issues

​

SDK Not Initializing

1. Missing publishable key
   // Wrong
   const client = new FanfareClient({});
   
   // Correct
   const client = new FanfareClient({
     publishableKey: "pk_live_...",
   });
   
2. Invalid key format
   • Publishable keys start with pk_test_ or pk_live_
   • Secret keys start with sk_test_ or sk_live_
   • Don’t mix test and live keys
3. Client created multiple times
   // Wrong: Creates new client on every render
   function Component() {
     const client = new FanfareClient({ publishableKey: "..." });
   }
   
   // Correct: Single client instance
   const client = new FanfareClient({ publishableKey: "..." });
   function Component() {
     // Use the shared client
   }
   

​

”Already Initialized” Error

// Create client once at app startup
let fanfareClient: FanfareClient | null = null;

export function getClient() {
  if (!fanfareClient) {
    fanfareClient = new FanfareClient({
      publishableKey: process.env.NEXT_PUBLIC_FANFARE_KEY!,
    });
  }
  return fanfareClient;
}

​

Authentication Issues

​

”Unauthorized” Errors (401)

1. Missing authentication header
   // Ensure consumer token is included
   const client = new FanfareClient({
     publishableKey: "pk_live_...",
   });
   
   // Start a session before making authenticated calls
   await client.auth.guest(); // or client.auth.login()
   
2. Expired session
   // Handle session expiration
   client.on("auth:session-expired", async () => {
     await client.auth.refresh();
   });
   
3. Wrong API key type
   • Use publishable keys for client-side SDK
   • Use secret keys only for server-to-server calls

​

Session Not Persisting

1. Check browser storage
   • Ensure cookies/localStorage aren’t blocked
   • Check for private browsing mode
2. Verify session initialization
   // The SDK automatically restores sessions
   const client = new FanfareClient({ publishableKey: "..." });
   
   // Check if session exists
   const session = client.auth.getSession();
   if (!session) {
     await client.auth.guest();
   }
   

​

Experience Entry Issues

​

”Experience Not Found” Error

• Invalid experience ID
• Experience not published
• Experience not yet active

1. Verify the experience ID in your dashboard
2. Check that the experience is published
3. Confirm the experience’s start time has passed

​

”Already in Experience” Error

try {
  const session = await client.experiences.enter(experienceId);
  // session is returned whether new or existing
} catch (error) {
  if (error.code === "ALREADY_IN_EXPERIENCE") {
    // Get existing session
    const session = client.experiences.getActiveSession();
  }
}

​

Queue Not Moving

1. Low throughput: Queue is processing slowly
2. Users ahead: Many users in front are still active
3. Checkout delays: Users are taking time to complete purchases

• Dashboard shows queue activity
• Access grant rate is configured correctly
• No errors in webhook processing

​

Real-Time Update Issues

​

Position Not Updating

1. Check event subscription
   // Ensure you're subscribed to the event
   client.on("queue:position-updated", ({ position }) => {
     console.log("Position updated:", position);
     setPosition(position);
   });
   
2. Verify connection status
   // Check connection state
   client.on("connection:lost", () => {
     showConnectionWarning();
   });
   
   client.on("connection:restored", () => {
     hideConnectionWarning();
   });
   
3. Network issues
   • Check browser console for WebSocket errors
   • Verify no firewall/proxy blocking
   • Try refreshing the page

​

Events Not Firing

1. Enable debug mode
   const client = new FanfareClient({
     publishableKey: "pk_test_...",
     debug: true, // Logs all events
   });
   
2. Check event registration timing
   // Register events before entering experiences
   client.on("queue:position-updated", handler);
   await client.experiences.enter(experienceId);
   
3. Verify handler function
   // Make sure handler is a function
   const handler = (data) => {
     console.log("Event received:", data);
   };
   client.on("queue:position-updated", handler);
   

​

Checkout/Handoff Issues

​

Handoff Token Invalid

1. Token expired: Handoff tokens have a limited validity period
2. Token already used: Each token can only be used once
3. Wrong environment: Token from test mode used in production

// Handle handoff properly
client.on("queue:access-granted", async ({ handoffToken, expiresAt }) => {
  // Check if token is still valid
  if (new Date(expiresAt) < new Date()) {
    showExpiredMessage();
    return;
  }

  // Use token immediately
  window.location.href = `/checkout?token=${handoffToken}`;
});

​

User Kicked from Checkout

• Access window expired
• Session timed out
• Another session took priority

• Show countdown timer in checkout
• Warn users when time is running low
• Implement session keep-alive

​

Mobile-Specific Issues

​

SDK Not Working on Mobile Safari

1. Private browsing mode
   • Storage APIs may be restricted
   • Inform users if detected
2. ITP (Intelligent Tracking Prevention)
   • May affect cross-site storage
   • Use first-party cookies when possible
3. WebSocket restrictions
   // Handle Safari WebSocket limitations
   client.on("connection:error", () => {
     // Fall back to polling if needed
   });
   

​

Touch Events Not Registering

<button
  onClick={handleClick}
  onTouchEnd={(e) => {
    e.preventDefault();
    handleClick();
  }}
>
  Enter Queue
</button>

​

Performance Issues

​

Slow Initial Load

1. Lazy load the SDK
   const client = await import("@fanfare/sdk").then((m) => new m.FanfareClient({ publishableKey: "..." }));
   
2. Preconnect to API
   <link rel="preconnect" href="https://consumer.fanfare.io" />
   

​

Memory Leaks

useEffect(() => {
  const handler = (data) => setPosition(data.position);
  client.on("queue:position-updated", handler);

  return () => {
    client.off("queue:position-updated", handler);
  };
}, []);

​

Getting More Help

1. Enable debug logging and capture the output
2. Note the error code from any error messages
3. Check the SDK Errors reference
4. Check the API Errors reference
5. Contact support with your findings