SDK Architecture
The FanFest Platform provides a comprehensive engagement and loyalty system for your website, handling user authentication, event tracking, and loyalty rewards through the FanFest SDK.
System Architecture
The platform involves four main components:
- Host Site - Your website or application
- Host SSO Provider - Your authentication system (Auth0, Keycloak, etc.)
- FanFest SDK - The JavaScript library running in the browser
- FanFest API - The backend services processing events and rewards
Authentication Flow
The SDK supports multiple authentication patterns:
Silent Authentication
For users already logged into your system, the SDK can silently authenticate with FanFest using your existing session.
OAuth Integration
The SDK can initiate OAuth flows with supported providers to create FanFest accounts.
Anonymous Mode
Users can interact with tracked content without authentication, with limited reward capabilities.
Event Processing
Event Collection
Events are collected through:
- Data attributes on HTML elements
- Imperative API calls in JavaScript
- Automatic page view tracking
Event Delivery
Events are sent to the FanFest API with:
- Automatic retry on network failures
- Batching for performance optimization
- Deduplication to prevent duplicate events
Privacy & PII
The SDK is designed with privacy in mind:
- No PII collection in event metadata
- Opaque user IDs for tracking
- Configurable data retention
Sequence Diagram
Component Responsibilities
| Component | Responsibilities |
|---|---|
| Host Site | Render content, trigger events, manage user sessions |
| Host SSO | Authenticate users, provide identity tokens |
| FanFest SDK | Track events, manage authentication, display rewards |
| FanFest API | Process events, calculate rewards, manage user data |
Authentication & Session Management
The SDK handles authentication through multiple channels:
- Silent authentication using existing SSO sessions
- OAuth flows for new user registration
- Session persistence across page reloads
- Token refresh for long-lived sessions
Event Delivery & Retry
Events are processed with reliability guarantees:
- Automatic retry with exponential backoff
- Offline queuing for network failures
- Batch processing for performance
- Duplicate detection to prevent data corruption
Privacy & Data Boundaries
The SDK maintains clear data boundaries:
- No PII in events - only opaque identifiers
- Configurable retention for analytics data
- User consent for reward notifications
- Data minimization principles
Next Steps
- Quickstart - Get started with step-by-step instructions
- API Reference - Complete method documentation
- Examples - Implementation patterns