React Native Embedding

Komo cards can be embedded into your React Native application through Komo’s NPM package @komo-tech/react-native-widgets .

Installation

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

NOTE: @komo-tech/react-native-widgets  has a peer dependency on 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.

import { KomoCardWidget } from '@komo-tech/react-native-widgets';
 
// ...
 
<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.

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

import { useFetchCardMetadata } from '@komo-tech/react-native-widgets';
 
// ... 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.

import { CardCover } from '@komo-tech/react-native-widgets';
 
// ... 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.

import { ExperienceModal } from '@komo-tech/react-native-widgets';
 
// ... rest of your component
 
<ExperienceModal
    isOpen={isModalOpen}
    onClose={() => setIsModalOpen(false)}
    embedUrl={metadata?.embedUrl}
    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.

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

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

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

API Reference

ButtonStyle

CardCover Props

CardEmbedMetadata

ExperienceModal Props

KomoCardWidget Props

KomoEvent

useFetchCardMetadata Hook

Options

Result