API Reference

Complete reference for the FanFest SDK methods, types, and configuration options.

Global SDK Instance

The SDK is available globally as FanFestSDK:

// Global access after loading the SDK script
window.FanFestSDK.init({ ... });

// Or simply
FanFestSDK.init({ ... });

Methods

init(options)

Initialize the SDK with configuration options.

FanFestSDK.init(options: SDKConfig): void

Parameters:

• options - Configuration object (see Configuration)

Example:

FanFestSDK.init({
  apiKey: "your-api-key",
  clientId: "your-client-id",
  apiBase: "https://api.fanfest.vip",
  appOrigin: "https://fanfest.vip",
});

trackEvent(payload)

Track a custom event programmatically.

FanFestSDK.trackEvent(payload: TrackEventPayload): Promise<TrackEventResponse>

Parameters:

• payload - Event data object (see TrackEventPayload)

Returns:

• Promise<TrackEventResponse> - Event processing result

Example:

const response = await FanFestSDK.trackEvent({
  action: "cta_click",
  description: "Hero CTA",
  externalObjectId: "hero-cta-1",
  metadata: {
    campaign: "BlackFriday",
  },
});

if (response.success) {
  console.log("Event tracked successfully");
}

login()

Initiate user authentication flow.

FanFestSDK.login(): Promise<void>

Example:

await FanFestSDK.login();

logout()

Log out the current user.

FanFestSDK.logout(): Promise<void>

Example:

await FanFestSDK.logout();

registerActionMapping(payload)

Register custom action mappings for event tracking.

FanFestSDK.registerActionMapping(payload: SDKActionRegistryPayload): void

Parameters:

• payload - Action mapping configuration

Example:

FanFestSDK.registerActionMapping({
  action: "custom_click",
  channelActionId: "cta_click",
});

Types

SDKConfig

Configuration options for SDK initialization.

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

Host Function Handlers

hostLoginFn - Host Website Login

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

FanFestSDK.init({
  apiKey: "your-api-key",
  clientId: "your-client-id",
  hostLoginFn: () => {
    // Trigger login on your host website
    window.location.href = "/login"; // Redirect to login page
    // or
    openLoginModal(); // Open login modal
    // or
    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({
  apiKey: "your-api-key",
  clientId: "your-client-id",
  hostRewardsFn: () => {
    // Navigate to your rewards page/section
    window.location.href = "/rewards"; // Redirect to rewards page
    // or
    router.push("/rewards"); // SPA navigation
    // or
    showRewardsSection(); // Show rewards section
  },
});

TrackEventPayload

Event data structure for tracking.

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

TrackEventResponse

Response from event tracking.

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)
}

LocationData

Geographic location information.

interface LocationData {
  latitude: number; // Latitude coordinate
  longitude: number; // Longitude coordinate
  types?: string[]; // Location types
  raw?: string; // Raw location data
}

AuthData

Authentication data for SSO integration.

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

SDKActionRegistryPayload

Action mapping configuration.

interface SDKActionRegistryPayload {
  action: string; // Action name
  channelActionId: string; // Mapped channel action ID
}

Data Attributes

Core Attributes

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

Metadata Attributes

Use data-fanfest-meta-* for custom metadata:

<button
  data-fanfest-track="purchase"
  data-fanfest-meta-campaign="BlackFriday"
  data-fanfest-meta-amount="99.99"
  data-fanfest-meta-currency="USD"
>
  Buy Now
</button>

Event Triggers

Supported Events

Event	Description	Use Case
click	Mouse click events	Buttons, links, CTAs
submit	Form submission	Contact forms, signups
render	Element visibility	View tracking, impressions

Event Modifiers

Modifier	Description	Example
prevent	Prevent default behavior	data-fanfest-on="click:prevent"
once	Fire only once	data-fanfest-on="click:once"
stop	Stop event propagation	data-fanfest-on="click:stop"
capture	Use capture phase	data-fanfest-on="click:capture"

Error Handling

Common Errors

Error	Code	Description	Solution
Invalid SDK options	-	Configuration validation failed	Check required options
SDK not initialized	-	Called before init()	Call init() first
API key not found	-	Missing API key	Provide valid API key
Invalid payload	-	Event data validation failed	Check payload structure

Debug Mode

Enable detailed logging:

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

Static Properties

embedElementId

FanFestSDK.embedElementId: string

Default ID for embed elements.

embedContainerId

FanFestSDK.embedContainerId: string

Default ID for embed containers.

Next Steps

• Examples - Implementation patterns
• Examples - Modifier usage
• Examples - Advanced patterns