Platform Overview

This page provides a comprehensive overview of the FanFest Platform architecture, components, and how they work together.

System Components

The FanFest Platform consists of several integrated components:

1. FanFest SDK

A JavaScript library that runs in the user's browser, responsible for:

• Tracking user interactions (clicks, page views, custom events)
• Managing user authentication via SSO integration
• Displaying reward notifications and loyalty updates
• Communicating with the FanFest API

Technology: Vanilla JavaScript, framework-agnostic Integration: Simple script tag or npm package

2. FanFest API

Backend services that process events and manage the platform:

• Event ingestion and processing
• Reward calculation and distribution
• User profile management
• Experience and contest management
• Analytics and reporting

Access: RESTful API, GraphQL for advanced queries Authentication: OAuth 2.0, OIDC-compliant

3. FanFest Admin Dashboard

Web interface for channel administrators:

• Configure SSO integration
• Create and manage shows and contests
• Set up challenges and interactive content
• View analytics and engagement metrics
• Manage channel branding

Access: Web-based at https://fanfest.vipRequires: Channel admin credentials

4. Identity Platform

FanFest's authentication layer that:

• Integrates with your existing SSO provider
• Creates FanFest user profiles linked to your users
• Manages secure token exchange
• Maintains session state

Supported Providers: Auth0, Okta, Azure AD, Keycloak, custom OIDC

---

Architecture Diagram

┌──────────────────────────────────────────────────────────┐
│                      Your Website                         │
│  ┌────────────────────────────────────────────────────┐  │
│  │           FanFest SDK (Browser)                    │  │
│  │  • Event Tracking                                  │  │
│  │  • Authentication Management                       │  │
│  │  • Reward Notifications                            │  │
│  └─────────────┬───────────────────┬──────────────────┘  │
└────────────────┼───────────────────┼─────────────────────┘
                 │                   │
                 │                   │
        ┌────────▼─────────┐  ┌─────▼──────────────┐
        │   Your SSO       │  │   FanFest API      │
        │  (Auth0, etc.)   │  │                    │
        │                  │  │  • Event Process   │
        └──────────────────┘  │  • Rewards Engine  │
                              │  • User Profiles   │
                              │  • Analytics       │
                              └─────┬──────────────┘
                                    │
                           ┌────────▼─────────────┐
                           │  FanFest Dashboard   │
                           │  • Admin Console     │
                           │  • Content Setup     │
                           │  • Analytics View    │
                           └──────────────────────┘

---

Authentication Flow

Silent SSO Authentication

FanFest uses silent authentication to seamlessly integrate with your existing user sessions:

1. User logs into your website via your SSO provider
2. FanFest SDK detects the authenticated session
3. SDK requests an ID token from your SSO provider
4. Token is exchanged with FanFest Identity Platform
5. FanFest creates/updates user profile
6. SDK receives session token for tracking events

Benefits:

• No additional login required
• Seamless user experience
• Secure token exchange
• Privacy-focused (no PII exposure)

---

Event Tracking

How Events are Tracked

Events can be tracked using two methods:

1. Declarative (Data Attributes)

<button 
  data-fanfest-track="newsletter_signup"
  data-fanfest-on="click"
  data-fanfest-description="Footer Newsletter">
  Subscribe
</button>

2. Imperative (JavaScript API)

FanFestSDK.trackEvent({
  action: "newsletter_signup",
  description: "Footer Newsletter",
  metadata: { source: "homepage" }
});

Event Processing Pipeline

User Action → SDK Capture → Validation → API Ingestion 
   → Deduplication → Reward Calculation → User Notification

Key Features:

• Automatic retry on network failures
• Event deduplication
• Batching for performance
• Offline queue support

---

Reward System

How Rewards Work

1. Channel Actions are defined in the FanFest dashboard
2. Each action has associated point values
3. When users complete tracked actions, they earn points
4. Points accumulate in user profiles
5. Users can redeem points for rewards or compete on leaderboards

Reward Types

• Points: Numeric values earned for actions
• Badges: Achievement markers for milestones
• Levels: Progression tiers based on total points
• Leaderboards: Competitive rankings among users

---

Interactive Content

Content Types

The FanFest Platform supports various types of interactive content:

• Shows: Live or recorded content with interactive elements
• Contests: Time-bound competitions with prizes and leaderboards
• Challenges: Achievement-based goals for user engagement
• Threads: Discussion and community content

Content Lifecycle

1. Creation: Create content in the FanFest dashboard
2. Configuration: Set rules, rewards, duration, and visual assets
3. Publishing: Make content live to users
4. Tracking: Monitor engagement and user participation
5. Completion: Award prizes and close time-bound content
6. Analysis: Review analytics and outcomes

---

Data & Privacy

Data Collection

FanFest tracks:

• Event data: Action names, timestamps, context
• User identifiers: Opaque IDs (no PII)
• Metadata: Custom context per event
• Engagement metrics: Aggregated analytics

FanFest does not collect:

• Personal identifiable information (PII)
• Email addresses (unless explicitly provided)
• Payment information
• Sensitive user data

Privacy Features

• Opaque user IDs: No reverse lookup to personal data
• Configurable retention: Control how long data is stored
• GDPR compliance: Right to access, delete, export
• Consent management: User opt-in for notifications

---

Integration Patterns

Standard Website Integration

<!-- Add SDK to your site -->
<script src="https://sdk.production.fanfest.vip/latest/esm/fanfest-sdk.esm.js"></script>

<!-- Initialize -->
<script>
  FanFestSDK.init({
    apiKey: "your-api-key",
    clientId: "your-client-id"
  });
</script>

<!-- Track events with data attributes -->
<button data-fanfest-track="cta_click" data-fanfest-on="click">
  Click Me
</button>

Single Page Application (SPA) Integration

// Install via npm
npm install @fanfest/sdk

// Import and initialize
import FanFestSDK from '@fanfest/sdk';

FanFestSDK.init({
  apiKey: process.env.FANFEST_API_KEY,
  clientId: process.env.FANFEST_CLIENT_ID
});

// Track page views on route change
router.afterEach(() => {
  FanFestSDK.trackEvent({
    action: 'page_view',
    externalObjectId: window.location.pathname
  });
});

---

Performance Considerations

SDK Performance

• Lightweight: ~50KB gzipped
• Async loading: Non-blocking initialization
• Lazy features: Components load on-demand
• Efficient batching: Multiple events in single request

Best Practices

1. Load SDK early but asynchronously
2. Batch related events when possible
3. Use data attributes for static tracking
4. Implement error handling for network failures
5. Test in staging before production

---

Scalability

FanFest is built to scale:

• Auto-scaling infrastructure: Handles traffic spikes
• Global CDN: Fast SDK delivery worldwide
• Event queueing: Reliable event processing
• Rate limiting: Protects against abuse
• High availability: 99.9% uptime SLA

---

Support & Resources

Documentation

• SDK Reference
• API Documentation
• Design Guidelines
• Implementation Examples

Support Channels

• Technical Support: Your onboarding representative
• Dashboard Help: In-app support chat
• Emergency: Contact your account manager

Status & Updates

• System Status: Check dashboard for announcements
• SDK Versions: Updated regularly with improvements
• Release Notes: Available in dashboard

---

Next Steps

• Implement SDK: Get Started
• Design Assets: Create Visuals
• View Examples: Code Samples