BricqsBricqs
Documentation

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>
That's it. The engagement renders inline, matching the width of its container. No JavaScript initialization, no API keys, no build step.

How It Works

1
Script loads

The embed script (embed.js) loads asynchronously and scans the page for elements with data-bricqs-id attributes.

2
iframe created

For each container found, the script creates an invisible iframe pointing to the Bricqs runtime with your engagement UUID.

3
Auto-resize

The iframe communicates its content height via PostMessage. The script automatically adjusts the iframe height to eliminate scrollbars — no manual sizing needed.

4
Events bubble up

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.

AttributeTypeDescription
data-bricqs-idstringRequired. Your engagement UUID from the Builder's Publish tab.
data-bricqs-user-idstringYour application's user ID. Links the Bricqs session to your authentication system for cross-device tracking.
data-bricqs-user-namestringDisplay name for leaderboards and social features.
data-bricqs-user-emailstringUser email for reward delivery and notifications.
data-bricqs-themestringTheme override. Values: light (default), dark, or auto (follows system preference).
data-bricqs-localestringLocale code (e.g. en-US, fr-FR). Defaults to browser locale.
data-bricqs-heightstringFixed height (e.g. 600px). Disables auto-resize. Useful for scroll-within-iframe layouts.
data-bricqs-lazybooleanSet to true to defer loading until the container scrolls into view. Good for below-the-fold placements.
Example with all attributes
<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.

Next Steps