/hub/wmt-sports/build/quickstart

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

Web (Browser)

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

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

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

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

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

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

React Native

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

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

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

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

4. 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'
  }}
/>

5. 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/embedding/react-native

Hub iframe

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

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

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

Next Steps

You've got a working integration. Go deeper:

  • Embedding Options -- Covers, triggers, programmatic API -- all the ways to embed Komo content.
  • SSO Setup -- Authenticate users so they don't see a Komo login screen.
  • CRM & API Integration -- Push data to Salesforce, Mailchimp, Braze, or any REST API via workflows.
  • Workflow Patterns -- Automate follow-ups, lead routing, loyalty points, and more.