Templates / Build with Komo / Embed SDK Docs

Embed SDK Docs

Build with Komo

Full reference for embedding Komo via web SDK and React Native SDK.

Template Content

~2125 words, 501 lines

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

```html
<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.

```html
<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.

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

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

```javascript
// 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.

```html
<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).

```html
<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.

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

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

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

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

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

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

```javascript
komoEmbed.closeExperience();
```

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

```javascript
komoEmbed.hideExperience();
```

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

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
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.

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

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

```javascript
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)**

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

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

**setExtensionDataValues(values)**

```javascript
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:

```html

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

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

```javascript
// 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`:

```html
<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.

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

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

```javascript
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.

```javascript
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.

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

Changes here will propagate to all partner hubs using this template. Switch to Preview to see how it renders.

Quickstart Guide Integration Recipes

Partner Usage

Using template (3)

Fan 360 x Komo auto-updates

Eventbase auto-updates

WMT Sports auto-updates

Customised (0)

No partner overrides

Editing impacts 3 hubs

Changes to this template will be reflected in all partner hubs that haven't customised this section. Partners with their own version (0) will not be affected.