Which integration path should I pick first?

If you build with React or Next.js and own the surface, start with the headless SDK. For every other stack — native mobile, Vue, Svelte, server-rendered HTML, backend services — start with the REST API. Most production stacks end up using both: SDK on the web, REST API everywhere else, same engine.

Can I switch paths later without losing data?

Yes. Both paths share the same backend engine. The participant ledger, points balance, badges, streaks, and challenge progress are stored once and visible to whichever surface reads them. You can render points via the SDK on the web and via the REST API on iOS for the same participant — they see the same numbers in real time.

Do I need a server to use the headless SDK?

Yes — for minting participant tokens. The SDK never sees your admin key; it consumes a short-lived participant token that you generate server-side by trading your admin key for a per-user token via /api/v1/auth/participant-token. In Next.js this is a single Route Handler; in any other backend it is one HTTP call.

Can I build the entire UI without the SDK using only REST?

Yes. Every state the SDK exposes — points, tier, badges, streaks, leaderboards, rewards, challenges, referrals — is available via REST. A single GET /api/v1/gamify/state/{id} returns the entire participant context in one round-trip. Use polling (or your own SWR/TanStack Query layer) instead of the SDK's revalidation channel for live-ish updates.

How long does a first integration take?

It depends on your auth flow, deploy pipeline, and how much UI you customise — not on Bricqs. The mechanical work the platform asks of you is small: install the SDK or pick your HTTP client, mint participant tokens server-side, drop a Provider or write a fetcher, and POST your first event. From there, timing is bounded by your team's release process. Read the quickstart sections on this page end-to-end first; the longest part is usually wiring it through your existing auth, not the integration itself.

Developer guides

Getting started with gamification

Three integration paths, one decision. Pick the one that matches the surface you are integrating into. Most production stacks combine the SDK and the REST API; the iframe path is the fast lane for marketing-led campaigns. This page covers the decision and ships a working quickstart for all three.

Last updatedMay 2026

Key takeaways

Quick read

Headless SDK is the default for React and Next.js. Hooks render points, tier, badges, streaks, challenges, leaderboards, and rewards in your own UI.
REST API is the default for everything else: native mobile, server-to-server, partner platforms, non-React frontends (Vue, Svelte, server-rendered).
iframe a Bricqs-hosted engagement page when speed beats UI control — marketing-led campaigns, microsites, partner placements.
Switching paths does not lose data. Participant ledger, points, badges, streaks, and challenge progress are stored once and visible to every surface.

The decision

Which path is right

Path	Best for	UI control
Headless SDK	React or Next.js apps where you own the UI. Onboarding flows, in-app challenges, member dashboards.	Full
REST API	Native mobile (iOS, Android), server-to-server scoring, partner platforms, non-React web (Vue, Svelte, server-rendered).	Full
iframe page	Marketing-led campaigns, microsites, partner placements where Bricqs renders the engagement page.	Pre-built

Default rule:SDK for React product surfaces. REST API for everything else. iframe when the marketing team wants to ship without engineering.

Headless SDK

Quickstart for React

Three steps from zero to a working points display.

bash

npm install @bricqs/sdk-react

app/providers.tsx·tsx

"use client";
import { BricqsProvider } from "@bricqs/sdk-react";

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <BricqsProvider
      config={{
        // Server route that mints a short-lived participant JWT with your
        // admin-scoped key (see /guides/build/headless-sdk/setup).
        getToken: async () => {
          const res = await fetch("/api/bricqs/token", { method: "POST" });
          return (await res.json()).token;
        },
      }}
    >
      {children}
    </BricqsProvider>
  );
}

app/components/PointsBadge.tsx·tsx

"use client";
import { usePoints } from "@bricqs/sdk-react";

export function PointsBadge() {
  // autoLoad defaults to false: pass it (or call loadBalance() yourself).
  const { status, balance, lifetime } = usePoints({ autoLoad: true });
  if (status === "loading" || status === "idle") return <span>Loading...</span>;
  return (
    <span className="inline-flex items-center gap-2">
      <strong>{balance.toLocaleString()}</strong> pts
      <small>(lifetime {lifetime.toLocaleString()})</small>
    </span>
  );
}

REST API

Quickstart for any backend

Two steps: send an event, read state.

POST one event·bash

curl -X POST https://api.bricqs.co/api/v1/gamify/events \
  -H "X-API-Key: bq_live_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: p_8a3f:order_4271" \
  -d '{
    "participant_id": "p_8a3f",
    "event_name": "purchase_completed",
    "properties": { "amount": 1250, "currency": "INR" }
  }'

GET participant state·bash

curl "https://api.bricqs.co/api/v1/gamify/state/p_8a3f?include=points,tier,streaks,challenges" \
  -H "X-API-Key: bq_live_..."

# response (sections you did not include are omitted)
{
  "participant_id": "p_8a3f",
  "points": { "balance": 1250, "lifetime": 4820, "redeemed": 3570 },
  "tier": { "code": "silver", "name": "Silver", "level": 2 },
  "streaks": { ... },
  "challenges": { "active_count": 1, "completed_count": 3, "active": [ ... ] }
}

iframe page

Quickstart for iframing a Bricqs-hosted engagement

When the marketing team wants to ship a campaign page without engineering, embed a Bricqs-hosted engagement (quiz, spin, scratch, challenge surface) via iframe. You pass the participant id; Bricqs handles UI, event submission, and reward delivery.

campaign.html·html

<iframe
  src="https://runtime.bricqs.co/embed/YOUR_ENGAGEMENT_UUID"
  width="100%"
  height="640"
  frameborder="0"
  allow="clipboard-write"
></iframe>

<!-- Identified users: mint a participant token server-side and append it,
     so the session is bound to your user instead of an anonymous visitor. -->
<iframe src="https://runtime.bricqs.co/embed/YOUR_ENGAGEMENT_UUID?pt=<participant-token>" ...></iframe>

The engagement is configured in the Bricqs dashboard. Participation, points, and rewards still hit the same ledger as the SDK and REST paths — so a user who completes the iframe campaign on Monday and logs into your app on Tuesday sees the points they earned. Details: iframe embed reference.

Where to go next