view.sequence.enter()} />;
}
if (view.sequence.phase === "participating" && view.sequence.mechanism === "queue") {
return ;
}
if (view.sequence.phase === "granted") {
return ;
}
return Status: {view.sequence.phase}
;
}
function StartState({ onStart }: { onStart: () => void }) {
return (
);
}
function GatedState() {
return (
Complete the required step to continue.
);
}
function EnterableState({ onEnter }: { onEnter: () => void }) {
return (
Access is available.
);
}
function LoadingState() {
return (
Connecting to experience...
);
}
function WaitingState() {
return (
Please keep this page open.
);
}
function AdmittedState({ expiresAt, onExpired }: { expiresAt?: number; onExpired: () => void }) {
const [timeRemaining, setTimeRemaining] = useState("");
useEffect(() => {
if (!expiresAt) return;
const interval = setInterval(() => {
const distance = expiresAt - Date.now();
if (distance <= 0) {
onExpired();
return;
}
const minutes = Math.floor(distance / (1000 * 60));
const seconds = Math.floor((distance % (1000 * 60)) / 1000);
setTimeRemaining(`${minutes}:${seconds.toString().padStart(2, "0")}`);
}, 1000);
return () => clearInterval(interval);
}, [expiresAt, onExpired]);
return (
✓
You're In!
Complete your purchase before time runs out.
{timeRemaining}
);
}
function ErrorState({ message }: { message?: string }) {
return (
Something went wrong
{message || "Please try again."}
);
}
function formatWaitTime(seconds?: number): string {
if (!seconds) return "Calculating...";
const minutes = Math.floor(seconds / 60);
if (minutes < 1) return "Less than a minute";
if (minutes === 1) return "About 1 minute";
if (minutes < 60) return `${minutes} minutes`;
const hours = Math.floor(minutes / 60);
const remainingMins = minutes % 60;
return `${hours}h ${remainingMins}m`;
}
```
## Step 4: Server-Side Validation
### Validation Middleware
```typescript theme={null}
// middleware/fanfare-validation.ts
import { Request, Response, NextFunction } from "express";
import { fanfareAPI } from "../services/fanfare-api";
interface FanfareAdmission {
token: string;
consumerId: string;
experienceId: string;
distributionId: string;
distributionType: string;
expiresAt: number;
}
export async function validateFanfareAdmission(req: Request, res: Response, next: NextFunction) {
const admissionData = req.body.fanfareAdmission;
if (!admissionData) {
// No Fanfare admission required for this item
return next();
}
let admission: FanfareAdmission;
try {
admission = typeof admissionData === "string" ? JSON.parse(admissionData) : admissionData;
} catch {
return res.status(400).json({
error: "INVALID_ADMISSION_DATA",
message: "Invalid admission data format",
});
}
// Check expiration locally first
if (admission.expiresAt < Date.now()) {
return res.status(403).json({
error: "ADMISSION_EXPIRED",
message: "Your access has expired. Please rejoin the experience.",
});
}
// Validate with Fanfare API
try {
const result = await fanfareAPI.validateAdmission({
token: admission.token,
consumerId: admission.consumerId,
distributionId: admission.distributionId,
distributionType: admission.distributionType,
});
if (!result.valid) {
return res.status(403).json({
error: "ADMISSION_INVALID",
message: result.error || "Your access is no longer valid.",
});
}
// Attach validated admission to request
req.fanfareAdmission = admission;
next();
} catch (error) {
console.error("Fanfare validation error:", error);
// Allow checkout to proceed on validation errors
// The order will be validated again at completion
req.fanfareAdmission = admission;
next();
}
}
// Extend Express Request type
declare global {
namespace Express {
interface Request {
fanfareAdmission?: FanfareAdmission;
}
}
}
```
### Checkout API Endpoint
```typescript theme={null}
// routes/checkout.ts
import express from "express";
import { validateFanfareAdmission } from "../middleware/fanfare-validation";
import { fanfareAPI } from "../services/fanfare-api";
import { db } from "../db";
import { orders, fanfareOrders } from "../db/schema";
const router = express.Router();
router.post("/create-order", validateFanfareAdmission, async (req, res) => {
try {
const { items, shippingAddress, paymentMethod } = req.body;
const fanfareAdmission = req.fanfareAdmission;
// Create order in database
const order = await db.transaction(async (tx) => {
// Create main order
const [newOrder] = await tx
.insert(orders)
.values({
customerId: req.user?.id,
items,
shippingAddress,
paymentMethod,
status: "pending",
totalAmount: calculateTotal(items),
})
.returning();
// If Fanfare admission present, store it
if (fanfareAdmission) {
await tx.insert(fanfareOrders).values({
orderId: newOrder.id,
admissionId: fanfareAdmission.token,
experienceId: fanfareAdmission.experienceId,
consumerId: fanfareAdmission.consumerId,
fanfareCompleted: false,
metadata: {
distributionId: fanfareAdmission.distributionId,
distributionType: fanfareAdmission.distributionType,
},
});
}
return newOrder;
});
res.json({
orderId: order.id,
status: order.status,
});
} catch (error) {
console.error("Order creation failed:", error);
res.status(500).json({
error: "ORDER_FAILED",
message: "Failed to create order",
});
}
});
// After payment is confirmed
router.post("/complete-order/:orderId", async (req, res) => {
const { orderId } = req.params;
try {
// Get order with Fanfare data
const fanfareOrder = await db.query.fanfareOrders.findFirst({
where: eq(fanfareOrders.orderId, orderId),
});
if (fanfareOrder && !fanfareOrder.fanfareCompleted) {
// Complete the Fanfare admission
await fanfareAPI.completeAdmission({
distributionId: fanfareOrder.metadata.distributionId,
distributionType: fanfareOrder.metadata.distributionType,
consumerId: fanfareOrder.consumerId,
metadata: {
orderId,
platform: "custom",
completedAt: new Date().toISOString(),
},
});
// Mark as completed
await db
.update(fanfareOrders)
.set({
fanfareCompleted: true,
fanfareCompletedAt: new Date(),
})
.where(eq(fanfareOrders.orderId, orderId));
}
// Update main order status
await db.update(orders).set({ status: "completed" }).where(eq(orders.id, orderId));
res.json({ success: true });
} catch (error) {
console.error("Order completion failed:", error);
res.status(500).json({
error: "COMPLETION_FAILED",
message: "Failed to complete order",
});
}
});
function calculateTotal(items: Array<{ price: string; quantity: number }>): string {
return sumMoney(items.map((item) => multiplyMoney(item.price, item.quantity)));
}
export default router;
```
## Step 5: Webhook Handler
```typescript theme={null}
// routes/webhooks/fanfare.ts
import express from "express";
import crypto from "crypto";
import { fanfareConfig } from "../../config/fanfare";
import { db } from "../../db";
import { fanfareAdmissions, fanfareOrders } from "../../db/schema";
import { eq } from "drizzle-orm";
const router = express.Router();
// Verify webhook signature
function verifySignature(payload: string, signature: string): boolean {
const expected = crypto.createHmac("sha256", fanfareConfig.webhookSecret).update(payload).digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
router.post("/", express.raw({ type: "application/json" }), async (req, res) => {
const signature = req.headers["x-fanfare-signature"] as string;
const payload = req.body.toString();
if (!signature || !verifySignature(payload, signature)) {
return res.status(401).json({ error: "Invalid signature" });
}
const event = JSON.parse(payload);
try {
switch (event.type) {
case "admission.created":
await handleAdmissionCreated(event.data);
break;
case "admission.expired":
await handleAdmissionExpired(event.data);
break;
case "admission.completed":
await handleAdmissionCompleted(event.data);
break;
case "experience.started":
await handleExperienceStarted(event.data);
break;
case "experience.ended":
await handleExperienceEnded(event.data);
break;
default:
console.log("Unhandled Fanfare event:", event.type);
}
res.json({ received: true });
} catch (error) {
console.error("Webhook handler error:", error);
res.status(500).json({ error: "Handler failed" });
}
});
async function handleAdmissionCreated(data: AdmissionEvent) {
// Track admission for analytics
await db.insert(fanfareAdmissions).values({
id: data.admissionId,
consumerId: data.consumerId,
experienceId: data.experienceId,
distributionId: data.distributionId,
distributionType: data.distributionType,
token: data.token,
expiresAt: new Date(data.expiresAt),
status: "active",
});
}
async function handleAdmissionExpired(data: AdmissionEvent) {
await db.update(fanfareAdmissions).set({ status: "expired" }).where(eq(fanfareAdmissions.id, data.admissionId));
// Optionally notify customer
// await sendAdmissionExpiredEmail(data.consumerId);
}
async function handleAdmissionCompleted(data: AdmissionEvent) {
await db
.update(fanfareAdmissions)
.set({
status: "used",
usedAt: new Date(),
})
.where(eq(fanfareAdmissions.id, data.admissionId));
}
async function handleExperienceStarted(data: ExperienceEvent) {
console.log("Experience started:", data.experienceId);
// Update any scheduled notifications or status displays
}
async function handleExperienceEnded(data: ExperienceEvent) {
console.log("Experience ended:", data.experienceId);
// Clean up any related resources
}
interface AdmissionEvent {
admissionId: string;
consumerId: string;
experienceId: string;
distributionId: string;
distributionType: string;
token: string;
expiresAt: string;
}
interface ExperienceEvent {
experienceId: string;
status: string;
}
export default router;
```
## Step 6: Product Configuration API
```typescript theme={null}
// routes/admin/fanfare-products.ts
import express from "express";
import { db } from "../../db";
import { products } from "../../db/schema";
import { eq } from "drizzle-orm";
const router = express.Router();
// Link product to Fanfare experience
router.post("/:productId/fanfare", async (req, res) => {
const { productId } = req.params;
const { experienceId, enabled } = req.body;
await db
.update(products)
.set({
fanfareEnabled: enabled,
fanfareExperienceId: experienceId,
})
.where(eq(products.id, productId));
res.json({ success: true });
});
// Get Fanfare configuration for product
router.get("/:productId/fanfare", async (req, res) => {
const { productId } = req.params;
const product = await db.query.products.findFirst({
where: eq(products.id, productId),
columns: {
fanfareEnabled: true,
fanfareExperienceId: true,
},
});
res.json(product || { fanfareEnabled: false });
});
export default router;
```
## CSS Styles
```css theme={null}
/* css/fanfare.css */
.fanfare-container {
padding: 24px;
border: 1px solid #e0e0e0;
border-radius: 8px;
background: #fafafa;
margin: 20px 0;
}
.fanfare-loading {
text-align: center;
padding: 40px;
}
.fanfare-loading .spinner {
width: 40px;
height: 40px;
border: 3px solid #e0e0e0;
border-top-color: #0066cc;
border-radius: 50%;
animation: spin 1s linear infinite;
margin: 0 auto 16px;
}
@keyframes spin {
to {
transform: rotate(360deg);
}
}
.fanfare-waiting {
text-align: center;
}
.fanfare-waiting .queue-position {
margin-bottom: 20px;
}
.fanfare-waiting .queue-position strong {
display: block;
font-size: 3rem;
color: #0066cc;
}
.fanfare-admitted {
text-align: center;
background: #e8f5e9;
padding: 24px;
border-radius: 8px;
}
.fanfare-admitted .success-icon {
width: 60px;
height: 60px;
background: #4caf50;
color: white;
border-radius: 50%;
display: flex;
align-items: center;
justify-content: center;
font-size: 32px;
margin: 0 auto 16px;
}
.fanfare-admitted .admission-timer {
font-size: 2rem;
font-weight: bold;
color: #e65100;
margin-top: 16px;
}
.fanfare-expired,
.fanfare-error {
text-align: center;
padding: 24px;
background: #ffebee;
border-radius: 8px;
}
.fanfare-not-started .countdown {
font-size: 2rem;
font-weight: bold;
color: #333;
margin-top: 12px;
}
.hidden {
display: none !important;
}
```
## Best Practices
### 1. Handle Network Failures Gracefully
```typescript theme={null}
async function safeCompleteAdmission(params: CompleteAdmissionParams, maxRetries = 3) {
for (let attempt = 1; attempt <= maxRetries; attempt++) {
try {
await fanfareAPI.completeAdmission(params);
return;
} catch (error) {
if (attempt === maxRetries) {
// Queue for later retry
await queueFailedCompletion(params);
console.error("Failed to complete admission, queued for retry");
} else {
await sleep(1000 * attempt); // Exponential backoff
}
}
}
}
```
### 2. Implement Idempotency
```typescript theme={null}
async function completeAdmissionIdempotent(orderId: string, params: CompleteAdmissionParams) {
// Check if already completed
const existing = await db.query.fanfareOrders.findFirst({
where: and(eq(fanfareOrders.orderId, orderId), eq(fanfareOrders.fanfareCompleted, true)),
});
if (existing) {
console.log("Admission already completed for order:", orderId);
return;
}
await fanfareAPI.completeAdmission(params);
await db
.update(fanfareOrders)
.set({
fanfareCompleted: true,
fanfareCompletedAt: new Date(),
})
.where(eq(fanfareOrders.orderId, orderId));
}
```
### 3. Monitor Integration Health
```typescript theme={null}
// Health check endpoint
router.get("/health/fanfare", async (req, res) => {
try {
const response = await fetch(`${fanfareConfig.baseUrl}/health`, {
headers: { "X-Organization-Id": fanfareConfig.organizationId },
timeout: 5000,
});
if (response.ok) {
res.json({ status: "healthy" });
} else {
res.status(503).json({ status: "degraded" });
}
} catch {
res.status(503).json({ status: "unavailable" });
}
});
```
## Troubleshooting
### SDK Not Loading
1. Check if script tag is present in page source
2. Verify no CSP (Content Security Policy) blocks
3. Check browser console for network errors
### Validation Failures
```typescript theme={null}
// Debug validation issues
try {
const result = await fanfareAPI.validateAdmission(params);
console.log("Validation result:", result);
} catch (error) {
if (error instanceof FanfareAPIError) {
console.log("Status:", error.status);
console.log("Code:", error.code);
console.log("Message:", error.message);
}
}
```
### Webhook Not Receiving Events
1. Verify webhook URL is publicly accessible
2. Check webhook secret is configured correctly
3. Test with webhook debugging tools
4. Review server logs for signature mismatches
## What's Next
* [Webhooks Guide](/guides/advanced/webhooks-guide) - Deep dive into webhook handling
* [Error Handling](/guides/advanced/error-handling) - Comprehensive error management
* [Real-time Updates](/guides/advanced/real-time-updates) - Live status updates
## Step 1: Backend Configuration
### Environment Setup
```typescript theme={null}
// config/fanfare.ts
export const fanfareConfig = {
organizationId: process.env.FANFARE_ORGANIZATION_ID!,
secretKey: process.env.FANFARE_SECRET_KEY!,
publicKey: process.env.FANFARE_PUBLIC_KEY!,
baseUrl: "https://api.fanfare.io",
webhookSecret: process.env.FANFARE_WEBHOOK_SECRET!,
};
// Validate configuration on startup
export function validateConfig() {
const required = ["organizationId", "secretKey", "publicKey"];
const missing = required.filter((key) => !fanfareConfig[key as keyof typeof fanfareConfig]);
if (missing.length > 0) {
throw new Error(`Missing Fanfare configuration: ${missing.join(", ")}`);
}
}
```
### Fanfare API Client
```typescript theme={null}
// services/fanfare-api.ts
import { fanfareConfig } from "../config/fanfare";
interface FanfareRequestOptions {
method: "GET" | "POST" | "PUT" | "DELETE";
path: string;
body?: Record