Event Tracking

Event tracking lets you capture user interactions on your website and feed them into the FanFest loyalty and engagement system. Every tracked action can earn points, move users up leaderboards, and trigger toast notifications — all without any backend work on your side.

Tracking works with both Embed-only and SSO integrations. With Embed-only, events are tracked for anonymous sessions. With SSO, events are attributed to identified users for cross-platform analytics.

Two Tracking Methods

The SDK provides two ways to track events:

Method	Best For	Approach
Declarative	CMS, static sites, server-rendered pages	Add data-fanfest-* HTML attributes to elements
Imperative	React, Vue, Angular, SPAs	Call FanFestSDK.trackEvent() from JavaScript

Both methods produce identical events on the backend. Choose based on your tech stack — or mix them on the same page.

Use declarative when your content is static or managed by a CMS. No JavaScript needed beyond loading the SDK.

Use imperative when you need conditional logic, dynamic data, or integration with your application state.

Public SDK API

The following methods are available on the FanFestSDK global object:

Method	Description
init(options)	Initialize the SDK with your client ID and configuration
trackEvent(payload)	Track a user action programmatically
login()	Trigger silent SSO authentication
logout()	Clear the authenticated user session
registerActionMapping(payload)	Map local action names to FanFest Channel Action IDs

Quick Start

1. Register Your Action Mapping

After initializing the SDK, map your local action names to the Channel Action IDs from your FanFest dashboard:

FanFestSDK.registerActionMapping({
  READ_ARTICLE: "ACTION_ID",       // Replace with your actual Action ID
  NEWSLETTER_SIGNUP: "ACTION_ID",
  BROWSE_TICKETS: "ACTION_ID",
});

The registerActionMapping method accepts three input formats:

// Recommended: bulk record (action name -> channel action ID)
FanFestSDK.registerActionMapping({
  READ_ARTICLE: "ch_action_abc123",
  NEWSLETTER_SIGNUP: "ch_action_def456",
});

// Single mapping object
FanFestSDK.registerActionMapping({
  action: "READ_ARTICLE",
  channelActionId: "ch_action_abc123",
});

// Array of mapping objects
FanFestSDK.registerActionMapping([
  { action: "READ_ARTICLE", channelActionId: "ch_action_abc123" },
  { action: "NEWSLETTER_SIGNUP", channelActionId: "ch_action_def456" },
]);

Action ID Format

Copy the Action ID exactly as shown in your FanFest dashboard. The left side of the mapping is the local name you use in your tracking code.

2. Add Tracking

Declarative — add attributes to HTML elements:

<button
  data-fanfest-track="READ_ARTICLE"
  data-fanfest-on="click"
  data-fanfest-object-id="article-123"
>
  Read More
</button>

Imperative — call the tracking API from JavaScript:

FanFestSDK.trackEvent({
  action: "READ_ARTICLE",
  externalObjectId: "article-123",
});

3. Verify

1. Open your site in a browser
2. Perform the tracked action (click, submit, etc.)
3. Look for the FanFest toast notification confirming the event
4. Check the activity feed in your FanFest channel dashboard

TIP

If the authenticated user on your site matches a FanFest user, the action appears immediately. Otherwise, refresh the FanFest app to see the latest activity.

Next Steps

• Declarative Tracking — Full reference for all 6 HTML data attributes
• Imperative Tracking — trackEvent() TypeScript interface and usage
• Tracking Examples — Real-world patterns for clicks, page views, metadata, and more