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 app.bricqs.ai/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://app.bricqs.ai/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

A campaign 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.