Skip to Content
Embed SDKBrowser

Setup

Include the following script element in your HTML, substituting in the domain your Komo hub is hosted on:

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

Cards

Cards can be embedded in 3 ways.

Card Covers

Card covers are an image or image & button which will launch the card experience in a full page modal. To setup a card cover have a HTML element marked with 2 data attributes. The first is data-komo-embed-card-cover. This let’s our embed code know that what to look for. The second is data-komo-embed. This holds data for which card and styling options. When the embed code loads, it will find all elements with data-komo-embed-card-cover and replace the element with the card cover. Clicking the cover will load the card in a full-page modal.

Code

Replace CARD_ID with yours

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

Card Triggers

Card triggers allow you to mark any HTML element as a card trigger. A card trigger will launch the card experience in a full page modal when clicked. To setup an element as a card trigger, simply add data-komo-embed-card-trigger={CARD_ID} as an attribute. When the embed code loads, it will find all elements with data-komo-embed-card-trigger and add an on click handler to load the card in a full-page modal.

Code

Replace CARD_ID with yours

<button
  class="bg-yellow-500 hover:bg-yellow-400 text-black font-bold py-2 px-4 rounded"
  data-komo-embed-card-trigger="CARD_ID"
>
  Show me Komo!
</button>
Live Example

Javascript

Once the setup script is loaded, you will have access to the komoEmbed javascript object. This can be used to programmatically register card triggers or open a card experience directly.

Code

Replace CARD_ID with yours

/**
 * Registers a card trigger to open a Komo card when the specified element is clicked.
 *
 * @param {string} cardId - The unique identifier of the card you want to display.
 * @param {string} domSelector - A DOM selector string to select the trigger element(s).
 */
komoEmbed.registerCardTrigger('CARD_ID', '#yourElementId');

A domSelector is a DOM selector used to locate elements in your document. You can learn more about DOM selectors here .

Replace CARD_ID with yours

/**
 * Opens the specified card experience in a full screen modal.
 */
komoEmbed.openExperience({ type: 'card', id: 'CARD_ID' });
/**
 * Closes the currently open experience modal.
 */
komoEmbed.closeExperience();
/**
 * Hides the currently open experience modal without closing it.
 * The modal remains open but becomes invisible to the user.
 */
komoEmbed.hideExperience();
/**
 * Shows a previously hidden experience modal.
 */
komoEmbed.unhideExperience();

Form Prefilling

Any form within an experience can be prefilled in the embed experience. We can accomplish this in 2 ways.

URL Query Parameters

Form fields on cards can be pre-filled with information based on the query string parameters in a given URL (learn more). This also works on the page that the embed is hosted on.

Javascript

Once the setup script is loaded, you will have access to the komoEmbed javascript object. This can be used to programmatically prefill forms.

/**
 * Sets a prefill value for a specific form field.
 * @param {string} fieldName - The name of the form field to prefill.
 * @param {string} value - The value to prefill the form field with.
 */
komoEmbed.setFormPrefillValue('email', 'user@example.com');
 
/**
 * Sets prefill values for multiple form fields at once.
 * @param {Record<string, string>} values - An object containing key-value pairs
 * where the key is the form field name and the value is the prefill value.
 */
komoEmbed.setFormPrefillValues({
  first_name: 'John',
  last_name: 'Doe',
  email: 'john.doe@example.com'
});

Listening for events from the embedded experience

  • You can listen for events from the embedded experience by using the listenToKomoEvents or listenToWindowMessageEvents methods on the komoEmbed object.
  • The listenToWindowMessageEvents method exposes any window.postMessage events from the embedded experience.
  • The listenToKomoEvents method exposes any User Interaction Events from the embedded experience.
    • Note: User Interaction Events will also appear in the listenToWindowMessageEvents callback. listenToKomoEvents is a more convenient way to listen for Komo User Interaction Events from the embedded experience.

Example Code

/**
 * Convenience method for subscribing to frontend komo-events coming from the embedded experience.
 * @param {Function} callback - The callback to be called when a komo-event is received.
 * @returns {Function} A function to unsubscribe from the event listener.
 */
const unsubscribeFromKomoEvents = komoEmbed.listenToKomoEvents((event) => {
  console.log('Komo event received:', event);
  // event has the structure: { eventName: string, eventData: any }
});
 
/**
 * Convenience method for subscribing to any window message events raised by the embedded experience.
 * @param {Function} callback - The callback to be called when a window message event is received.
 * @returns {Function} A function to unsubscribe from the event listener.
 */
const unsubscribeFromWindowMessages = komoEmbed.listenToWindowMessageEvents(
  (payload) => {
    console.log('Window message received:', payload);
  }
);
 
// To stop listening for events, call the unsubscribe functions:
// unsubscribeFromKomoEvents();
// unsubscribeFromWindowMessages();

Extension Data

The browser embed SDK allows you to set extension data on the user interaction events. There are 2 ways to set extension data.

URL Query Parameters

Extension data can be set with information based on the query string parameters in a given URL (learn more). This also works on the page that the embed is hosted on.

Javascript

Once the setup script is loaded, you will have access to the komoEmbed javascript object. This can be used to programmatically set extension data.

/**
 * Sets extension data value for a specific key.
 * @param {string} key - The key of the extension data
 * @param {string | number | boolean | object} value - The extension data value
 */
komoEmbed.setExtensionDataValue('custom_unique_id', 'ABC123');
komoEmbed.setExtensionDataValue('custom_object', {
  some_id: 'ABC123',
  some_measure: 123456
});
 
/**
 * Sets extension data values for multiple keys at once.
 * @param {Record<string, string | number | boolean | object>} values - An object containing key-value pairs
 * where the key is the extension data key and the value is the extension data value.
 */
komoEmbed.setExtensionDataValues({
  custom_unique_id: 'ABC123',
  custom_object: {
    some_id: 'ABC123',
    some_measure: 123456
  }
});

Query Parameters

Pass custom query parameters (like UTM tracking parameters) to your embedded experiences using three different methods: inline configuration, programmatic API, or query parameter forwarding.

Inline Configuration

Add query parameters directly in your embed configuration.

Card Cover with Query Params

Replace CARD_ID with yours

<div
  data-komo-embed-card-cover
  data-komo-embed='{
    "cardId": "CARD_ID",
    "styles": {
      "embedStyle": "ImageButton",
      "embedWidth": "500px"
    },
    "queryParams": {
      "utm_source": "website",
      "utm_medium": "embed",
      "utm_campaign": "spring-promo",
      "utm_content": "homepage-hero"
    }
  }'
></div>

Card Trigger with Query Params

Replace CARD_ID with yours

<button
  data-komo-embed-card-trigger="CARD_ID"
  data-komo-embed='{
    "queryParams": {
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "weekly-digest"
    }
  }'
>
  Click to Play
</button>

Programmatic API

Set query parameters using JavaScript before or after page load.

Global Query Params (All Embeds)

/**
 * Apply query parameters to all embeds on the page
 */
komoEmbed.setQueryParam('utm_source', 'homepage');
komoEmbed.setQueryParams({
  utm_medium: 'banner',
  utm_campaign: 'summer-2024'
});

Card-Specific Query Params

/**
 * Apply query parameters only to a specific card embed
 * @param {string} key - The query parameter name
 * @param {string} value - The query parameter value
 * @param {string} cardId - The card ID to apply the parameter to
 */
komoEmbed.setQueryParam('utm_content', 'variant-a', 'your-card-id');
komoEmbed.setQueryParams(
  {
    utm_term: 'keyword',
    custom_param: 'value'
  },
  'your-card-id'
);

Register Trigger with Query Params

/**
 * Register a card trigger with query parameters
 */
komoEmbed.registerCardTrigger('your-card-id', '.my-trigger-button', {
  queryParams: {
    utm_source: 'sidebar',
    utm_medium: 'widget'
  }
});

Open Experience with Query Params

/**
 * Open an experience with query parameters
 */
komoEmbed.openExperience({
  type: 'card',
  id: 'your-card-id',
  options: {
    queryParams: {
      utm_source: 'modal',
      utm_medium: 'popup'
    }
  }
});

Query Parameter Forwarding

Automatically forward query parameters from your host page to the embedded experience.

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

How it works:

  • If your page URL is https://example.com/?utm_source=google&utm_medium=cpc
  • With forwardQueryParams: true, those params are automatically passed to the embed
  • The embedded experience receives: ?utm_source=google&utm_medium=cpc

Parameter Precedence

When multiple sources provide the same query parameter, later sources override earlier ones:

  1. Forwarded params (base layer) - from host page if forwardQueryParams: true
  2. Global params - from setQueryParam() without cardId
  3. Card-specific params - from setQueryParam() with cardId or inline config

Example:

// Host page URL: ?utm_medium=cpc
 
// Enable forwarding and set overrides
komoEmbed.setQueryParam('utm_medium', 'email'); // Global override
komoEmbed.setQueryParam('utm_medium', 'banner', 'card-123'); // Card-specific override
 
// Result for card-123: utm_medium=banner
// Result for other cards: utm_medium=email

Common Use Cases

UTM Tracking for Campaign Attribution

<div
  data-komo-embed-card-cover
  data-komo-embed='{
    "cardId": "prize-wheel",
    "styles": {"embedStyle": "ImageButton"},
    "queryParams": {
      "utm_source": "email",
      "utm_medium": "newsletter",
      "utm_campaign": "black-friday-2024",
      "utm_content": "main-cta"
    }
  }'
></div>

Dynamic Campaign Tracking

// Extract campaign info from your app
const campaignId = getCurrentCampaignId();
const userSegment = getUserSegment();
 
komoEmbed.setQueryParams({
  utm_campaign: campaignId,
  utm_content: userSegment,
  source: 'web-app'
});

Pass-Through UTM Parameters

Useful when you’re running paid ads:

<div
  data-komo-embed-card-cover
  data-komo-embed='{
    "cardId": "contest-entry",
    "styles": {"embedStyle": "ImageButton"},
    "forwardQueryParams": true,
    "queryParams": {
      "utm_medium": "website"
    }
  }'
></div>

Result: If user arrives via ?utm_source=facebook&utm_campaign=q1-promo, the embed receives both those params plus your override for utm_medium=website.

Technical Details

  • Query parameters are added directly to the iframe URL (no prefix)
  • All values must be strings
  • Parameters are available to analytics tools in the embedded experience
  • Can be combined with form prefill and extension data features
  • Supports standard UTM parameters and custom parameters

Authentication

The browser embed SDK supports authentication for embedded experiences that require user authentication. There are two main approaches:

Setting Authentication Data

You can proactively set an authentication token before or after the experience loads. The token will be automatically sent to the embedded experience.

/**
 * Sets an authentication token for the embedded experience.
 * This token will be passed to the embedded experience for authentication.
 * @param {Object} payload - The authentication payload
 * @param {string} payload.token - The authentication token (e.g., JWT)
 * @param {string} payload.type - The type of token (currently supports 'jwt')
 */
komoEmbed.setAuthToken({
  token: 'your-jwt-token-here',
  type: 'jwt'
});

Clearing Authentication

If you need to sign the current user out of any embedded experiences (for example, when they log out of your host application), call komoEmbed.forgetUser(). This clears the active session inside the embed and triggers any necessary cleanup in the Komo experience.

/**
 * Clears any previously provided authentication details for embedded experiences.
 */
komoEmbed.forgetUser();

Handling Authentication Requests

If an embedded Komo experience requires authentication and no token has been set via komoEmbed.setAuthToken, the embed SDK will automatically call a handler function that you can register using komoEmbed.setAuthRequestHandler(handler).

This allows you to show your own authentication modal, collect credentials, and then provide the token back to the embed.

/**
 * Sets a handler function that will be called when the embedded experience
 * requires authentication.
 * @param {Function} handler - An async function that handles the authentication flow
 */
komoEmbed.setAuthRequestHandler(async () => {
  try {
    console.log("Komo embed requesting authentication");
 
    // Hide Komo's modal temporarily to avoid z-index issues
    komoEmbed.hideExperience();
 
    // Show your authentication modal and wait for user to authenticate
    const token = await showAuthModal();
 
    // Set the token once authentication is complete
    komoEmbed.setAuthToken({
      token: token,
      type: "jwt",
    });
 
    // Close your auth modal
    closeAuthModal();
 
    // Show Komo's modal again
    komoEmbed.unhideExperience();
 
  } catch (error) {
    console.error("Authentication failed:", error);
 
    // Ensure Komo's modal is shown again even on error
    komoEmbed.unhideExperience();
 
    throw error;
  }
});
Tracked Data (Advanced)React Native