Templates / Build with Komo / Quickstart Guide

Quickstart Guide

Build with Komo

Get up and running in minutes. Tabbed guide for Web, React Native, and iframe.

Template Content

~957 words, 250 lines

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

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

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.

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

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

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

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

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

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

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

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

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

Technical Overview Embed SDK Docs

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.