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://app.bricqs.ai/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://app.bricqs.ai/e/{ENGAGEMENT_UUID}?param1=value1&param2=value2

Parameter	Type	Description
`userId`	string	Your application's user ID for cross-device session linking.
`userName`	string	Display name for leaderboards.
`userEmail`	string	User email for reward delivery.
`theme`	string	`light`, `dark`, or `auto`.
`locale`	string	Locale code (e.g. `en-US`).
`hideHeader`	boolean	Set to `true` to hide the engagement header/title bar.
`hideFooter`	boolean	Set to `true` to hide the Bricqs branding footer.

Example with parameters

<iframe
  src="https://app.bricqs.ai/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://app.bricqs.ai/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://app.bricqs.ai/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://app.bricqs.ai/e/YOUR_UUID"
  width="100%"
  style="border: none;"
></iframe>

<script>
  window.addEventListener('message', function(e) {
    if (e.origin !== 'https://app.bricqs.ai') 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://app.bricqs.ai') 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 Type	Payload
`bricqs:ready`	Empty — 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://app.bricqs.ai/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>

Attribute	Purpose
`allow="clipboard-write"`	Lets users copy reward codes and share links.
`loading="lazy"`	Defers loading for below-the-fold embeds (native browser lazy loading).
`sandbox`	Restricts iframe capabilities for security. The listed permissions are the minimum required.
`title`	Accessibility — 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.