Configuration & Customization

Theming, API key management, environment setup, localization, and advanced configuration options across all integration methods.

API Keys

API keys authenticate your application with the Bricqs backend. Required for the React SDK and Headless SDK; not required for script tag or iframe embeds.

Creating an API Key

Go to Settings → API Keys in the Builder. Click Create API Key, give it a name, and select the scopes. The key is shown once, copy it immediately.

Key Formats (server-only)

bq_live_..., Production key. Use on your backend to mint participant tokens. Never ship to a browser.

bq_test_..., Test key. Use during development. Test data is isolated from production. Also server-only.

Both prefixes are tenant-scoped server credentials. The browser SDK refuses them at construction. Your server holds the key and calls mintParticipantToken from @bricqs/sdk-server to issue short-lived JWTs that the browser SDK consumes.

Security Best Practices

- Store API keys in server-only environment variables (no NEXT_PUBLIC_, no VITE_ prefix)
- Use bq_test_ keys in development, bq_live_ in production
- Rotate keys periodically via Settings → API Keys
- Set per-key rate limits to prevent abuse
- Revoke unused keys immediately

Server-side only: never use NEXT_PUBLIC_ for these keys, that prefix exposes them to the browser.

# .env.local (Next.js / React) — SERVER-SIDE ONLY
BRICQS_ADMIN_API_KEY=bq_live_your_production_key_here

# .env.development
BRICQS_ADMIN_API_KEY=bq_test_your_test_key_here

Environment Configuration

Environment	API Base URL	Runtime URL	Key Prefix
Production	`https://api.bricqs.co`	`https://app.bricqs.co`	`bq_live_`
Testing	`https://api.bricqs.co`	`https://app.bricqs.co`	`bq_test_`
Self-hosted	Your API URL	Your runtime URL	Custom

// React SDK, custom base URL (browser).
// Pair with a server route that calls mintParticipantToken from @bricqs/sdk-server.
<BricqsProvider
  config={{
    getToken: async () => {
      const res = await fetch('/api/bricqs-token');
      return (await res.json()).token;
    },
    apiUrl: 'https://api.your-domain.com', // Self-hosted
    debug: process.env.NODE_ENV === 'development',
  }}
>
  <App />
</BricqsProvider>

Theming & Visual Customization

Customize the look and feel of Bricqs engagements to match your brand. Theming options differ by integration method.

Builder Theme (All Methods)

The primary way to customize appearance. In the Builder, go to Settings → Brand to configure:

Setting	Description
Primary Color	Buttons, active states, and accent elements.
Secondary Color	Secondary buttons, hover states, and backgrounds.
Background	Page background color or gradient.
Font Family	Typography for headings and body text.
Border Radius	Corner rounding for cards, buttons, and inputs.
Logo	Your logo displayed in engagement headers.

CSS Overrides (React SDK)

When using the React SDK, you can target Bricqs elements with CSS for additional customization.

/* Target the engagement container */
.bricqs-engagement {
  border-radius: 16px;
  overflow: hidden;
  box-shadow: 0 4px 24px rgba(0, 0, 0, 0.08);
}

/* Override button styles */
.bricqs-engagement button[data-bricqs-action] {
  font-family: 'Your Font', sans-serif;
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

Full UI Control (Headless SDK)

The Headless SDK gives you 100% control over rendering. No Bricqs CSS is loaded, you build the entire UI with your own design system. See the Headless SDK page.

Session & User Identity

Bricqs automatically manages participant sessions. You can optionally link sessions to your user system.

Anonymous Sessions

By default, Bricqs generates a unique session ID per browser/device. This enables activity tracking, point accumulation, and leaderboard participation without requiring login.

Identified Users

Pass your user ID to link sessions across devices and track individual user journeys.

// Script Tag
<div data-bricqs-id="UUID" data-bricqs-user-id="user_123"></div>

// iframe
<iframe src="https://app.bricqs.co/e/UUID?userId=user_123"></iframe>

// React SDK / Headless SDK
const { sessionStore } = useBricqs();
sessionStore.setUserIdentity({
  userId: 'user_123',
  email: 'jane@example.com',
  displayName: 'Jane Doe',
});

Session Merging

When a userId is provided after an anonymous session, Bricqs automatically merges the anonymous session data (points, badge progress, activity completions) into the identified user's profile.

Localization

Set the locale to display engagement content and system UI in the user's language.

// Script Tag
<div data-bricqs-id="UUID" data-bricqs-locale="fr-FR"></div>

// iframe
<iframe src="https://app.bricqs.co/e/UUID?locale=fr-FR"></iframe>

React / Headless SDK: Locale is configured per-engagement in the Bricqs Builder, or via the runtime URL parameter ?locale=fr-FR.

Supported locales: en-US, en-GB, fr-FR, de-DE, es-ES, pt-BR, ja-JP, ko-KR, zh-CN, ar-SA, hi-IN. Contact us for additional language support.

Content Security Policy

If your site enforces a Content Security Policy, add these directives:

Content-Security-Policy:
  script-src 'self' https://app.bricqs.co;
  frame-src 'self' https://app.bricqs.co;
  connect-src 'self' https://api.bricqs.co;
  img-src 'self' https://YOUR_CDN_DOMAIN https://*.https://app.bricqs.co;

Directive	Required For
`script-src`	Script tag embed (`embed.js`).
`frame-src`	iframe embed and React SDK (which uses iframes).
`connect-src`	React SDK and Headless SDK API calls.
`img-src`	Badge icons, reward images, and engagement media.

Next Steps

Events Reference →

All event types, payloads, and callback patterns.

API Reference →

REST endpoints, authentication, and rate limits.