Glossary
A shared vocabulary for the platform, in plain language. If you read only one page before integrating, read this one. The single most useful idea: a participant does something → you send an event → the platform records a fact → that updates progression (points, badges, tiers, streaks) → which can grant rewards and fire webhooks.
Tenancy & access
- Tenant
- Your isolated account and all its data. Everything you create (engagements, participants, points, rewards) belongs to one tenant, and data never crosses tenant boundaries.
- API key
- A server-only secret that authenticates your backend to the API. Keys start with
bq_live_(production) orbq_test_(test mode). Never ship a key to a browser. See Authentication. - Scope
- What a key or token is allowed to do:
events:write(send events),gamify:read(read state),gamify:write(move value), andadmin(management, incl. minting participant tokens). Grant the least a key needs. - Participant token
- A short-lived JWT (default 5 minutes, clamped to 1–60) that lets a browser act as one specific participant. Minted on your server with an admin-scoped key and passed to the SDK. It carries scopes and is pinned to a single participant.
The event spine
- Participant
- A person in your product, identified by a
participant_idthat you choose (usually your own user id). All progression is tracked per participant. - Event
- A signal that something happened, sent to
POST /gamify/events(e.g.activity.completed, or your own custom name likepurchase_completed). Ingestion is synchronous: rules and progression are applied before the response returns. See Events. - Fact
- The durable, internal record the platform writes from an event. Facts are the “spine” every mechanic reads from — challenges, contests, and progression all evaluate against facts, not raw events.
- Idempotency key
- A value you attach to an event so a retry is not double-counted. Send the same key and the platform returns the original result marked
duplicate. Essential for safe retries. - Activity
- A single interactive step a participant does inside an engagement (a quiz, poll, form, spin wheel, and so on). Completing an activity typically produces an event like
activity.completed.
Progression (state that accrues)
- Progression
- The umbrella term for the state that builds up as a participant acts: points, tiers, badges, streaks, and milestones. It is calculated from facts, and you read it back with the data hooks or the state API.
- Points
- A running numeric balance. Points can be awarded by rules and spent on rewards. Real event:
points.awarded.v1. - Tier
- A named level (e.g. Bronze/Silver/Gold) a participant reaches based on points or other criteria. Real event:
tier.changed.v1. - Badge
- A one-time achievement a participant unlocks. Real event:
badge.earned.v1. - Streak
- A count of consecutive qualifying days. Day boundaries are UTC. Streaks advance through explicit records, not automatically from every event.
- Milestone
- A threshold on an accumulating metric (e.g. total spend). When reached, it fires
milestone.reached.v1; you grant any reward in your handler.
Engagement mechanics
- Engagement
- A built experience a participant interacts with (a quiz campaign, an onboarding flow, a spin-to-win). Engagements are configured in the Builder and rendered via an embed or the SDK.
- Challenge
- A goal with one or more objectives that a participant progresses toward over time (e.g. “complete 5 lessons”). Configured in the dashboard.
- Contest
- A time-boxed competition with scoring and prizes (e.g. a weekly leaderboard tournament). Lifecycle and prize allocation run on background workers.
- Reward
- Something of value a participant earns or redeems: a coupon, voucher, physical/digital item, or points multiplier. Real event:
reward.claimed.v1. - Leaderboard
- A ranked list of participants by a metric. General leaderboard reads are served from a cache and can be up to ~30s stale. See Known Limitations.
Integration & delivery
- Embed
- The no-code ways to render an engagement in your page: a script tag or an iframe. Fastest to ship; least UI control.
- Managed render (React SDK)
- The React SDK renders Bricqs-built UI inside your app via components. Bricqs owns the UI; you own placement and callbacks.
- Headless SDK
- Hooks that return data, state, and handlers with zero UI, so you build your own components. Maximum control; you own all rendering.
- Webhook (outbound)
- A signed HTTP callback Bricqs sends to your server when something happens (a badge earned, a reward claimed). Deliveries are retried but not ordered; process them idempotently. See Webhooks.
- Streaming (SSE)
- A live, per-participant feed of progression events over Server-Sent Events, consumed with
useBricqsStream. See Live Updates.