Quickstart

Get Komo running in your environment. Pick your platform below — each guide gets you from zero to a working integration.

Prerequisites (all platforms)

A Komo Workspace with at least one Site (Hub) created
Access to portal.komo.digital
Your Hub URL (e.g. my-awesome-hub.komo.site)
At least one Card ID — find this in the Komo Portal under card settings

Add the Embed Script

Paste this bootstrapper into your HTML. Replace KOMO_HUB_URL with your Hub domain (e.g. my-awesome-hub.komo.site).

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

This creates a komoEmbed global. Calls are queued until the script loads, so you can use it immediately.

Embed a Card Cover

Renders the card's cover image inline. Clicking opens the full experience in a modal.

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

Or Use a Card Trigger

Turn any element into a card opener — no visual changes, just behavior.

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

Listen for Events

React to user interactions — form submissions, gameplay, prizes.

const unsubscribe = komoEmbed.listenToKomoEvents(
  function(event) {
    // event: { eventName: string, eventData: any }
    console.log(event.eventName, event.eventData);
  }
);

Prefill Forms (Optional)

If you know the user's details, prefill so they don't re-enter them.

komoEmbed.setFormPrefillValues({
  first_name: 'Jane',
  last_name: 'Smith',
  email: 'jane@example.com'
});

✓

See It Working

Live card cover and trigger — click either to open a real Komo experience.

Card Cover

Card Trigger

Full reference: Web Embed SDK docs — covers programmatic API, query parameters, authentication, extension data, and more.

Install the Package

Add the Komo React Native widgets package and its peer dependency.

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

Requires react-native-webview v13.x as a peer dependency. Package: @komo-tech/react-native-widgets on npm

Get Your Card Embed Meta URL

In the Komo Portal, open your card's settings, select the Embed tab, click React Native code in the sidebar, and copy the Card embed meta URL. This URL is the only required prop.

Embed a Card

The KomoCardWidget component handles everything — metadata fetching, card cover display, and modal for the card experience. One component, one prop.

import { KomoCardWidget } from '@komo-tech/react-native-widgets';

function EngagementScreen() {
  return (
    <KomoCardWidget
      embedMetaUrl="YOUR_CARD_EMBED_META_URL"
      containerStyle={{ maxWidth: '80%' }} 
    />
  );
}

That's the basics. The widget fetches the card cover image, renders it, and opens a modal with the full experience when tapped. Everything below is optional.

Prefill Forms and Listen for Events

Pass user data to prefill forms, and listen for events (gameplay, form submissions, prizes) via callback props.

<KomoCardWidget
  embedMetaUrl="YOUR_CARD_EMBED_META_URL"
  formPrefillValues={{ 
    email: 'jane@example.com',
    first_name: 'Jane',
    last_name: 'Smith'
  }} 
  onKomoEvent={(event) => {
    // event: { eventName, eventData, extensionData }
    console.log('Komo event:', event.eventName, event.eventData);
  }}
  extensionDataValues={{ 
    custom_user_id: 'usr_12345',
    source: 'mobile-app'
  }} 
/>

Authentication (Optional)

For Auth0 SSO, pass a fresh session transfer token. The user authenticates via Auth0 before seeing the Komo experience. The token has a 60-second lifespan — generate it immediately before opening.

<KomoCardWidget
  embedMetaUrl="YOUR_CARD_EMBED_META_URL"
  authPassthroughParams={new URLSearchParams({
    session_transfer_token: freshToken
  })} 
/>

Advanced: Individual Components

KomoCardWidget is the all-in-one solution. For more control, use the individual building blocks:

useFetchCardMetadata

Hook to fetch card metadata (cover image URL, embed URL, button style). Use your own data-fetching if needed.

CardCover

Renders the card's cover image with loading/error states and a CTA button. Requires onClick and isLoading props.

ExperienceModal

Full-screen modal that loads the card experience. Requires isOpen, onClose, and embedUrl. Supports auth, events, prefill.

Capabilities

Card cover + experience modal (KomoCardWidget)
Individual components (CardCover, ExperienceModal)
Auth0 session transfer (SSO)
Form prefilling
Event listening (onKomoEvent)
Extension data
Query parameters (UTM tracking)

Not using React Native?

For native iOS/Android apps without React Native, embed Komo inside a native WebView and use the browser embed SDK. The same setup script and data attributes work identically inside a WebView context.

Full reference: React Native Embed docs — npm: @komo-tech/react-native-widgets — developer docs: developers.komo.tech

Get Your Hub URL

Every Komo Site has a hosted URL. Find it in the Komo Portal under your Site settings.

https://my-awesome-hub.komo.site

Embed with an iframe

The simplest integration — drop an iframe into any page. The user gets the full hub experience (all pages, cards, navigation, branding) without leaving your site.

<iframe
  src="https://my-awesome-hub.komo.site"
  width="100%"
  height="800"
  frameborder="0"
  allow="clipboard-write"
  style="border: none; border-radius: 8px;"
></iframe>

That's It

No SDK, no scripts, no configuration. The iframe loads the full Komo hub as-is. Branding, navigation, cards, competitions — everything is managed in the Komo Portal.

Best for

Standalone engagement destinations
Event apps embedding a full engagement hub
Quick launches — zero dev work
When Komo manages the entire UI

When to use the SDK instead

You want individual cards in your existing page
You need event listening or form prefilling
You need SSO/authentication
You want programmatic control

Live Preview

Nexero Summit Hub Open full hub

Next Steps

You've got a working integration. Go deeper: