Headless SDK

Architecture

The Headless SDK is a layer of React hooks that sit on top of the existing SDK infrastructure. Hooks call the Bricqs API through the SDK client, manage state with React, and return typed objects, you render everything yourself.

┌──────────────────────────────────────────────────────┐
│  Your Custom UI (your components, your design system) │
│                                                       │
│  useQuiz()    useSpinWheel()    useForm()             │
│  usePoll()    useSurvey()       useBadgesHeadless()   │
│  usePoints()  useTier()         useChallenge()        │
│  useLeaderboard()               useRewardsHeadless()  │
│  useReferral()  useContest()    useGates()            │
│  useActivityProgress()          useActivityCalendar() │
│                                                       │
│  Returns: data + state + handlers. Zero JSX.          │
├───────────────────────────────────────────────────────┤
│  BricqsProvider (context + SDK client)                │
│                                                       │
│  BricqsClient.activities, validate, complete         │
│  BricqsClient.challenges, enroll, progress           │
│  BricqsClient.leaderboards, rankings                 │
│  BricqsClient.rewards, claimed rewards               │
│  BricqsClient.badges, earned/unearned status         │
│  BricqsClient.points, balance, transactions          │
├───────────────────────────────────────────────────────┤
│  Bricqs API Server                                    │
│                                                       │
│  Activity validation + action execution               │
│  Points, badges, tiers, rewards (atomic, server-side) │
│  Challenge evaluation + progress tracking             │
└───────────────────────────────────────────────────────┘

Quick Start

Build a completely custom quiz UI in 5 minutes. Bricqs handles scoring, point awards, badge unlocks, and reward claims, you handle the rendering.

import {
  BricqsProvider,
  useEngagementData,
  useQuiz,
  usePoints,
} from '@bricqs/sdk-react';

// 1. Wrap your app
function App() {
  return (
    <BricqsProvider config={{ apiKey: 'bq_live_YOUR_KEY' }}>
      <MyCustomQuiz />
    </BricqsProvider>
  );
}

// 2. Load engagement and get quiz config
function MyCustomQuiz() {
  const { getQuizConfig, getComponent, isLoading } = useEngagementData({
    engagementId: 'YOUR_ENGAGEMENT_UUID',
  });

  const quizConfig = getQuizConfig();
  const quizComponent = getComponent('quiz');
  const points = usePoints({ engagementId: 'YOUR_ENGAGEMENT_UUID' });

  if (isLoading || !quizConfig || !quizComponent) {
    return <div>Loading...</div>;
  }

  return (
    <QuizUI
      engagementId="YOUR_ENGAGEMENT_UUID"
      activityId={quizComponent.id}
      config={quizConfig}
      pointsBalance={points.balance}
    />
  );
}

// 3. Build your own quiz UI, zero Bricqs styling
function QuizUI({ engagementId, activityId, config, pointsBalance }) {
  const quiz = useQuiz({ engagementId, activityId, config });

  if (quiz.isComplete) {
    return (
      <div className="my-results">
        <h2>{quiz.feedback?.title}</h2>
        <p>Score: {quiz.score?.percentage}%</p>
        {quiz.actionResults?.points_awarded > 0 && (
          <p className="points">+{quiz.actionResults.points_awarded} points!</p>
        )}
        <button onClick={quiz.reset}>Try Again</button>
      </div>
    );
  }

  return (
    <div className="my-quiz">
      <div className="progress-bar" style={{ width: quiz.progress + '%' }} />
      <p className="balance">{pointsBalance} pts</p>
      <h3>{quiz.currentQuestion.question}</h3>
      <div className="options">
        {quiz.currentQuestion.options.map((opt, i) => (
          <button
            key={i}
            className={quiz.selectedAnswer === i ? 'selected' : ''}
            onClick={() => quiz.selectAnswer(i)}
          >
            {opt}
          </button>
        ))}
      </div>
      <div className="nav">
        {!quiz.isFirstQuestion && <button onClick={quiz.previous}>Back</button>}
        {quiz.isLastQuestion ? (
          <button onClick={quiz.submit} disabled={quiz.isSubmitting}>
            Submit
          </button>
        ) : (
          <button onClick={quiz.next}>Next</button>
        )}
      </div>
    </div>
  );
}

Hook Reference

Detailed API docs for every hook, organized by category.

Server-Side Actions

When a headless activity hook submits (e.g., quiz.submit()), the server executes all configured on-completion actions atomically. The actionResults object contains the outcomes.

// After quiz.submit() resolves:
const results = quiz.actionResults;

// Points
if (results?.points_awarded > 0) {
  showPointsAnimation(results.points_awarded);
}

// Badges
if (results?.badges_unlocked?.length > 0) {
  results.badges_unlocked.forEach(badge => {
    showBadgeUnlocked(badge.name, badge.icon);
  });
}

// Tier upgrade
if (results?.tier_upgrade) {
  showTierCelebration(results.tier_upgrade.new_tier);
}

// Reward claimed
if (results?.reward_claimed) {
  showCouponCode(results.reward_claimed.code_value);
}

// Challenge progress
if (results?.challenge_progress) {
  showProgressUpdate(results.challenge_progress);
}

Full Example: Custom Campaign Page

A complete example with a custom quiz UI, points display, badge shelf, and challenge progress, all with your own design system.

import {
  BricqsProvider,
  useEngagementData,
  useQuiz,
  usePoints,
  useTier,
  useBadgesHeadless,
  useChallenge,
  useLeaderboard,
  useReferral,
  useContest,
  useGates,
  useActivityProgress,
  useActivityCalendar,
} from '@bricqs/sdk-react';

const ENGAGEMENT_ID = 'your-engagement-uuid';

function App() {
  return (
    <BricqsProvider config={{ apiKey: 'bq_live_xxx' }}>
      <CampaignPage />
    </BricqsProvider>
  );
}

function CampaignPage() {
  const { getQuizConfig, getComponent, isLoading } = useEngagementData({
    engagementId: ENGAGEMENT_ID,
  });

  if (isLoading) return <LoadingSpinner />;

  return (
    <div className="campaign-layout">
      <main>
        <QuizSection
          config={getQuizConfig()!}
          componentId={getComponent('quiz')!.id}
        />
      </main>
      <aside>
        <PointsCard />
        <BadgeShelf />
        <ChallengeProgress />
        <TopPlayers />
      </aside>
    </div>
  );
}

function PointsCard() {
  const points = usePoints({ engagementId: ENGAGEMENT_ID });
  const tier = useTier({ engagementId: ENGAGEMENT_ID });

  return (
    <div className="points-card">
      <span className="balance">{points.balance}</span>
      <span className="label">points</span>
      {tier.currentTier && (
        <div className="tier" style={{ color: tier.tierColor || '#666' }}>
          {tier.tierName}, {tier.pointsToNext} pts to {tier.nextTierName}
        </div>
      )}
    </div>
  );
}

function BadgeShelf() {
  const { badges } = useBadgesHeadless({ engagementId: ENGAGEMENT_ID });

  return (
    <div className="badge-shelf">
      {badges.map(badge => (
        <div key={badge.code} className={badge.earned ? 'earned' : 'locked'}>
          <img src={badge.icon} alt={badge.name} />
          <span>{badge.name}</span>
        </div>
      ))}
    </div>
  );
}

function ChallengeProgress() {
  const ch = useChallenge({ engagementId: ENGAGEMENT_ID, autoEnroll: true });
  if (!ch.challenge) return null;

  return (
    <div className="challenge">
      <h3>{ch.challenge.name}</h3>
      <div className="progress-bar">
        <div style={{ width: ch.progressPercentage + '%' }} />
      </div>
      <p>{ch.completedObjectives}/{ch.totalObjectives} objectives</p>
    </div>
  );
}

function TopPlayers() {
  const lb = useLeaderboard({
    code: 'main',
    engagementId: ENGAGEMENT_ID,
    limit: 5,
  });

  return (
    <ol className="leaderboard">
      {lb.entries.map(e => (
        <li key={e.rank}>
          <span className="rank">#{e.rank}</span>
          <span className="name">{e.name}</span>
          <span className="score">{e.score}</span>
        </li>
      ))}
    </ol>
  );
}

Migrating from iframe to Headless