Embedding Komo

Komo content can live on its own domain or be embedded directly into your website or app. Choose the embedding approach that fits your use case.

Embedding Options

Full Hub Embed

Renders the entire Komo Site (all pages, cards, navigation, and branding) as an embedded iframe within your page. The user gets the full hub experience without leaving your site.

How it works: Link directly to your hub URL or embed it in an iframe. The hub is a fully hosted web destination -- no SDK needed.

<iframe
  src="https://your-hub.komo.site"
  width="100%"
  height="800"
  frameborder="0"
  allow="clipboard-write"
></iframe>

When to use:

• Standalone engagement destination within your app
• Branded microsite embedded in an event platform
• Full-page engagement experiences
• When you want Komo to manage the entire UI

Considerations:

• Takes up significant page real estate
• Branding is controlled in the Komo Portal
• Navigation is Komo's, not yours

Card Cover Embed

Renders a card's cover image and play button inline in your page. When clicked, the full card experience opens in a modal overlay. The cover image is configured in the Komo Portal.

How it works: Add a <div> with two data attributes: a marker attribute and a JSON config. The SDK replaces it with the card's cover image.

<div
  data-komo-embed-card-cover
  data-komo-embed='{
    "cardId": "CARD_ID",
    "styles": {
      "embedStyle": "ImageButton",
      "embedWidth": "unset"
    }
  }'
></div>

When to use:

• Promotional placements in hero sections or sidebars
• Showing a visual preview of the experience
• Email-like layouts with clickable content blocks
• When the card's cover image adds value

Considerations:

• Requires space for the cover image
• Cover design is managed in Komo Portal
• Best when visuals drive engagement

Card Trigger Embed

Attaches card-opening behavior to any existing HTML element. No visual changes -- when the element is clicked, the card opens in a modal. You control the look; Komo provides the behavior.

How it works: Add data-komo-embed-card-trigger with the card ID to any HTML element. The SDK adds a click handler automatically.

<button data-komo-embed-card-trigger="CARD_ID">
  Play the Trivia Challenge!
</button>

<!-- Works on any element -->
<a href="#" data-komo-embed-card-trigger="CARD_ID">
  Take the Quiz
</a>

<div data-komo-embed-card-trigger="CARD_ID">
  <img src="my-promo.jpg" alt="Play to win" />
</div>

When to use:

• Inline CTAs in your existing content
• Buttons in navigation or menus
• Custom-designed card previews
• When you want full control over the visual presentation

Considerations:

• No visual preview of the card unless you build one
• Users need clear indication something will happen on click

Programmatic API

Use JavaScript calls to open, close, and manage card experiences dynamically. Ideal for SPA frameworks (React, Vue, Angular) and dynamic content where you need full programmatic control.

How it works: Call methods on the komoEmbed global. You can register triggers by CSS selector, open/close experiences, and control visibility.

// Register any element as a trigger via CSS selector
komoEmbed.registerCardTrigger('CARD_ID', '#my-button');

// Open a card experience directly
komoEmbed.openExperience({ type: 'card', id: 'CARD_ID' });

// Close, hide, or unhide the modal
komoEmbed.closeExperience();
komoEmbed.hideExperience();    // hides but preserves state
komoEmbed.unhideExperience();  // shows it again

When to use:

• Single Page Applications (React, Vue, Angular)
• Dynamic content where cards are loaded conditionally
• Complex interactions (open card after form submit, etc.)
• When data attributes don't fit your framework

Considerations:

• Requires JavaScript -- won't work with JS disabled
• More code to write and maintain

---

Web (Browser) Embed

Complete reference for embedding Komo into any website. Covers the setup script, data attributes, programmatic API, event listening, form prefilling, extension data, query parameters, and authentication.

Setup Script

Add this script to every page where you want Komo embeds. It creates the komoEmbed global with a proxy-based command queue, then asynchronously loads the full SDK.

<script>
  (function (n, r, t, c, u, e, f) {
    n[u] =
      n[u] ||
      (function (q) {
        return new Proxy(q, {
          get(y, s) {
            return s === 'q'
              ? y[s] || []
              : function (...B) {
                  (n[u].q = n[u].q || []).push([s, ...B]);
                };
          }
        });
      })({});
    e = r.createElement(t);
    f = r.getElementsByTagName(t)[0];
    e.async = 1;
    e.src = c;
    f.parentNode.insertBefore(e, f);
  })(
    window,
    document,
    'script',
    'https://KOMO_HUB_URL/assets/embed/embed.js',
    'komoEmbed'
  );
</script>

Replace KOMO_HUB_URL with your Hub URL (e.g., https://yourbrand.komo.site). The script is loaded asynchronously and won't block page rendering. Thanks to the proxy-based queue, you can call komoEmbed methods immediately -- they'll be replayed once the SDK finishes loading.

Important: All komoEmbed calls must appear below the setup script in your HTML. The setup script creates the global proxy that queues commands -- calling komoEmbed before it runs will result in a ReferenceError.

Card Covers

Render a card's cover image inline. Clicking it opens the full card experience in a modal. Uses two data attributes: data-komo-embed-card-cover (marker, no value) and data-komo-embed (JSON configuration).

<div
  data-komo-embed-card-cover
  data-komo-embed='{"cardId":"CARD_ID","styles":{"embedStyle":"ImageButton","embedWidth":"unset"}}'
></div>

The data-komo-embed-card-cover attribute is a boolean marker (no value). The data-komo-embed attribute takes a JSON string with the card ID and optional style overrides. The SDK fetches the card's cover image and renders it within the <div>.

Style Options:

• embedStyle -- e.g., "ImageButton"
• embedWidth -- e.g., "unset", "500px", "100%"

Card Triggers

Turn any HTML element into a card trigger. Clicking the element opens the card in a modal.

<button data-komo-embed-card-trigger="CARD_ID">Show me Komo!</button>

<a data-komo-embed-card-trigger="CARD_ID" href="#">
  Take the Quiz
</a>

<div data-komo-embed-card-trigger="CARD_ID" class="my-custom-card">
  <img src="my-promo.jpg" alt="Play to win" />
</div>

The trigger doesn't change the element's appearance -- it only adds click behavior. You have full control over the visual design.

Programmatic API

For dynamic scenarios where data attributes aren't practical (SPAs, conditional rendering), use the JavaScript API directly.

registerCardTrigger(cardId, selector) -- Programmatically register a DOM element as a card trigger. The first argument is the card ID, the second is a CSS selector string (not an element reference).

komoEmbed.registerCardTrigger('CARD_ID', '#my-button');

openExperience(config) -- Open a card experience modal programmatically. Takes a configuration object, not a string.

komoEmbed.openExperience({ type: 'card', id: 'CARD_ID' });

closeExperience() -- Close the currently open card experience.

komoEmbed.closeExperience();

hideExperience() -- Hide the modal without closing it. The experience state is preserved -- the user can resume where they left off.

komoEmbed.hideExperience();

unhideExperience() -- Show a previously hidden experience modal.

komoEmbed.unhideExperience();

Event Listening

Receive events from the embedded Komo experience. Use these to trigger actions in your parent page -- analytics, UI updates, navigation, etc. All listenTo* methods return an unsubscribe function you can call to stop listening.

listenToKomoEvents(callback) (Recommended) -- Listen to structured Komo events. The callback receives an object with eventName and eventData properties.

const unsubscribe = komoEmbed.listenToKomoEvents((event) => {
  console.log('Komo event received:', event);
  // event has structure: { eventName: string, eventData: any }
});

// To stop listening:
unsubscribe();

listenToAuthTokenProcessed(callback) -- Listen for authentication token processing results.

const unsubscribe = komoEmbed.listenToAuthTokenProcessed(
  ({ success, errorMessage }) => {
    if (success) {
      console.log('Authentication completed');
    } else {
      console.error('Authentication failed', errorMessage);
    }
  }
);

// To stop listening:
unsubscribe();

listenToWindowMessageEvents(callback) -- Listen to raw window postMessage events from the Komo iframe. Lower-level than Komo events -- use when you need access to the raw message payload.

const unsubscribe = komoEmbed.listenToWindowMessageEvents((payload) => {
  console.log('Window message received:', payload);
});

// To stop listening:
unsubscribe();

Form Prefilling

Pre-populate form fields so users don't re-enter data you already have. You can call these methods at any time -- they also work via URL query parameters on the host page.

setFormPrefillValue(key, value) -- Set a single form field value.

komoEmbed.setFormPrefillValue('email', 'user@example.com');

setFormPrefillValues(values) -- Set multiple form field values at once.

komoEmbed.setFormPrefillValues({
  first_name: 'John',
  last_name: 'Doe',
  email: 'john.doe@example.com'
});

Important: Field keys must match the form field identifiers configured in the Komo Portal. Check the card's form settings to find the correct keys. Form prefill values can also be passed via URL query parameters on the host page.

Extension Data

Attach custom key-value data to the embed session. Extension data flows through to webhooks and workflow payloads, letting you correlate Komo events with your own system data (user IDs, session tokens, campaign codes, etc.). Values can be strings or objects. Also works via URL query parameters.

setExtensionDataValue(key, value)

komoEmbed.setExtensionDataValue('custom_unique_id', 'ABC123');

// Values can also be objects
komoEmbed.setExtensionDataValue('custom_object', {
  some_id: 'ABC123',
  some_measure: 123456
});

setExtensionDataValues(values)

komoEmbed.setExtensionDataValues({
  custom_unique_id: 'ABC123',
  custom_object: { some_id: 'ABC123', some_measure: 123456 }
});

Tip: Extension data is included in webhook payloads and workflow context. Use it to tag entries with your own identifiers so you can join data across systems.

Query Parameters

Pass query parameters to the Komo embed using three methods. Parameters follow this precedence: Forwarded params < Global params < Card-specific params.

1. Inline Configuration

Add a queryParams object to the data-komo-embed JSON attribute on card covers or triggers:

<!-- On a card cover -->
<div
  data-komo-embed-card-cover
  data-komo-embed='{"cardId":"CARD_ID","styles":{"embedStyle":"ImageButton","embedWidth":"500px"},"queryParams":{"utm_source":"website","utm_medium":"embed"}}'
></div>

<!-- On a card trigger -->
<button
  data-komo-embed-card-trigger="CARD_ID"
  data-komo-embed='{"queryParams":{"utm_source":"newsletter"}}'
>Click</button>

2. Programmatic API

Set parameters via JavaScript. You can set global parameters or card-specific ones:

// Global (applies to all embeds)
komoEmbed.setQueryParam('utm_source', 'homepage');
komoEmbed.setQueryParams({ utm_medium: 'banner', utm_campaign: 'summer-2024' });

// Card-specific (third argument is the card ID)
komoEmbed.setQueryParam('utm_content', 'variant-a', 'your-card-id');
komoEmbed.setQueryParams({ utm_term: 'keyword' }, 'your-card-id');

// With registerCardTrigger
komoEmbed.registerCardTrigger('your-card-id', '.my-trigger', {
  queryParams: { utm_source: 'sidebar' }
});

// With openExperience
komoEmbed.openExperience({
  type: 'card',
  id: 'your-card-id',
  options: { queryParams: { utm_source: 'modal' } }
});

3. Query Parameter Forwarding

Automatically forward the host page's query parameters to the Komo embed by setting forwardQueryParams to true:

<div
  data-komo-embed-card-cover
  data-komo-embed='{"cardId":"CARD_ID","styles":{"embedStyle":"ImageButton"},"forwardQueryParams":true}'
></div>

This is useful for passing UTM parameters, campaign tracking codes, or referrer information from your page URL through to Komo analytics and webhook payloads.

Precedence: Forwarded params are overridden by global params, which are overridden by card-specific params. This lets you set defaults via forwarding and override specific values per card.

Authentication

Authenticate users in the embedded experience so they don't see a Komo login screen. Uses JWT-based SSO.

setAuthToken(config) -- Set a JWT auth token proactively. Takes an object with token and type properties.

komoEmbed.setAuthToken({
  token: 'your-jwt-token-here',
  type: 'jwt'
});

listenToAuthTokenProcessed(callback) -- Listen for the result of auth token processing. Returns an unsubscribe function.

const unsubscribe = komoEmbed.listenToAuthTokenProcessed(
  ({ success, errorMessage }) => {
    if (success) console.log('Auth completed');
    else console.error('Auth failed', errorMessage);
  }
);

forgetUser() -- Clear the current user's authentication state. Call this on logout.

komoEmbed.forgetUser();

setAuthRequestHandler(handler) -- Set a callback for on-demand authentication. Called when Komo needs the user to be authenticated. Use hideExperience() and unhideExperience() to manage the modal while your auth UI is shown.

komoEmbed.setAuthRequestHandler(async () => {
  try {
    komoEmbed.hideExperience();
    const token = await showAuthModal();
    komoEmbed.setAuthToken({ token: token, type: 'jwt' });
    closeAuthModal();
    komoEmbed.unhideExperience();
  } catch (error) {
    komoEmbed.unhideExperience();
    throw error;
  }
});

For the full SSO setup guide including JWT generation and configuration, see the SSO Setup recipe.

For the complete and up-to-date embed SDK reference, see developers.komo.tech/embedding/browser.

---

Mobile (React Native) Embed

Embed Komo cards and hubs natively in React Native apps. The same concepts from the web embed apply -- card embedding, event listening, authentication, form prefilling -- but delivered via a native component.

Overview

Komo provides a React Native SDK that wraps the embed experience in a native component. This gives you the same card embedding, SSO, event listening, and form prefilling capabilities as the web SDK, but within a mobile app context.

Capabilities:

• Card embedding -- render card covers and open card experiences within your React Native app
• Full Hub embedding -- render an entire Komo Site within your app
• Event listening -- receive gameplay, form, and prize events in your React Native code
• SSO / Authentication -- pass JWT tokens for seamless user authentication
• Form prefilling -- pre-populate form fields from your app's user data
• Extension data -- pass custom key-value data through to webhooks and workflows

When to Use Mobile Embed

Good fit:

• React Native event apps adding engagement features
• Mobile loyalty apps with gamification
• Apps that need Komo embedded inline (not a web redirect)
• When you need native event handling and navigation

Consider web embed instead:

• WebView-based apps (use the browser embed SDK directly)
• Non-React-Native mobile apps (use WebView + browser SDK)
• Quick prototypes where a link to the Hub URL is sufficient

Getting Started

Install the package from npm:

npm install @komo-tech/react-native-widgets

The React Native SDK documentation covers component usage, props, event handling, and authentication setup.

Full setup instructions, API reference, and code examples are available in the Komo Developer Docs:

• NPM Package: https://www.npmjs.com/package/@komo-tech/react-native-widgets
• Integration Docs: https://developers.komo.tech/embedding/react-native