@komo-tech/react-native-widgets v1.0.3

Embed Komo content in your React Native applications.

Installation

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

NOTE: This package 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 content (i.e. 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}
/>

Metadata model

CardEmbedMetadata

ButtonStyle

Hooks

useFetchCardMetadata

A hook for fetching card metadata from the Komo platform.

Options

Result

Components

CardCover Props

ExperienceModal Props

KomoCardWidget Props