Getting Started

Everything you need to go from zero to a working Bricqs integration in under 10 minutes.

Prerequisites

A Bricqs Account

Sign up at YOUR_APP_DOMAIN/register. The free Starter plan includes 5,000 participants/month, enough for development and testing.

A Published Engagement

Create an engagement in the Builder (quiz, spin wheel, poll, form, survey, or any combination). Hit "Publish" to make it available for embedding. You'll get an Engagement UUID, this is your unique identifier.

An API Key (for React SDK / Headless SDK only)

Go to Settings → API Keys in the Builder to generate an API key. Keys start with bq_live_ (production) or bq_test_ (testing). Script tag and iframe embeds don't require an API key.

Quick Start: Script Tag (2 minutes)

The fastest way to embed. Works on any website with zero build step.

Step 1, Add the embed script and div

<!-- Add this anywhere in your HTML -->
<script src="https://YOUR_APP_DOMAIN/embed.js"></script>
<div data-bricqs-id="YOUR_ENGAGEMENT_UUID"></div>

Step 2, That's it

The script automatically discovers the div, creates an iframe, and handles auto-resizing. Your engagement renders inline, matching the width of its container.

Where do I find my Engagement UUID?
In the Builder, open your engagement and go to the Publish tab. The UUID is shown in the embed code section. It looks like a1b2c3d4-e5f6-7890-abcd-ef1234567890.

Quick Start: React SDK (5 minutes)

For React/Next.js applications with full TypeScript support.

Step 1, Install the packages

npm install @bricqs/sdk-react @bricqs/sdk-core

Step 2, Wrap your app with the provider

import { BricqsProvider } from '@bricqs/sdk-react';

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

Step 3, Render an engagement

import { BricqsEngagement } from '@bricqs/sdk-react';

function CampaignPage() {
  return (
    <BricqsEngagement
      id="YOUR_ENGAGEMENT_UUID"
      onComplete={(result) => console.log('Done!', result)}
      onPointsAwarded={({ points }) => console.log('+' + points + ' points!')}
      onRewardClaimed={({ rewardName, codeValue }) => {
        showCouponModal(rewardName, codeValue);
      }}
    />
  );
}

Core Concepts

Engagement

An engagement or journey built in the Bricqs Builder. Contains one or more activities (quiz, spin wheel, form, poll, survey) with optional gamification (points, badges, tiers, rewards, challenges). Identified by a UUID.

Activity

An interactive component within an engagement, a quiz, spin wheel, form, poll, or survey. Activities have on-completion actions (award points, unlock badges, claim rewards) that execute atomically on the server.

Session

A unique participant session. Bricqs auto-generates a session ID per browser/device. For identified users, you can pass a user ID to link sessions to your authentication system.

Actions

Server-side side effects that run when an activity completes, award points, unlock badges, emit facts, claim rewards. Configured in the Builder via the on-completion actions panel.

How It Works

┌─────────────────────────────────────────────────────┐
│  Your Website / App                                  │
│                                                      │
│  Integration Layer (script tag / iframe / React SDK) │
│    └── Creates iframe or renders via hooks            │
│                                                      │
│  ┌─────────────────────────────────────────────────┐ │
│  │  Bricqs Runtime (iframe or headless hooks)       │ │
│  │                                                  │ │
│  │  Activities: Quiz, Spin Wheel, Form, Poll, ...  │ │
│  │  Progression: Points, Badges, Tiers, Rewards    │ │
│  │  Challenges: Objectives, Milestones, Leaderboard│ │
│  │                                                  │ │
│  │  PostMessage / API ←→ Bricqs Backend API         │ │
│  └─────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────┘

                        │
                        ▼
            ┌───────────────────────┐
            │  Bricqs API Server     │
            │                       │
            │  Activity validation   │
            │  Action execution      │
            │  Points & rewards      │
            │  Challenge evaluation  │
            │  Fact emission         │
            └───────────────────────┘

Next Steps

Script Tag Embed →

Deep dive into script tag integration with all data attributes and callbacks.

React SDK →

Full React integration with providers, components, and TypeScript types.

Headless SDK →

Build your own UI with headless hooks for full enterprise control.

Events Reference →

Complete list of events, payloads, and integration patterns.