Tracking Events - Quickstart #3

With your Channel Action created and FanFest integrated into your website, you're ready to start tracking user interactions. This guide will show you how to map your custom actions and add tracking to your website elements.

Step 1: Register Your Action Mapping

First, you need to tell the FanFest SDK about the Channel Action you created in the previous step. Update the SDK initialization code snippet you added earlier to include your action mapping.

Locate the FanFestSDK.registerActionMapping() call in your code and update it with your action:

FanFestSDK.registerActionMapping({
  READ_ARTICLE: "ACTION_ID", // Replace with your actual Action ID

  // Add more actions as needed:
  // NEWSLETTER_SUBSCRIPTION: "...",
  // BROWSE_TICKETS: "...",
});

Action ID Format

The Action ID you copied from the dashboard should be used exactly as shown. You can map multiple actions by adding more entries to the object.

The left side of the mapping (READ_ARTICLE) is your local action name that you'll use in your tracking code. The right side is the actual Channel Action ID from the FanFest dashboard.

Step 2: Add Tracking to Your Website Elements

Now you can add tracking to elements on your website. The FanFest SDK supports two approaches:

Option A: Declarative Attributes (Recommended for CMS/Static Sites)

Add data-fanfest-* attributes directly to your HTML elements. This approach is perfect if you're using a CMS like WordPress or managing static HTML pages.

Example: Track a button click

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

Example: Track a form submission

<form data-fanfest-track="NEWSLETTER_SUBSCRIPTION" data-fanfest-on="submit">
  <input type="email" placeholder="Enter your email" required />
  <button type="submit">Subscribe</button>
</form>

Example: Track when an element becomes visible

<div
  data-fanfest-track="BROWSE_TICKETS"
  data-fanfest-on="render"
  data-fanfest-object-id="tickets-hero"
>
  <h2>Available Tickets</h2>
  <!-- Ticket content -->
</div>

Attribute Reference

Attribute	Required	Description
data-fanfest-track	✅	The local action name (e.g., READ_ARTICLE)
data-fanfest-on	✅	Trigger event: click, submit, or render
data-fanfest-object-id	❌	Unique identifier for the element being tracked
data-fanfest-experience-id	❌	Group related actions (e.g., "checkout-flow")
data-fanfest-meta-*	❌	Custom metadata (e.g., data-fanfest-meta-amount)

Option B: Imperative API (Recommended for React/Vue/SPAs)

If you're building a React, Vue, or Angular application, you can track events programmatically using JavaScript:

// Track a button click
function handleArticleClick(articleId) {
  FanFestSDK.trackEvent({
    action: "READ_ARTICLE",
    description: "User read featured article",
    externalObjectId: articleId,
  });

  // Continue with your app logic
  navigateToArticle(articleId);
}

React Example:

// FanFestSDK is available globally after loading the SDK script
function ArticleCard({ articleId, title }) {
  const handleClick = async () => {
    await FanFestSDK.trackEvent({
      action: "READ_ARTICLE",
      description: `Read article: ${title}`,
      externalObjectId: articleId,
      metadata: {
        title: title,
        category: "featured",
      },
    });

    // Navigate to article
    window.location.href = `/articles/${articleId}`;
  };

  return (
    <div className="article-card">
      <h3>{title}</h3>
      <button onClick={handleClick}>Read More</button>
    </div>
  );
}

Choosing the Right Approach

• Use declarative attributes for simple, static content and CMS-managed pages
• Use imperative API for dynamic SPAs and when you need conditional logic or integration with your app's state

Learn more about both approaches in the Attributes vs Imperative API guide.

Step 3: Test Your Integration

1. Open your website in a browser
2. Login as a user to trigger authentication
3. Perform the action you're tracking (click the button, submit the form, etc.)
4. Check the toast notification from FanFest confirming the event was tracked
5. Visit your FanFest channel page and verify that the event appears in the activity row for the user.

   Refresh the Page

   If the user on the FanFest app matches the user on Your Website, you should see the action reflected there right away, otherwise make sure to refresh the page to see the latest actions.

Continue

🎉 Congratulations! You've successfully integrated FanFest and can now track user engagement on your website.

Proceed to Next Steps to explore advanced features and learn what to do before going to production.