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.
Replace CARD_ID
with yours
<div
data-komo-embed-card-cover
data-komo-embed='{"cardId":"CARD_ID","styles":{"embedStyle": "ImageButton","embedWidth": "unset"}}'
>
</div>
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.
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>
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.
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"});
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
orlistenToWindowMessageEvents
methods on thekomoEmbed
object. - The
listenToWindowMessageEvents
method exposes anywindow.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.
- Note: User Interaction Events will also appear in the
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
}
});