Skip to main content

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.

​
Performance Optimization

Optimize your Fanfare integration for fast load times and responsive user experiences.

​
SDK Initialization

​
Lazy Loading

Initialize the SDK only when needed to reduce initial page load time. 
// Lazy load the SDK when entering an experience
async function initializeFanfare() {
  const { FanfareClient } = await import("@fanfare/sdk");

  const client = new FanfareClient({
    publishableKey: "pk_live_...",
    debug: false, // Disable in production
  });

  return client;
}

// Initialize when user navigates to experience
button.addEventListener("click", async () => {
  const client = await initializeFanfare();
  await client.experiences.enter(experienceId);
});

​
Early Initialization for Critical Paths

For pages where users will definitely enter an experience, initialize early. 
// Preconnect to Fanfare services
<link rel="preconnect" href="https://consumer.fanfare.io" />

// Initialize SDK in page header
const fanfare = new FanfareClient({
  publishableKey: "pk_live_...",
});

​
Network Optimization

​
Connection Pooling

The SDK maintains persistent connections for real-time updates. Avoid creating multiple client instances. 
// Good: Single client instance
const client = new FanfareClient({ publishableKey: "pk_live_..." });

// Use the same client throughout your application
export { client };

// Bad: Multiple client instances
function enterExperience(id: string) {
  // Creates new connections each time
  const client = new FanfareClient({ publishableKey: "pk_live_..." });
  return client.experiences.enter(id);
}

​
Handling Rate Limits

The API returns rate limit headers to help you optimize request patterns. 
// Rate limit headers returned by the API
// X-RateLimit-Limit: Maximum requests per window
// X-RateLimit-Remaining: Remaining requests in window
// Retry-After: Seconds to wait if rate limited

// SDK handles rate limits automatically with exponential backoff
// For custom implementations, respect the Retry-After header

​
Caching Strategies

​
Experience Details

Cache experience details to avoid redundant API calls. 
const experienceCache = new Map<string, { data: ExperienceDetails; timestamp: number }>();
const CACHE_TTL = 60000; // 1 minute

async function getExperience(id: string): Promise<ExperienceDetails> {
  const cached = experienceCache.get(id);

  if (cached && Date.now() - cached.timestamp < CACHE_TTL) {
    return cached.data;
  }

  const data = await client.experiences.get(id);
  experienceCache.set(id, { data, timestamp: Date.now() });

  return data;
}

​
Session State

The SDK maintains session state internally. Access it without additional API calls. 
// Get current session state without API call
const session = client.experiences.getActiveSession();
const isInQueue = client.queues.isInQueue(queueId);
const position = client.queues.getPosition(queueId);

​
Real-Time Updates

​
Efficient Event Handling

Subscribe only to events you need. 
// Good: Subscribe to specific events
client.on("queue:position-updated", handlePositionUpdate);
client.on("queue:access-granted", handleAccessGranted);

// Clean up when component unmounts
return () => {
  client.off("queue:position-updated", handlePositionUpdate);
  client.off("queue:access-granted", handleAccessGranted);
};

​
Debounce UI Updates

For rapidly changing data like queue position, debounce UI updates. 
import { debounce } from "lodash";

const updatePosition = debounce((position: number) => {
  setQueuePosition(position);
}, 100); // Update UI at most every 100ms

client.on("queue:position-updated", ({ position }) => {
  updatePosition(position);
});

​
Bundle Size

​
Tree Shaking

Import only the modules you need. 
// Good: Import specific hooks
import { useExperienceJourney } from "@fanfare/sdk-react";

// Avoid: Importing entire package if using only specific features
import * as Fanfare from "@fanfare/sdk-react";

​
Code Splitting

Split Fanfare-related code into separate chunks. 
// Next.js dynamic import
const ExperienceWidget = dynamic(
  () => import("./components/ExperienceWidget"),
  {
    ssr: false,
    loading: () => <LoadingSpinner />
  }
);

​
Monitoring Performance

​
SDK Metrics

The SDK provides performance metrics for monitoring. 
// Access SDK metrics (when debug mode is enabled)
const client = new FanfareClient({
  publishableKey: "pk_live_...",
  debug: process.env.NODE_ENV === "development",
});

// SDK logs timing information for key operations
// [Fanfare] 2024-01-15T10:00:00.000Z [DEBUG] Experience entered in 45ms
Track these metrics in your application:
MetricTargetDescription
SDK initialization time< 100msTime from import to ready
Experience entry time< 500msTime to enter an experience
Position update latency< 200msReal-time update delivery
Error rate< 0.1%API and SDK errors

​
Production Checklist

const client = new FanfareClient({
  publishableKey: "pk_live_...",
  debug: false, // Ensure this is false in production
});
Use live keys (pk_live_, sk_live_) in production, not test keys.
Wrap Fanfare components in error boundaries to prevent crashes from affecting your entire application.
Set up monitoring for SDK performance metrics and error rates.
Run load tests to verify performance under expected traffic conditions.

​
Next Steps