BricqsBricqs
Documentation

iframe Embed

Maximum isolation. A single HTML tag that works anywhere iframes are supported, CMS platforms, email builders, or environments where script injection is restricted.

Quick Start

<iframe
  src="https://YOUR_APP_DOMAIN/e/YOUR_ENGAGEMENT_UUID"
  width="100%"
  height="600"
  frameborder="0"
  allow="clipboard-write"
  style="border: none; max-width: 100%;"
></iframe>

Replace YOUR_ENGAGEMENT_UUID with the UUID from the Builder's Publish tab.

URL Format

The iframe URL accepts query parameters for configuration:

https://YOUR_APP_DOMAIN/e/{ENGAGEMENT_UUID}?param1=value1&param2=value2
ParameterTypeDescription
userIdstringYour application's user ID for cross-device session linking.
userNamestringDisplay name for leaderboards.
userEmailstringUser email for reward delivery.
themestringlight, dark, or auto.
localestringLocale code (e.g. en-US).
hideHeaderbooleanSet to true to hide the engagement header/title bar.
hideFooterbooleanSet to true to hide the Bricqs branding footer.
Example with parameters
<iframe
  src="https://YOUR_APP_DOMAIN/e/a1b2c3d4-e5f6-7890?userId=user_123&userName=Jane%20Doe&theme=light"
  width="100%"
  height="600"
  frameborder="0"
  allow="clipboard-write"
  style="border: none;"
></iframe>

Sizing & Responsive Layout

Fixed Height

Set a fixed pixel height. The content scrolls within the iframe if it exceeds this height.

<iframe
  src="https://YOUR_APP_DOMAIN/e/YOUR_UUID"
  width="100%"
  height="600"
  style="border: none;"
></iframe>

Responsive Container

Wrap the iframe in a responsive container to control max-width and centering.

<div style="max-width: 640px; margin: 0 auto;">
  <iframe
    src="https://YOUR_APP_DOMAIN/e/YOUR_UUID"
    width="100%"
    height="700"
    style="border: none; border-radius: 12px; box-shadow: 0 4px 24px rgba(0,0,0,0.08);"
  ></iframe>
</div>

Auto-Resize with Script Helper

For auto-resize without the full embed script, use the lightweight resize helper:

<iframe
  id="bricqs-frame"
  src="https://YOUR_APP_DOMAIN/e/YOUR_UUID"
  width="100%"
  style="border: none;"
></iframe>

<script>
  window.addEventListener('message', function(e) {
    if (e.origin !== 'https://YOUR_APP_DOMAIN') return;
    if (e.data.type === 'bricqs:resize') {
      document.getElementById('bricqs-frame').style.height = e.data.height + 'px';
    }
  });
</script>

PostMessage Communication

The iframe sends PostMessage events for key engagement milestones. Always verify the origin before processing.

window.addEventListener('message', function(event) {
  // Security: always check origin
  if (event.origin !== 'https://YOUR_APP_DOMAIN') return;

  var msg = event.data;
  switch (msg.type) {
    case 'bricqs:resize':
      // Auto-resize the iframe
      document.getElementById('my-iframe').style.height = msg.height + 'px';
      break;

    case 'bricqs:activity:completed':
      // Activity finished
      console.log('Activity:', msg.payload.activityType);
      console.log('Score:', msg.payload.score);
      break;

    case 'bricqs:points:awarded':
      console.log('Points:', msg.payload.points);
      console.log('New balance:', msg.payload.newBalance);
      break;

    case 'bricqs:badge:unlocked':
      console.log('Badge:', msg.payload.badgeName);
      break;

    case 'bricqs:reward:claimed':
      console.log('Reward:', msg.payload.rewardName);
      console.log('Code:', msg.payload.codeValue);
      break;

    case 'bricqs:engagement:completed':
      console.log('Engagement fully completed');
      break;

    case 'bricqs:ready':
      console.log('Iframe loaded and ready');
      break;
  }
});
Message TypePayload
bricqs:readyEmpty, the iframe has loaded and is ready.
bricqs:resize{ height: number }, content height in pixels.
bricqs:activity:completed{ activityType, activityId, score?, passed? }
bricqs:points:awarded{ points, newBalance, reason }
bricqs:badge:unlocked{ badgeCode, badgeName, badgeIcon }
bricqs:reward:claimed{ rewardName, rewardType, codeValue, expiresAt }
bricqs:engagement:completed{ engagementId, completedAt }

Recommended iframe Attributes

<iframe
  src="https://YOUR_APP_DOMAIN/e/YOUR_UUID"
  width="100%"
  height="600"
  frameborder="0"
  allow="clipboard-write"
  loading="lazy"
  referrerpolicy="no-referrer-when-downgrade"
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms"
  style="border: none;"
  title="Bricqs Engagement"
></iframe>
AttributePurpose
allow="clipboard-write"Lets users copy reward codes and share links.
loading="lazy"Defers loading for below-the-fold embeds (native browser lazy loading).
sandboxRestricts iframe capabilities for security. The listed permissions are the minimum required.
titleAccessibility, describes the iframe for screen readers.

When to Use iframe vs. Script Tag

Use iframe when...

  • - Your platform doesn't allow custom JavaScript (e.g., email builders, some CMS tools)
  • - You want maximum security isolation between the embed and your page
  • - You need to embed inside a sandboxed environment
  • - You only need basic event communication (PostMessage is sufficient)

Use Script Tag when...

  • - You want automatic height resizing without extra code
  • - You need a richer callback API (global window.Bricqs object)
  • - You want programmatic control (destroy, re-render, get session)
  • - You're embedding on a site where you control the HTML/JS

Next Steps

Script Tag Embed →

Auto-resize, global API, and richer callbacks.

Events Reference →

Complete event types and payload documentation.