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

bq_live_... — Production key. Use in your production environment.

bq_test_... — Test key. Use during development and testing. Test data is isolated from production.

Security Best Practices

- Store API keys in environment variables, never in source code
- 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

# .env.local (Next.js / React)
NEXT_PUBLIC_BRICQS_KEY=bq_live_your_production_key_here

# .env.development
NEXT_PUBLIC_BRICQS_KEY=bq_test_your_test_key_here

Environment Configuration

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

// React SDK — custom base URL
<BricqsProvider
  config={{
    apiKey: process.env.NEXT_PUBLIC_BRICQS_KEY!,
    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.ai/e/UUID?userId=user_123"></iframe>

// React SDK
<BricqsProvider config={{ apiKey: 'key', userId: user.id }}>

// Headless SDK — same as React SDK
<BricqsProvider config={{ apiKey: 'key', userId: user.id }}>

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.ai/e/UUID?locale=fr-FR"></iframe>

// React SDK
<BricqsProvider config={{ apiKey: 'key', 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.ai;
  frame-src 'self' https://app.bricqs.ai;
  connect-src 'self' https://api.bricqs.ai;
  img-src 'self' https://cdn.bricqs.ai https://*.bricqs.ai;

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.