API Overview

The FanFest Platform provides a comprehensive API for tracking user engagement and managing loyalty rewards. This section covers the core concepts and data models.

Event Model

Every tracked event follows a consistent structure:

interface TrackEventPayload {
  action: string; // Event name (e.g., 'cta_click', 'page_view')
  description?: string; // Human-readable description
  externalExperienceId?: string; // Experience/channel identifier
  externalObjectId?: string; // Object being interacted with
  location?: LocationData; // Geographic location (optional)
  metadata?: Record<string, string | number | boolean>; // Custom data
}

Comprehensive Event Tracking

Here's how to implement comprehensive event tracking across different engagement types:

// Engagement actions enum
enum EngagementAction {
  PURCHASED_ITEM = "PURCHASED_ITEM",
  PODCAST_COMPLETE = "PODCAST_COMPLETE",
  BROWSED_TICKETS = "BROWSED_TICKETS",
  LOCATION_CHECK_IN = "LOCATION_CHECK_IN",
  NEWSLETTER_SIGNUP = "NEWSLETTER_SIGNUP",
  VIDEO_WATCH = "VIDEO_WATCH",
  ARTICLE_READING = "ARTICLE_READING",
  PLAYED_GAME = "PLAYED_GAME",
  SHARE_VIDEO_ON_X = "SHARE_VIDEO_ON_X",
  SHARE_ARTICLE_ON_FACEBOOK = "SHARE_ARTICLE_ON_FACEBOOK",
  // ... 50+ more engagement actions
}

// Real tracking examples
FanFestSDK.trackEvent({
  action: EngagementAction.EXPERIENCE_CHECK_IN,
  description: "Stadium Tour",
  externalExperienceId: "stadium-tour",
  externalObjectId: "stadium-tour",
  metadata: {},
});

FanFestSDK.trackEvent({
  action: EngagementAction.SHARE_VIDEO_ON_X,
  description: "Shared on X",
  externalExperienceId: "SHARE_VIDEO_ON_X",
  metadata: {
    videoId: "match-highlights-2024",
    platform: "X",
  },
});

Event Response

interface TrackEventResponse {
  success: boolean; // Whether the event was processed
  didReward: boolean; // Whether the user received a reward
  message?: string; // Optional success/error message
  rewardData?: RewardData; // Reward details (if applicable)
}

Configuration Options

Required Options

interface SDKConfig {
  clientId: string; // Your FanFest client ID
}

Optional Options

interface SDKConfig {
  apiBase?: string; // API endpoint (default: 'https://api.fanfest.vip')
  appOrigin?: string; // FanFest app origin (default: 'https://fanfest.vip')
  iframe?: {
    backgroundColor?: string; // Iframe background color
  };
  hostLoginFn?: () => void; // Triggers login on host website
  hostRewardsFn?: () => void; // Navigates to rewards page/section
}

Host Function Handlers

The SDK provides two optional host function handlers for integration with your website:

hostLoginFn - Host Website Login

Called when the SDK needs to trigger authentication on your host website:

FanFestSDK.init({
  clientId: "your-client-id",
  hostLoginFn: () => {
    window.location.href = "/login"; // Redirect to login page
    openLoginModal(); // Open login modal
    initiateOAuthFlow(); // Start OAuth flow
    authStore.login(); // Trigger auth store login
  },
});

hostRewardsFn - Navigate to Rewards Section

Called when the SDK needs to navigate to your rewards page or section:

FanFestSDK.init({
  clientId: "your-client-id",
  hostRewardsFn: () => {
    window.location.href = "/rewards"; // Redirect to rewards page
    router.push("/rewards"); // SPA navigation
    showRewardsSection(); // Show rewards section
  },
});

Data Attributes

The SDK supports declarative tracking through HTML data attributes:

Attribute	Description	Example
data-fanfest-track	Event name to track	data-fanfest-track="cta_click"
data-fanfest-on	Event trigger with modifiers	data-fanfest-on="click:prevent:once"
data-fanfest-description	Human-readable description	data-fanfest-description="Hero CTA"
data-fanfest-experience-id	Experience identifier	data-fanfest-experience-id="homepage"
data-fanfest-object-id	Object identifier	data-fanfest-object-id="hero-cta-1"
data-fanfest-meta-*	Custom metadata	data-fanfest-meta-campaign="BlackFriday"

Event Triggers

Supported Events

• click - Mouse click events
• submit - Form submission events
• render - Element visibility events

Event Modifiers

• prevent - Prevent default behavior
• once - Fire only once
• stop - Stop event propagation
• capture - Use capture phase

Transport & Reliability

Network Layer

Events are sent via HTTP POST to the FanFest API:

POST /public/external-actions/ingest
Content-Type: application/json

{
  "channelActionId": "cta_click",
  "externalExperienceId": "homepage",
  "externalObjectId": "hero-cta-1",
  "timestamp": "2024-01-15T10:30:00Z",
  "location": null,
  "metadata": {
    "campaign": "BlackFriday",
    "source": "fanfest_sdk",
    "sdk_version": "1.0.0"
  }
}

Retry Logic

• Automatic retry on network failures
• Exponential backoff for rate limiting
• Offline queuing for network outages
• Duplicate detection to prevent data corruption

Deduplication

Events are deduplicated based on:

• Session ID
• Event name
• Object ID
• Timestamp window (configurable)

Authentication Integration

SSO Flow

interface AuthData {
  token: string; // SSO token
  userId: string; // User identifier
  email?: string; // User email (optional)
  displayName?: string; // Display name (optional)
}

Session Management

• Silent authentication using existing SSO sessions
• Token refresh for long-lived sessions
• Anonymous mode when authentication fails
• Session persistence across page reloads

Performance Considerations

Batching

Events are automatically batched for performance:

• Multiple events sent in single request
• Configurable batch size and timing
• Priority queuing for important events

Memory Management

• Automatic cleanup of tracked elements
• Event listener optimization for large pages
• Lazy loading of non-critical features

Error Handling

Common Errors

Error	Cause	Solution
401 Unauthorized	Invalid API key	Verify API key configuration
403 Forbidden	Domain not whitelisted	Add domain to FanFest dashboard
429 Too Many Requests	Rate limiting	Implement backoff strategy
Network Error	Connectivity issues	Check network connection

Debug Mode

Enable detailed logging:

FanFestSDK.init({
  clientId: "your-client-id",
  logLevel: "debug", // Enable detailed logging
});

Next Steps

• Declarative vs Imperative Tracking - Choose the right approach
• SDK Methods Reference - Complete method documentation
• Tracking Examples - Implementation patterns