# Embed SDK

Source: /embedding/

Learn how to embed Komo experiences into your website or mobile application.

The Komo Embed SDK allows you to embed interactive cards and experiences directly into your website or mobile application. This enables seamless integration of Komo's engagement features into your existing digital properties.

## Supported Platforms

### Browser

Embed Komo cards into any website using JavaScript and iframes. Works with
all modern browsers and frameworks. [View Browser
Guide](/embedding/browser/)
### React Native

Embed Komo experiences into iOS and Android mobile apps using our React
Native SDK. [View React Native Guide](/embedding/react-native/)

## Key Features

- **Seamless Integration**: Embed cards that match your site's look and feel
- **Form Prefilling**: Pass user data to pre-populate forms
- **Event Tracking**: Listen to user interactions via User Interaction Events
- **UTM Tracking**: Add query parameters for analytics
- **Extension Data**: Pass custom data through to your integrations
- **Auth0 Support**: Enable authentication for protected content

## Getting Started

Choose your platform above to get started with detailed implementation guides, API references, and code examples.

## Support

If you need help with integration, contact us at [support@komo.tech](mailto:support@komo.tech).

---

# Embed SDK

Source: /embedding/browser/

Learn how to embed Komo experiences into your website or application.

## Setup

Include the following script element in your HTML, substituting in the domain your Komo hub is hosted on:

> **Important Note**
>
> Ensure you substitute in the **KOMO_HUB_HOST** hostname below. Use the Site
> hostname only, without `https://` or a path.

Komo Site URL: `https://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://my-awesome-hub.komo.site/assets/embed/embed.js","komoEmbed");
</script>
```

## Cards

Live examples on this page load the embed script from Komo’s public demo hub (`komohub.komo.site`) so covers and triggers work as on a real site.

Cards can be embedded in 3 ways.

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

   **Code - Replace `CARD_ID` with yours**

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

   **Live Example**

Live card cover example for card ID `2092eac3-a0b5-4187-a392-f84dc3cae941`.

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

   **Code - Replace `CARD_ID` with yours**

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

   **Live Example**

Live card trigger button example for card ID `2092eac3-a0b5-4187-a392-f84dc3cae941`.

3. **Javascript**

   Once the [setup script](#setup) 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.

> **Caution**
>
> Ensure any javascript code calling **komoEmbed** are in scripts **below**
> the [setup script](#setup).

   **Code - Replace `CARD_ID` with yours**

   ```js
   /**
    * 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](https://developer.mozilla.org/en-US/docs/Web/API/Document_Object_Model/Locating_DOM_elements_using_selectors).

   **Code - Replace `CARD_ID` with yours**

   ```js
   /**
    * Opens the specified card experience in a full screen modal.
    */
   komoEmbed.openExperience({ type: 'card', id: 'CARD_ID' });
   ```

   ```js
   /**
    * Closes the currently open experience modal.
    */
   komoEmbed.closeExperience();
   ```

   ```js
   /**
    * Hides the currently open experience modal without closing it.
    * The modal remains open but becomes invisible to the user.
    */
   komoEmbed.hideExperience();
   ```

   ```js
   /**
    * Shows a previously hidden experience modal.
    */
   komoEmbed.unhideExperience();
   ```

## Form Prefilling

Any form within an experience can be prefilled in the embed experience.
We can accomplish this in 2 ways.

1. **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](/forms#pre-filling-from-url-query-parameters)). This also works on the page that the embed is hosted on.

2. **Javascript**

   Once the [setup script](#setup) is loaded, you will have access to the `komoEmbed` javascript object.
   This can be used to programmatically prefill forms.

> **Caution**
>
> Ensure any javascript code calling **komoEmbed** are in scripts **below**
> the [setup script](#setup).

   ```js
   /**
    * 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`, `listenToAuthTokenProcessed`, or `listenToWindowMessageEvents` methods on the `komoEmbed` object.
- The `listenToKomoEvents` method exposes any [User Interaction Events](/user-interaction-events) from the embedded experience.
- The `listenToAuthTokenProcessed` method is triggered after the embedded experience finishes processing an authentication token.
- The `listenToWindowMessageEvents` method exposes any `window.postMessage` 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.

> **Caution**
>
> Ensure any javascript code calling **komoEmbed** are in scripts **below** the
> [setup script](#setup).

### Example Code

```js
/**
 * 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](/user-interaction-events/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](/user-interaction-events/extension-data#1-extension-data-from-url-query-parameters)). This also works on the page that the embed is hosted on.

### Javascript

Once the [setup script](#setup) is loaded, you will have access to the `komoEmbed` javascript object.
This can be used to programmatically set extension data.

> **Caution**
>
> Ensure any javascript code calling **komoEmbed** are in scripts **below** the
> [setup script](#setup).

```js
/**
 * 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
  }
});
```

## Query Parameters

Pass custom query parameters (like UTM tracking parameters) to your embedded experiences using three different methods: inline configuration, programmatic API, or query parameter forwarding.

### Inline Configuration

Add query parameters directly in your embed configuration.

#### Card Cover with Query Params

Replace `CARD_ID` with yours

```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",
      "utm_campaign": "spring-promo",
      "utm_content": "homepage-hero"
    }
  }'
></div>
```

#### Card Trigger with Query Params

Replace `CARD_ID` with yours

```html
<button
  data-komo-embed-card-trigger="CARD_ID"
  data-komo-embed='{
    "queryParams": {
      "utm_source": "newsletter",
      "utm_medium": "email",
      "utm_campaign": "weekly-digest"
    }
  }'
>
  Click to Play
</button>
```

### Programmatic API

Set query parameters using JavaScript before or after page load.

> **Caution**
>
> Ensure any javascript code calling **komoEmbed** are in scripts **below** the
> [setup script](#setup).

#### Global Query Params (All Embeds)

```js
/**
 * Apply query parameters to all embeds on the page
 */
komoEmbed.setQueryParam('utm_source', 'homepage');
komoEmbed.setQueryParams({
  utm_medium: 'banner',
  utm_campaign: 'summer-2024'
});
```

#### Card-Specific Query Params

```js
/**
 * Apply query parameters only to a specific card embed
 * @param {string} key - The query parameter name
 * @param {string} value - The query parameter value
 * @param {string} cardId - The card ID to apply the parameter to
 */
komoEmbed.setQueryParam('utm_content', 'variant-a', 'your-card-id');
komoEmbed.setQueryParams(
  {
    utm_term: 'keyword',
    custom_param: 'value'
  },
  'your-card-id'
);
```

#### Register Trigger with Query Params

```js
/**
 * Register a card trigger with query parameters
 */
komoEmbed.registerCardTrigger('your-card-id', '.my-trigger-button', {
  queryParams: {
    utm_source: 'sidebar',
    utm_medium: 'widget'
  }
});
```

#### Open Experience with Query Params

```js
/**
 * Open an experience with query parameters
 */
komoEmbed.openExperience({
  type: 'card',
  id: 'your-card-id',
  options: {
    queryParams: {
      utm_source: 'modal',
      utm_medium: 'popup'
    }
  }
});
```

### Query Parameter Forwarding

Automatically forward query parameters from your host page to the embedded experience.

```html
<div
  data-komo-embed-card-cover
  data-komo-embed='{
    "cardId": "CARD_ID",
    "styles": {"embedStyle": "ImageButton"},
    "forwardQueryParams": true
  }'
></div>
```

**How it works:**

- If your page URL is `https://example.com/?utm_source=google&utm_medium=cpc`
- With `forwardQueryParams: true`, those params are automatically passed to the embed
- The embedded experience receives: `?utm_source=google&utm_medium=cpc`

### Parameter Precedence

When multiple sources provide the same query parameter, later sources override earlier ones:

1. **Forwarded params** (base layer) - from host page if `forwardQueryParams: true`
2. **Global params** - from `setQueryParam()` without cardId
3. **Card-specific params** - from `setQueryParam()` with cardId or inline config

### Common Use Cases

#### UTM Tracking for Campaign Attribution

```html
<div
  data-komo-embed-card-cover
  data-komo-embed='{
    "cardId": "prize-wheel",
    "styles": {"embedStyle": "ImageButton"},
    "queryParams": {
      "utm_source": "email",
      "utm_medium": "newsletter",
      "utm_campaign": "black-friday-2024",
      "utm_content": "main-cta"
    }
  }'
></div>
```

#### Dynamic Campaign Tracking

```js
// Extract campaign info from your app
const campaignId = getCurrentCampaignId();
const userSegment = getUserSegment();

komoEmbed.setQueryParams({
  utm_campaign: campaignId,
  utm_content: userSegment,
  source: 'web-app'
});
```

#### Pass-Through UTM Parameters

Useful when you're running paid ads:

```html
<div
  data-komo-embed-card-cover
  data-komo-embed='{
    "cardId": "contest-entry",
    "styles": {"embedStyle": "ImageButton"},
    "forwardQueryParams": true,
    "queryParams": {
      "utm_medium": "website"
    }
  }'
></div>
```

**Result:** If user arrives via `?utm_source=facebook&utm_campaign=q1-promo`, the embed receives both those params plus your override for `utm_medium=website`.

### Technical Details

- Query parameters are added directly to the iframe URL (no prefix)
- All values must be strings
- Parameters are available to analytics tools in the embedded experience
- Can be combined with form prefill and extension data features
- Supports standard UTM parameters and custom parameters

## Authentication

The browser embed SDK supports authentication for embedded experiences that require user authentication. There are two main approaches:

1. **Setting Authentication Data**

   You can proactively set an authentication token before or after the experience loads. The token will be automatically sent to the embedded experience.

> **Caution**
>
> Ensure any javascript code calling **komoEmbed** are in scripts **below**
> the [setup script](#setup).

   ```js
   /**
    * Sets an authentication token for the embedded experience.
    * This token will be passed to the embedded experience for authentication.
    * @param {Object} payload - The authentication payload
    * @param {string} payload.token - The authentication token (e.g., JWT)
    * @param {string} payload.type - The type of token (currently supports 'jwt')
    */
   komoEmbed.setAuthToken({
     token: 'your-jwt-token-here',
     type: 'jwt'
   });
   ```

   You can register a listener to be notified when the embedded experience finishes processing the token:

   ```js
   const unsubscribeFromAuth = komoEmbed.listenToAuthTokenProcessed(
     ({ success, errorMessage }) => {
       if (success) {
         console.log('Authentication completed');
       } else {
         console.error('Authentication failed', errorMessage);
       }
     }
   );

   // Later, when you no longer need the callback:
   unsubscribeFromAuth();
   ```

2. **Clearing Authentication**

   If you need to sign the current user out of any embedded experiences (for example, when they log out of your host application), call `komoEmbed.forgetUser()`. This clears the active session inside the embed and triggers any necessary cleanup in the Komo experience.

   ```js
   /**
    * Clears any previously provided authentication details for embedded experiences.
    */
   komoEmbed.forgetUser();
   ```

3. **Handling Authentication Requests**

   If an embedded Komo experience requires authentication and no token has been set via `komoEmbed.setAuthToken`, the embed SDK will automatically call a handler function that you can register using `komoEmbed.setAuthRequestHandler(handler)`.

   This allows you to show your own authentication modal, collect credentials, and then provide the token back to the embed.

   ```js
   /**
    * Sets a handler function that will be called when the embedded experience
    * requires authentication.
    * @param {Function} handler - An async function that handles the authentication flow
    */
   komoEmbed.setAuthRequestHandler(async () => {
     try {
       console.log('Komo embed requesting authentication');

       // Hide Komo's modal temporarily to avoid z-index issues
       komoEmbed.hideExperience();

       // Show your authentication modal and wait for user to authenticate
       const token = await showAuthModal();

       // Set the token once authentication is complete
       komoEmbed.setAuthToken({
         token: token,
         type: 'jwt'
       });

       // Close your auth modal
       closeAuthModal();

       // Show Komo's modal again
       komoEmbed.unhideExperience();
     } catch (error) {
       console.error('Authentication failed:', error);

       // Ensure Komo's modal is shown again even on error
       komoEmbed.unhideExperience();

       throw error;
     }
   });
   ```

---

# React Native Embedding

Source: /embedding/react-native/

Learn how to embed Komo experiences in your React Native application.

Komo cards can be embedded into your React Native application through Komo's NPM package [@komo-tech/react-native-widgets](https://www.npmjs.com/package/@komo-tech/react-native-widgets).

## Installation

```bash
npm install @komo-tech/react-native-widgets
```

> **Note**
>
> [@komo-tech/react-native-widgets](https://www.npmjs.com/package/@komo-tech/react-native-widgets)
> has a peer dependency on
> [react-native-webview](https://github.com/react-native-webview/react-native-webview),
> and recommends the latest major version, `13.x`.

## Basic Usage

- The quickest way to get started with embedding Komo content in react native is by using the `KomoCardWidget` component.
- This component combines metadata fetching, card cover display, and modal handling for the card experience.
- The only required prop is `embedMetaUrl`. To find this in the Komo portal:
  - Navigate to the settings of the card to be embedded.
  - Select the `Embed` tab and click on `React Native code` in the right sidebar.
  - Copy the `Card embed meta URL` and use it as the value of the `embedMetaUrl` prop.

```js

// ...

<KomoCardWidget
  embedMetaUrl={KomoCardNativeEmbedUrl}
  containerStyle={{ maxWidth: '80%' }}
/>;
```

### Prefilling form details

- You can pass information through to the Komo experience that will be pre-filled in any forms that the user may encounter.
- Pass a plain `Record<string,string>` object of keys and values through to the `formPrefillValues` prop on `KomoCardWidget` or `ExperienceModal`.
- The object keys must match the Unique ID of the form field or contact property from the Komo Platform that you want to prefill.

```js
<KomoCardWidget
  embedMetaUrl={KomoCardNativeEmbedUrl}
  containerStyle={{ maxWidth: '80%' }}
  formPrefillValues={{
    email: 'email@domain.com',
    first_name: 'Person',
    last_name: 'Doe'
  }}
/>
```

## Advanced usage

### Metadata fetching

- The first step to using embedded Komo content involves fetching the card metadata.
- Use the `useFetchCardMetadata` hook and the `Native embed URL` copied from the platform to fetch the `CardEmbedMetadata`.
- The `CardEmbedMetadata` has the information required to render the cover image (`imageUrl`) and the URL (`embedUrl`) that the `ExperienceModal` needs to render the embedded experience.
- Note: you can use your own data-fetching patterns if you require more advanced data fetching handling. So long as it produces a `CardEmbedMetadata`, you can pass that to the other components that you want to use.

```js

// ... rest of your component

const { data, isLoading, isError } = useFetchCardMetadata({
  embedMetaUrl: KomoCardNativeEmbedUrl
});

// ... use the data.
```

### Render a Card Cover

- The `CardCover` component is used to display the cover image of a Komo card.
- It handles loading states, error states, and button display.
- The component requires an `onClick` handler and `isLoading` state.
- The `imageUrl` and `imageAspectRatio` props are typically obtained from the `CardEmbedMetadata`.

```js

// ... rest of your component

<CardCover
  imageUrl={metadata?.imageUrl}
  imageAspectRatio={metadata?.imageAspectRatio}
  isLoading={isLoading}
  isError={isError}
  onClick={() => doSomethingOnCoverClicked()}
  metaButtonStyle={metadata?.buttonStyle}
  containerStyle={{ borderRadius: 8 }}
/>;
```

### Using the Experience Modal

- The `ExperienceModal` component is used to display the full Komo experience in a modal overlay.
- It handles loading states, error states, and communication with the embedded experience.
- The component requires an `isOpen` state and `onClose` handler.
- A valid `embedUrl` prop is required for the experience modal to function, and this is typically obtained from the `CardEmbedMetadata`.
- If you have forced OAuth enabled, you also need to pass through the `embedAuthUrl` from `CardEmbedMetadata`.

```js

// ... rest of your component

<ExperienceModal
  isOpen={isModalOpen}
  onClose={() => setIsModalOpen(false)}
  embedUrl={metadata?.embedUrl}
  embedAuthUrl={metadata?.embedAuthUrl}
  loadingTimeoutMs={15000} // Optional: customize loading timeout
  appId="my-app" // Optional: identify where the content is embedded
/>;
```

### Experience Modal example without Card Cover

- You can use whichever components you want to build your desired experience.
- For example, you can trigger the `ExperienceModal` without rendering our CardCover.

```js
// ... rest of your component
const { data, isLoading } = useFetchCardMetadata({
  isEnabled,
  embedMetaUrl: EmbedMetaUrlFromKomoPortal
});
const [modalOpen, setModalOpen] = useState(false);

// other code, e.g. some element that calls setModalOpen(true) after isLoading returns false

<ExperienceModal
  isOpen={modalOpen}
  onClose={() => {
    setModalOpen(false);
  }}
  embedUrl={data?.embedUrl}
/>;
```

### Listening for events from the embedded experience

- You can listen for events from the embedded experience by using the `onWindowMessage` or `onKomoEvent` props on the `ExperienceModal` or `KomoCardWidget`.
- The `onWindowMessage` prop exposes any `window.postMessage` events from the embedded experience.
- The `onKomoEvent` prop exposes any [User Interaction Events](/user-interaction-events) from the embedded experience.
  - Note: User Interaction Events will also appear in the `onWindowMessage` callback. `onKomoEvent` is a more convenient way to listen for Komo User Interaction Events from the embedded experience.

```js
<ExperienceModal
  isOpen={modalOpen}
  onClose={() => {
    setModalOpen(false);
  }}
  embedUrl={data?.embedUrl}
  onKomoEvent={(event) => {
    console.log('Komo event received:', event);
  }}
  onWindowMessage={(event) => {
    console.log('Window message received:', event);
  }}
/>
```

### Extension Data

- The `ExperienceModal` and `KomoCardWidget` components allow you to set [extension data](/user-interaction-events/extension-data) on the user interaction events.
- The `extensionDataValues` prop is a plain `Record<string, string | number | boolean | object>` object.
- Make sure PII is not passed in as extension data, as it is passed directly to your tag manager integrations.

```js
<KomoCardWidget
  embedMetaUrl={KomoCardNativeEmbedUrl}
  extensionDataValues={{
    custom_unique_id: 'ABC123',
    custom_object: {
      some_id: 'ABC123',
      some_measure: 123456
    }
  }}
/>
```

### Query Parameters

Pass custom query parameters (like UTM tracking parameters) to your embedded experiences. This is useful for campaign attribution, A/B testing, and analytics tracking.

#### Basic Usage

```js

<KomoCardWidget
  embedMetaUrl={KomoCardNativeEmbedUrl}
  queryParams={{
    utm_source: 'mobile-app',
    utm_medium: 'widget',
    utm_campaign: 'summer-2024',
    utm_content: 'hero-banner'
  }}
/>;
```

#### UTM Tracking Example

```js
<KomoCardWidget
  embedMetaUrl={embedUrl}
  queryParams={{
    utm_source: 'instagram',
    utm_medium: 'social',
    utm_campaign: 'product-launch',
    utm_term: 'keyword',
    utm_content: 'story-swipe-up'
  }}
/>
```

#### Dynamic Campaign Tracking

```js

function CampaignScreen() {
  const route = useRoute();
  const { campaignId, source } = route.params;

  return (
    <KomoCardWidget
      embedMetaUrl={embedUrl}
      queryParams={{
        utm_campaign: campaignId,
        utm_source: source,
        utm_medium: 'app'
      }}
    />
  );
}
```

#### User Segment Tracking

```js

function ContestScreen() {
  const { userSegment, subscriptionTier } = useUser();

  return (
    <KomoCardWidget
      embedMetaUrl={embedUrl}
      queryParams={{
        utm_source: 'app',
        utm_content: userSegment,
        user_tier: subscriptionTier
      }}
    />
  );
}
```

#### Combining with Other Props

Query parameters work alongside form prefill and extension data:

```js
<KomoCardWidget
  embedMetaUrl={embedUrl}
  // Prefill form fields
  formPrefillValues={{
    email: user.email,
    first_name: user.firstName
  }}
  // Add analytics data
  extensionDataValues={{
    user_id: user.id,
    account_type: user.accountType
  }}
  // Track campaign source
  queryParams={{
    utm_source: 'app',
    utm_medium: 'home-screen',
    utm_campaign: 'welcome-flow'
  }}
/>
```

#### Using with ExperienceModal

The `ExperienceModal` component also supports `queryParams`:

```js

function CustomModal() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <Button title="Open Contest" onPress={() => setIsOpen(true)} />

      <ExperienceModal
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
        embedUrl={metadata?.embedUrl}
        queryParams={{
          utm_source: 'custom-modal',
          utm_medium: 'app'
        }}
      />
    </>
  );
}
```

#### Deep Link Attribution

Track users coming from deep links:

```js

function DeepLinkScreen() {
  const [queryParams, setQueryParams] = useState({});

  useEffect(() => {
    // Parse deep link URL parameters
    Linking.getInitialURL().then((url) => {
      if (url) {
        const urlObj = new URL(url);
        const params = {};
        urlObj.searchParams.forEach((value, key) => {
          params[key] = value;
        });
        setQueryParams(params);
      }
    });
  }, []);

  return (
    <KomoCardWidget
      embedMetaUrl={embedUrl}
      queryParams={{
        ...queryParams,
        utm_source: 'deep-link'
      }}
    />
  );
}
```

#### Multi-Platform Tracking

Detect and track the platform:

```js

<KomoCardWidget
  embedMetaUrl={embedUrl}
  queryParams={{
    utm_source: 'react-native',
    utm_medium: 'app',
    platform: Platform.OS, // 'ios' or 'android'
    app_version: DeviceInfo.getVersion()
  }}
/>;
```

#### Technical Details

- Query parameters are added directly to the webview URL (no prefix)
- All values must be strings
- Parameters are available to analytics tools in the embedded experience
- Can be combined with `formPrefillValues` and `extensionDataValues`
- Supports standard UTM parameters and custom parameters

### Auth0 Session Transfer

- The `KomoCardWidget` component supports Auth0 authentication through the `authPassthroughParams` prop.
- The `ExperienceModal` component supports Auth0 authentication through the `embedAuthUrl` and `authPassthroughParams` props.
  - The `embedAuthUrl` is typically obtained from the `CardEmbedMetadata`.
- Pre-requisites:
  - Auth0 SSO must be configured on the Komo Hub, and "Force Embed Auth" must be enabled under Embed SDK settings on the hub.
  - Pass a fresh session transfer token to the `authPassthroughParams` prop, e.g. `session_transfer_token: 'ABC123'`.
- With this setup, the user will be redirected to Auth0 to authenticate when the experience modal is opened, before being redirected back to the embedded experience.
- The session transfer token must be obtained immediately before opening the experience modal, since it has a short 60 second lifespan.
- **Recommended:** Specify `webViewProps={{ incognito: true }}` to ensure user session state is cleared correctly when changing between different authenticated users.

```js
<KomoCardWidget
    embedMetaUrl={KomoCardNativeEmbedUrl}
    authPassthroughParams={new URLSearchParams({
        session_transfer_token: 'ABC123'
    })}
    webViewProps={{ incognito: true }}
/>

// or if using the ExperienceModal directly
<ExperienceModal
    isOpen={isModalOpen}
    onClose={() => setIsModalOpen(false)}
    embedUrl={metadata?.embedUrl}
    embedAuthUrl={metadata?.embedAuthUrl}
    authPassthroughParams={new URLSearchParams({
        session_transfer_token: 'ABC123'
    })}
    webViewProps={{ incognito: true }}
/>
```

#### Error handling

- If the `session_transfer_token` passed to Auth0 is used, invalid, or expired, then the users will end up being shown the ExperienceModal `errorDisplay`, which includes a built-in retry button.
- If you don't provide an `errorDisplay` override, the retry function will just attempt to reload the experience with the current parameters and will most likely fail again.
- We recommend that you provide a custom `errorDisplay` so that you can handle `session_transfer_token` regeneration before trying to load the content again.

## API Reference

### ButtonStyle

| Name            | Type    | Description                    | Required |
| --------------- | ------- | ------------------------------ | -------- |
| text            | string? | Text to display on the button  | Optional |
| backgroundColor | string? | Background color of the button | Optional |
| color           | string? | Text color of the button       | Optional |

### CardCover Props

| Name                    | Type                     | Description                                                | Required |
| ----------------------- | ------------------------ | ---------------------------------------------------------- | -------- |
| onClick                 | () => void               | The callback for when the cover is clicked                 | Required |
| isLoading               | boolean                  | Whether the cover is loading                               | Required |
| isError                 | boolean?                 | Whether the cover is in an error state                     | Optional |
| loader                  | ReactNode?               | Override the default skeleton loader                       | Optional |
| errorDisplay            | ReactNode?               | Override the default error display                         | Optional |
| metaButtonStyle         | ButtonStyle?             | The button style returned from the embed metadata endpoint | Optional |
| overrideButtonStyle     | `StyleProp<ViewStyle>`?  | Override the button style                                  | Optional |
| overrideButtonTextStyle | `StyleProp<TextStyle>`?  | Override the button text style                             | Optional |
| containerStyle          | `StyleProp<ViewStyle>`?  | Override the container style                               | Optional |
| coverImageStyle         | `StyleProp<ImageStyle>`? | Override the cover image style                             | Optional |
| hideCoverButton         | boolean?                 | Whether to hide the cover button                           | Optional |
| imageUrl                | string?                  | The url of the cover image                                 | Optional |
| imageAspectRatio        | number?                  | The aspect ratio of the cover image                        | Optional |

### CardEmbedMetadata

| Name             | Type         | Description                                                   | Required |
| ---------------- | ------------ | ------------------------------------------------------------- | -------- |
| title            | string?      | The title of the card                                         | Optional |
| imageUrl         | string?      | URL of the card's cover image                                 | Optional |
| imageHeight      | number?      | Height of the cover image in pixels                           | Optional |
| imageWidth       | number?      | Width of the cover image in pixels                            | Optional |
| imageAspectRatio | number?      | Aspect ratio of the cover image                               | Optional |
| embedUrl         | string?      | URL for the embedded experience                               | Optional |
| embedAuthUrl     | string?      | URL used to OAuth user before showing the embedded experience | Optional |
| buttonStyle      | ButtonStyle? | Styling for the card's button                                 | Optional |

### ExperienceModal Props

| Name                  | Type                                                    | Description                                                                    | Required |
| --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------ | -------- |
| isOpen                | boolean                                                 | Whether the modal is open                                                      | Required |
| onClose               | () => void                                              | Callback for when close is requested                                           | Required |
| embedUrl              | string                                                  | The URL of the embedded card experience                                        | Required |
| modalHeader           | ReactNode                                               | Override the default modal header                                              | Optional |
| shareClickUrl         | string                                                  | Override the url that redirects a user when clicking on a share link           | Optional |
| appId                 | string                                                  | An identifier for the embedded Komo content                                    | Optional |
| formPrefillValues     | `Record<string, string>`                                | Prefill values for the form within the experience                              | Optional |
| extensionDataValues   | `Record<string, string \| number \| boolean \| object>` | Extension data values for the experience                                       | Optional |
| loadingIndicator      | ReactNode                                               | Override the default loading indicator                                         | Optional |
| modalProps            | `ModalProps`                                            | Override the default modal props                                               | Optional |
| loadingTimeoutMs      | number                                                  | Timeout in milliseconds before showing error state. Defaults to 15000ms        | Optional |
| errorDisplay          | `({ onRetry }: { onRetry: () => void }) => ReactNode`   | Override the default error display                                             | Optional |
| onFileDownload        | `WebViewProps["onFileDownload"]`                        | Callback for when a file download is requested. Only applies to iOS            | Optional |
| onKomoEvent           | `(event: KomoEvent) => void`                            | Callback for when a Komo event is raised in the embedded experience            | Optional |
| onWindowMessage       | `(event: any) => void`                                  | Callback for when a window message is raised in the embedded experience        | Optional |
| embedAuthUrl          | string?                                                 | The URL of the authorization endpoint                                          | Optional |
| authPassthroughParams | URLSearchParams                                         | Passthrough parameters to add to the auth URL as query parameters              | Optional |
| webViewProps          | `WebViewProps`                                          | Additional props for the react-native-webview component                        | Optional |
| iframeProps           | `IframeProps`                                           | Additional props for the iframe component. Only applies if the platform is web | Optional |

### KomoCardWidget Props

| Name                  | Type                                                    | Description                                                                          | Required |
| --------------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------ | -------- |
| embedMetaUrl          | String                                                  | The native embed url taken from the Komo portal settings of the card to be embedded  | Required |
| appId                 | String                                                  | Useful for the embedded Komo content to identify where it's being embedded           | Optional |
| containerStyle        | `StyleProp<ViewStyle>`                                  | Style overrides for the container of the card cover                                  | Optional |
| coverImageStyle       | `StyleProp<ImageStyle>`                                 | Style overrides for the image of the card cover                                      | Optional |
| buttonStyle           | `StyleProp<ViewStyle>`                                  | Style overrides for the CTA button of the card cover                                 | Optional |
| buttonTextStyle       | `StyleProp<TextStyle>`                                  | Style overrides for the CTA button text of the card cover                            | Optional |
| coverLoader           | ReactNode                                               | The loader shown while the cover is loading                                          | Optional |
| coverErrorDisplay     | ReactNode                                               | Override the default error display for the cover                                     | Optional |
| hideCoverButton       | Boolean                                                 | Hide the CTA button of the cover                                                     | Optional |
| modalHeader           | ReactNode                                               | The header of the modal to render instead of the default                             | Optional |
| onError               | `(error) => void`                                       | Callback for when an error occurs during querying the embed metadata endpoint        | Optional |
| onModalClose          | `() => void`                                            | Callback on modal close                                                              | Optional |
| onModalOpen           | `() => void`                                            | Callback on modal open                                                               | Optional |
| shareClickUrl         | String                                                  | Override of the url that redirects a user when clicking on a share link              | Optional |
| formPrefillValues     | `Record<string, string>`                                | Prefill values for the form within the experience                                    | Optional |
| extensionDataValues   | `Record<string, string \| number \| boolean \| object>` | Extension data values for the experience                                             | Optional |
| onFileDownload        | `WebViewProps["onFileDownload"]`                        | Callback for when a file download is requested. Only applies to iOS                  | Optional |
| onKomoEvent           | `(event: KomoEvent) => void`                            | Callback for when a Komo event is raised in the embedded experience                  | Optional |
| onWindowMessage       | `(event: any) => void`                                  | Callback for when a window message is raised in the embedded experience              | Optional |
| authPassthroughParams | URLSearchParams                                         | Passthrough parameters to add to the auth URL as query parameters                    | Optional |
| loadingTimeoutMs      | number                                                  | Timeout in milliseconds before showing error state in the modal. Defaults to 15000ms | Optional |
| modalErrorDisplay     | `({ onRetry }: { onRetry: () => void }) => ReactNode`   | Override the default error display for the modal                                     | Optional |
| webViewProps          | `WebViewProps`                                          | Additional props for the react-native-webview component                              | Optional |
| iframeProps           | `IframeProps`                                           | Additional props for the iframe component. Only applies if the platform is web       | Optional |

### KomoEvent

| Name          | Type                                                    | Description                                | Required |
| ------------- | ------------------------------------------------------- | ------------------------------------------ | -------- |
| eventName     | string                                                  | The name of the event                      | Required |
| eventData     | any                                                     | Object containing the event data           | Required |
| extensionData | `Record<string, string \| number \| boolean \| object>` | Extension data raised along with the event | Required |

### useFetchCardMetadata Hook

#### Options

| Name         | Type             | Description                                                                   | Required |
| ------------ | ---------------- | ----------------------------------------------------------------------------- | -------- |
| embedMetaUrl | string           | The URL of the embed metadata for the card, copied from the Komo Portal       | Required |
| isEnabled    | boolean          | Whether the embed metadata query is enabled. Defaults to true                 | Optional |
| onError      | (e: any) => void | Callback for when an error occurs during querying the embed metadata endpoint | Optional |

#### Result

| Name         | Type                  | Description                                | Required |
| ------------ | --------------------- | ------------------------------------------ | -------- |
| data         | `CardEmbedMetadata?`  | The embed metadata for the card            | Optional |
| isLoading    | boolean               | Whether the embed metadata is loading      | Required |
| isError      | boolean               | Whether the embed metadata query failed    | Required |
| isSuccess    | boolean               | Whether the embed metadata query succeeded | Required |
| refetchAsync | `() => Promise<void>` | Function to refetch the embed metadata     | Required |