Which integration path should I pick first?

If you build with React or Next.js and own the surface, start with the headless SDK. If you build native mobile or your stack is non-React (Vue, Svelte, server-rendered), start with the REST API. If you need to ship a single campaign in a day with no engineering follow-up, start with the iframe embed. Most production stacks end up using two of the three.

Can I switch paths later without losing data?

Yes. All three 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.

Is the iframe embed customizable?

Yes, within bounds. The embed accepts theme tokens (colors, fonts, border radius, button styles) via URL parameters or the dashboard. For pixel-perfect control over every element, use the headless SDK; for fully bespoke flows that include forms and routing, use the SDK plus the REST API. The embed is intentionally constrained so that marketing teams can ship without engineering review.

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 end up using two of the three over time. This page covers the decision and ships a working quickstart for all three.

Reading time6 minutes

Last updatedMay 2026

Key takeaways

Quick read

Headless SDK is the default for React. Hooks render points, tier, badges, streaks, challenges, leaderboards, and engagement components.
REST API is the default for everything else: native mobile, server-to-server, partner platforms, non-React frontends.
Embed is the fastest path. Drop an iframe, capture the participant id, ship in an afternoon.
Most teams start with embed for an engagement, move to SDK for owned UI, and reach for the API to wire it server-side.
All three paths share the same engine. Switching does not lose data.

The decision

Which path is right

Path	Best for	Effort	UI control
Headless SDK	React apps where you own the UI. Onboarding flows, in-app challenges, member dashboards.	Medium	Full
REST API	Native mobile, server-to-server scoring, partner platforms, non-React web.	Medium	Full
Iframe / embed	Marketing landing pages, single-campaign drops, microsites, partner placements.	Low	Constrained

Default rule:Default pick: SDK for product surfaces, API for mobile and server work, embed for time-bound campaigns.

Headless SDK

Quickstart for React

Three steps from zero to a working points display.

bash

npm install @bricqs/headless-react

app/providers.tsx·tsx

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

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <BricqsProvider
      tenantId={process.env.NEXT_PUBLIC_BRICQS_TENANT!}
      participantToken={getParticipantTokenFromCookie()}
      env="production"
    >
      {children}
    </BricqsProvider>
  );
}

app/components/PointsBadge.tsx·tsx

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

export function PointsBadge() {
  const { available, lifetime, isLoading } = usePoints();
  if (isLoading) return <span>Loading...</span>;
  return (
    <span className="inline-flex items-center gap-2">
      <strong>{available.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/ingest/events \
  -H "Authorization: Bearer bq_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "participant_id": "p_8a3f",
    "event_type": "purchase_completed",
    "attributes": { "amount": 1250, "currency": "INR" },
    "idempotency_key": "p_8a3f:order_4271"
  }'

GET participant state·bash

curl https://api.bricqs.co/api/v1/gamify/state/p_8a3f \
  -H "Authorization: Bearer bq_live_..."

# response
{
  "participant_id": "p_8a3f",
  "points": { "available": 1250, "lifetime": 4820 },
  "tier": { "id": "silver", "label": "Silver" },
  "streaks": [...],
  "active_challenges": [...]
}

Iframe and embed

Quickstart for fastest ship

One script tag, one participant token, zero engineering follow-up.

campaign.html·html

<div id="bricqs-engagement"
     data-tenant="your_tenant_id"
     data-engagement="spring_quiz_2026"
     data-participant="p_8a3f"></div>

<script async src="https://embed.bricqs.co/v1/embed.js"></script>

The embed handles UI, event submission, and reward flow. You provide the participant id; everything else is configured in the dashboard.

Where to go next