SDK Introduction

The FanFest Platform enables you to track user engagement and deliver loyalty rewards across your website. This guide will get you up and running in minutes.

Quickstart

Do you want to jump straight into the "How to"? Check out our Quickstart Guide for a step-by-step walkthrough.

Want to see an example implementation with Auth0?

Check out the Auth0 Example Guide for a complete walkthrough of integrating FanFest with Auth0 SSO.

Installation

Add the SDK script to your HTML:

<script src="https://sdk.production.fanfest.vip/1.0.20/esm/fanfest-sdk.esm.js"></script>

Initialize the SDK

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

Your First Event

Method 1: Data Attributes (Declarative)

Add tracking attributes to any HTML element:

<button
  data-fanfest-track="cta_click"
  data-fanfest-on="click"
  data-fanfest-description="Hero CTA"
  data-fanfest-object-id="hero-cta-1"
  data-fanfest-meta-campaign="BlackFriday"
>
  Get Started
</button>

Method 2: Imperative API

Call the tracking method directly:

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

Advanced Tracking Examples

Dynamic tracking with Vue.js components:

<!-- Page-level tracking with render events -->
<div
  :data-fanfest-track="EngagementAction.BROWSED_VIDEOS"
  :data-fanfest-description="EngagementAction.BROWSED_VIDEOS"
  data-fanfest-experience-id="BROWSED_VIDEOS"
  data-fanfest-on="render"
>
  <!-- Video content -->
</div>

<!-- Social sharing with dynamic tracking -->
<button
  v-for="value in socialShare"
  :key="value.name"
  :data-fanfest-track="value.dataFanfestTrack"
  data-fanfest-on="click"
  :data-fanfest-description="`Shared on ${value.name}`"
  :data-fanfest-experience-id="`SHARE_ARTICLE_ON_${value.name.toUpperCase()}`"
>
  <Icon :name="value.icon" />
</button>

Page View Tracking

Automatic (Default)

Page views are tracked automatically when the SDK initializes.

Manual Tracking

For SPAs or custom routing, track page views manually:

// React example
useEffect(() => {
  FanFestSDK.trackEvent({
    action: "page_view",
    description: document.title,
    externalObjectId: window.location.pathname,
  });
}, [location]);

Troubleshooting

Check Console

Open browser dev tools and look for FanFest SDK logs:

// Enable debug logging
FanFestSDK.init({
  // ... your config
  logLevel: "debug", // optional
});

Network Tab

Check the Network tab for requests to /public/external-actions/ingest endpoint.

Common Issues

401 Unauthorized

• Verify your apiKey is correct
• Check that the API key has proper permissions

403 Forbidden

• Ensure your domain is whitelisted
• Verify clientId matches your configuration

Events not tracking

• Check that elements have data-fanfest-track attribute
• Verify SDK is initialized before tracking
• Look for JavaScript errors in console

Debug Mode

Enable detailed logging:

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

Next Steps

• Architecture - Understand how the SDK works
• Quickstart - Get started with step-by-step instructions
• API Reference - Complete method documentation