Web (Browser) Embed

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.

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.

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

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

komoEmbed.closeExperience();

komoEmbed.hideExperience();

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.

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

// To stop listening:
unsubscribe();

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

// To stop listening:
unsubscribe();

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.

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

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

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.

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

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

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

Query Parameters

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

<!-- 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>

// 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' } }
});

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

Authentication

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

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

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

komoEmbed.forgetUser();

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;
  }
});