Script Tag Embed
The fastest way to add Bricqs to any website. Two lines of HTML — no build step, no framework, no configuration required.
Quick Start
Add these two lines anywhere in your HTML. The script auto-discovers the container div, creates an iframe, and renders your engagement.
<!-- Bricqs Embed — add anywhere in your HTML -->
<script src="https://app.bricqs.ai/embed.js"></script>
<div data-bricqs-id="YOUR_ENGAGEMENT_UUID"></div>How It Works
The embed script (embed.js) loads asynchronously and scans the page for elements with data-bricqs-id attributes.
For each container found, the script creates an invisible iframe pointing to the Bricqs runtime with your engagement UUID.
The iframe communicates its content height via PostMessage. The script automatically adjusts the iframe height to eliminate scrollbars — no manual sizing needed.
Activity completions, point awards, badge unlocks, and reward claims are forwarded to your page via PostMessage events and optional callback attributes.
Data Attributes
Configure the embed behavior with HTML data attributes on the container div.
| Attribute | Type | Description |
|---|---|---|
data-bricqs-id | string | Required. Your engagement UUID from the Builder's Publish tab. |
data-bricqs-user-id | string | Your application's user ID. Links the Bricqs session to your authentication system for cross-device tracking. |
data-bricqs-user-name | string | Display name for leaderboards and social features. |
data-bricqs-user-email | string | User email for reward delivery and notifications. |
data-bricqs-theme | string | Theme override. Values: light (default), dark, or auto (follows system preference). |
data-bricqs-locale | string | Locale code (e.g. en-US, fr-FR). Defaults to browser locale. |
data-bricqs-height | string | Fixed height (e.g. 600px). Disables auto-resize. Useful for scroll-within-iframe layouts. |
data-bricqs-lazy | boolean | Set to true to defer loading until the container scrolls into view. Good for below-the-fold placements. |
<div
data-bricqs-id="a1b2c3d4-e5f6-7890-abcd-ef1234567890"
data-bricqs-user-id="user_12345"
data-bricqs-user-name="Jane Doe"
data-bricqs-user-email="jane@example.com"
data-bricqs-theme="light"
data-bricqs-locale="en-US"
data-bricqs-lazy="true"
></div>Event Callbacks
Listen for events from the embedded engagement using the global window.Bricqs API or PostMessage.
Method 1: Global API (recommended)
<script src="https://app.bricqs.ai/embed.js"></script>
<div data-bricqs-id="YOUR_ENGAGEMENT_UUID" id="my-quiz"></div>
<script>
// Wait for the embed to initialize
window.addEventListener('bricqs:ready', function(e) {
var bricqs = e.detail;
// Activity completed (quiz answered, form submitted, etc.)
bricqs.on('activity:completed', function(data) {
console.log('Activity done!', data.activityType);
console.log('Score:', data.score);
});
// Points awarded
bricqs.on('points:awarded', function(data) {
console.log('+' + data.points + ' points!');
// Update your app's points display
document.getElementById('my-points').textContent = data.newBalance;
});
// Badge unlocked
bricqs.on('badge:unlocked', function(data) {
console.log('Badge earned:', data.badgeName);
showToast('You earned the ' + data.badgeName + ' badge!');
});
// Reward claimed (coupon code, voucher, etc.)
bricqs.on('reward:claimed', function(data) {
console.log('Reward:', data.rewardName);
console.log('Code:', data.codeValue);
showCouponModal(data.codeValue, data.expiresAt);
});
// Tier upgraded
bricqs.on('tier:changed', function(data) {
console.log('New tier:', data.tierName);
});
// Engagement fully completed (all activities done)
bricqs.on('engagement:completed', function(data) {
console.log('All done!');
redirectToThankYou();
});
});
</script>Method 2: PostMessage (advanced)
For environments where global scripts are restricted, you can listen for PostMessage events directly.
window.addEventListener('message', function(event) {
// Always verify the origin
if (event.origin !== 'https://app.bricqs.ai') return;
var data = event.data;
if (data.type === 'bricqs:activity:completed') {
console.log('Activity completed:', data.payload);
}
if (data.type === 'bricqs:points:awarded') {
console.log('Points awarded:', data.payload.points);
}
if (data.type === 'bricqs:reward:claimed') {
console.log('Reward code:', data.payload.codeValue);
}
});Programmatic API
Control the embed programmatically after initialization.
window.addEventListener('bricqs:ready', function(e) {
var bricqs = e.detail;
// Destroy the embed (removes iframe)
bricqs.destroy();
// Re-render with different config
bricqs.render({
engagementId: 'NEW_ENGAGEMENT_UUID',
userId: 'user_456',
});
// Get current session info
var session = bricqs.getSession();
console.log('Session ID:', session.sessionId);
console.log('Participant ID:', session.participantId);
});Multiple Embeds on One Page
You can embed multiple engagements on the same page. Each gets its own iframe and session.
<script src="https://app.bricqs.ai/embed.js"></script>
<!-- Quiz widget -->
<div data-bricqs-id="quiz-uuid-here"></div>
<!-- Spin wheel widget -->
<div data-bricqs-id="spinwheel-uuid-here"></div>
<!-- Leaderboard widget -->
<div data-bricqs-id="leaderboard-uuid-here"></div>The script only needs to be included once. It discovers all containers on the page.
Platform Examples
WordPress
Add a Custom HTML block in the WordPress editor and paste the embed code.
<!-- WordPress Custom HTML Block -->
<script src="https://app.bricqs.ai/embed.js"></script>
<div data-bricqs-id="YOUR_ENGAGEMENT_UUID" style="max-width: 600px; margin: 0 auto;"></div>Shopify
Use the Custom Liquid section or add to your theme's template.
<!-- Shopify Custom Liquid Section -->
<script src="https://app.bricqs.ai/embed.js"></script>
<div
data-bricqs-id="YOUR_ENGAGEMENT_UUID"
data-bricqs-user-id="{{ customer.id }}"
data-bricqs-user-email="{{ customer.email }}"
data-bricqs-user-name="{{ customer.first_name }}"
></div>Webflow / Static HTML
Add the script to your page's custom code section and place the div in an Embed element.
<!-- In <head> or before </body> -->
<script src="https://app.bricqs.ai/embed.js"></script>
<!-- Embed element in your layout -->
<div data-bricqs-id="YOUR_ENGAGEMENT_UUID"></div>Content Security Policy (CSP)
If your site uses 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;Troubleshooting
Engagement doesn't appear
Make sure the engagement is published in the Builder. Draft engagements won't render. Check the browser console for error messages — the embed script logs helpful diagnostics.
Iframe shows but has no content
Verify the engagement UUID is correct (find it in the Builder → Publish tab). Also check that your CSP allows framing from app.bricqs.ai.
Auto-resize not working
Auto-resize relies on PostMessage between the iframe and your page. If you've set a data-bricqs-height attribute, auto-resize is disabled. Also ensure the parent container has no overflow: hidden that could clip the content.
Events not firing
Make sure you're listening for the bricqs:ready event before registering callbacks. The embed might initialize before your event listener is attached — use the global API pattern shown above.
