Choose Your Integration
Five ways in, one engine underneath. Every path talks to the same gamification backend and the same published contract, so you can start with an embed and graduate to the SDK or raw REST without migrating data.
Decision matrix
| Path | Best for | Auth in client | Server needed | UI control | Live updates | Ops burden |
|---|---|---|---|---|---|---|
| Script tag embed | Marketing and no-code teams | None in the page (engagement-scoped public runtime) | No | Rendered by the Bricqs runtime; theme configured in the Builder | Polling inside the runtime | Paste the snippet |
| iframe embed | Same, on platforms that restrict scripts (CMS, builders) | None in the page | No | Rendered by the runtime, fully isolated | Polling inside the runtime | Paste one tag |
| React SDK (managed render) | Frontend teams wanting drop-in components | Participant JWT (server mint route required) | Yes: one token-mint endpoint | Managed components with slot-level customization | SSE stream + polling fallback | Mint endpoint + token refresh |
| Headless hooks | Product engineering owning every pixel | Participant JWT (server mint route required) | Yes: one token-mint endpoint | Fully yours; hooks return data only | SSE stream + polling fallback | Mint endpoint + token refresh + your UI |
| REST only | Backends, mobile-native, non-React stacks | API key server-side; participant JWT for user-context calls | Yes | Fully yours | SSE endpoint directly, or poll | Everything explicit; generated OpenAPI + catalogs are the contract |
True on every path
- Value movement is server-only. Awarding points, assigning tiers, and claiming rewards require an API key with the
gamify:writescope; no path moves value from a browser. See Authentication. - Webhooks are path-independent. Any backend can subscribe to progression events regardless of how the frontend integrates. See Webhooks.
- Test mode is a separate tenant.
bq_test_keys hit an isolated sibling tenant with its own data and suppressed webhook sends. - The contract is generated. OpenAPI plus the event and error catalogs are served machine-readable; docs are a projection of them.
Quick guidance
Launching a campaign this week on a marketing site? Script tag. Two lines, no build step, done.
Building gamification into a React product? Start with the React SDK managed components; drop to headless hooks screen-by-screen where you need full design control. Both share the same provider and token flow, so mixing is free.
Native mobile or a non-JS backend? REST-only is a first-class path: the generated OpenAPI spec and the event/error catalogs are the contract, and the SSE endpoint works from any HTTP client.
Anonymous visitors? Embeds and the public challenge/contest read surface work without any credential; gated engagements upgrade to participant tokens when identity matters.