FansUnited React Widgets — Documentation

Purpose: Embed mini‑game widgets powered by the FansUnited SDK. The bundle scans for placeholder <div>s with data‑attributes and mounts interactive widgets into them.

Last updated: 2025‑08‑12

1) Overview

Project name: fansunited-react-widgets
Version: 0.3.6
Runtime: Preact 10 (via Vite)
SDK: fansunited-sdk-esm
Output: Single IIFE bundle named → public/docs/fu-r-widgets.js

What it does

• Looks for widget placeholders in the DOM (e.g. a div with a specific data‑attribute data-fu-widget="WIDGET_TYPE").
• Hydrates each placeholder with the correct mini‑game component.
• Uses FansUnited SDK for data/auth.

Note: Core entry is src/fu-r-widgets.jsx (referenced in vite.config.js).

2) Quick Start (Dev & Build)

Install

# Installation
yarn install

Scripts (from package.json)

# Start dev server (Vite)
yarn dev

# Build production bundle (IIFE)
yarn build

# Deploy helper (deploys on jsdelivr.com package fansunited-react-widgets)
yarn deploy

Build output: public/docs/fu-r-widgets.js (global name: FuReactWidgets).

3) Embedding on a Host Website

3.1 Include the bundle

<script src="/path/to/fu-r-widgets.js"></script>

or

<script src="https://cdn.jsdelivr.net/npm/[email protected]/public/docs/fu-r-widgets.js"></script>

Note: There could be a newer version.

Host this file from your CDN/site. The bundle registers a window.FuReactWidgets global.

3.2 Add placeholders

Use simple markup where the widget should appear.

<!-- Example placeholder -->
<div
  data-fu-widget="poll"
  data-fu-content-id="POLL_ID"
></div>

Attribute schema:

• data-fu-widget — widget type (e.g. poll, poll-lists, classic-quiz, classic-quiz-lists, article-topx-widget, topx-game, match-quiz, match-quiz-lists, match-quiz-card, my-leaderboard, trophies).
• data-fu-content-id — (used on some widgets) The id of the selected widget.

Each widget can have its own exclusive attributes.

3.3 Initialization

Auto‑init: the bundle scans on DOMContentLoaded and mounts automatically.

<script>
  // Example
  document.addEventListener("DOMContentLoaded", function() {
      FuReactWidgets.init({
          fansUnited: {
              apiKey: "FANS_UNITED_API_KEY",
              clientId: "FANS_UNITED_PROJECT_NAME",
              lang: "LANGUAGE_CODE" // Two-letter ISO 639-1
          },
          labels: { // JSON with the translation labels
              "next":"Seguinte",
              "previous":"Anterior"
          }, 
          routes: { // Your project's routes
              loginUrl: '/oauth/ringier-connect/redirect-to-login',
              matchQuiz: {
                  url: "/fans-arena/match-quiz/{id}",
              },
              classicQuiz: {
                  url: "/fans-arena/classic-quiz/{id}",
              },
          },
      });
  });
</script>

4) Project Structure

• src/fu-r-widgets.jsx — Entry that exposes the scanning and initialization logic.
• src/App.jsx / src/main.jsx — local demo/app shell (not shipped in the IIFE).
• src/components/
  • ProgressBar.jsx, GenericPopup.jsx, LeadPopup.jsx, UnloggedPopupComponent.jsx — shared UI used by widgets.
• Other feature folders (Quizzes, Leaderboards, Poll, etc.) as referenced by Vite aliases in vite.config.js.

Aliases (from vite.config.js): @assets, @classic-quiz, @components, @helpers, @leaderboards, @match-quiz, @services, @topx, @trophies, @pages, @poll.

5) Styling & Theming

• Ship scoped CSS with BEM‑like prefixes (e.g., .fu-r-widget__*).
• All CSS rules are included in src/fu-r-widgets.scss
• During build time, the css is compiled and included in fu-r-widgets.js
• On initialization the script is injecting the CSS into the website's header.

6) Deployment

• yarn build → public/docs/fu-r-widgets.js.
• yarn deploy → Push to jsdelivr.net CDN; version using the package version (e.g., /0.3.6/public/docs/fu-r-widgets.js).

7) Host Integration Cheatsheet

<!-- 1) Include the bundle -->
<script src="https://cdn.jsdelivr.net/npm/[email protected]/public/docs/fu-r-widgets.js"></script>

<!-- 2) Include the initialization script -->
<script>
    document.addEventListener("DOMContentLoaded", function() {
        FuReactWidgets.init(config) // See chapter 3.3 for config details
    });
</script>

<!-- 3) Place a placeholder where you want the widget -->
<div data-fu-widget="poll" data-fu-content-id="RXTgvgN8srpgQBInhZdv7"></div>

8) Widget placeholder reference

<!-- Poll List -->
<div 
    data-fu-widget="poll-lists" 
    data-limit="50"
></div>

<!-- Poll Widget -->
<div 
    data-fu-widget="poll" 
    data-fu-content-id="POLL_ID"
></div>

<!-- Classic Quiz List -->
<div
    data-fu-widget="classic-quiz-lists"
    data-fu-splash="false" <!-- overlay on start: "true"; no splash: "false" (default); redirect flow: "redirect"; overlay above section: "above" -->
></div>

<!-- Classic Quiz Widget -->
<div
    data-fu-widget="classic-quiz"
    data-fu-content-id="CLASSIC_QUIZ_ID"
    data-fu-splash="false" <!-- same options as Classic Quiz List -->
></div>

<!-- Match Quiz List -->
<div 
    data-fu-widget="match-quiz-lists" 
    data-limit="2"
></div>

<!-- Match Quiz Card (displays a card that redirects to the actual match quiz)-->
<div
    data-fu-widget="match-quiz-card"
    data-fu-content-id="MATCH_QUIZ_ID"
></div>

<!-- Match Quiz Widget -->
<div
    data-fu-widget="match-quiz"
    data-fu-content-id="MATCH_QUIZ_ID"
    data-fu-slider="true" <!-- true if we want the quiz to be a slider or false to display all questions vertically -->
></div>

<!-- Top X Game (the current Top X game, we can have only one at a time) -->
<div data-fu-widget="topx-game"></div>

<!-- Article TopX Widget -->
<div
    data-fu-widget="article-topx-widget"
    data-fu-content-id="TOPX_ID"
></div>

<!-- Leaderboards -->
<div
    data-fu-widget="my-leaderboard"
    data-leaderboard="LEADERBOARD_ID"
    data-limit="5" <!-- how many players to display -->
    data-paginated="true" <!-- or false for no pagination -->
    data-type="topx" <!-- type of the leaderboard, if it is TopX we display current season and overall stats -->
></div>

<!-- Trophies -->
<div 
    data-fu-widget="trophies" 
    data-type="all" <!-- all | all-simple | topX -->
></div>

9) Appendix

• Dependencies: axios, dayjs, js-cookie, jwt-decode, firebase, wouter, fansunited-sdk-esm.
• Dev tooling: Vite 7, Prettier, ESLint, Preact preset.