Skip to Content
Embed SDKReact Native

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

NameTypeDescriptionRequired
textstring?Text to display on the button
Optional
backgroundColorstring?Background color of the button
Optional
colorstring?Text color of the button
Optional

CardCover Props

NameTypeDescriptionRequired
onClick() => voidThe callback for when the cover is clicked
Required
isLoadingbooleanWhether the cover is loading
Required
isErrorboolean?Whether the cover is in an error state
Optional
loaderReactNode?Override the default skeleton loader
Optional
errorDisplayReactNode?Override the default error display
Optional
metaButtonStyleButtonStyle?The button style returned from the embed metadata endpoint
Optional
overrideButtonStyleStyleProp<ViewStyle>?Override the button style
Optional
overrideButtonTextStyleStyleProp<TextStyle>?Override the button text style
Optional
containerStyleStyleProp<ViewStyle>?Override the container style
Optional
coverImageStyleStyleProp<ImageStyle>?Override the cover image style
Optional
hideCoverButtonboolean?Whether to hide the cover button
Optional
imageUrlstring?The url of the cover image
Optional
imageAspectRationumber?The aspect ratio of the cover image
Optional

CardEmbedMetadata

NameTypeDescriptionRequired
titlestring?The title of the card
Optional
imageUrlstring?URL of the card's cover image
Optional
imageHeightnumber?Height of the cover image in pixels
Optional
imageWidthnumber?Width of the cover image in pixels
Optional
imageAspectRationumber?Aspect ratio of the cover image
Optional
embedUrlstring?URL for the embedded experience
Optional
buttonStyleButtonStyle?Styling for the card's button
Optional

ExperienceModal Props

NameTypeDescriptionRequired
isOpenbooleanWhether the modal is open
Required
onClose() => voidCallback for when close is requested
Required
embedUrlstringThe URL of the embedded card experience
Required
modalHeaderReactNodeOverride the default modal header
Optional
shareClickUrlstringOverride the url that redirects a user when clicking on a share link
Optional
appIdstringAn identifier for the embedded Komo content
Optional
formPrefillValuesRecord<string, string>Prefill values for the form within the experience
Optional
extensionDataValuesRecord<string, string | number | boolean | object>Extension data values for the experience
Optional
loadingIndicatorReactNodeOverride the default loading indicator
Optional
modalPropsModalPropsOverride the default modal props
Optional
loadingTimeoutMsnumberTimeout in milliseconds before showing error state. Defaults to 15000ms
Optional
errorDisplay({ onRetry }: { onRetry: () => void }) => ReactNodeOverride the default error display
Optional
onFileDownloadWebViewProps["onFileDownload"]Callback for when a file download is requested. Only applies to iOS. See react-native-webview docs for more details
Optional
onKomoEvent(event: KomoEvent) => voidCallback for when a Komo event is raised in the embedded experience
Optional
onWindowMessage(event: any) => voidCallback for when a window message is raised in the embedded experience
Optional

KomoCardWidget Props

NameTypeDescriptionRequired
embedMetaUrlStringThe native embed url taken from the Komo portal settings of the card to be embedded
Required
appIdStringUseful for the embedded Komo content to identify where it's being embedded
Optional
containerStyleStyleProp<ViewStyle>Style overrides for the container of the card cover (including both image and CTA button)
Optional
coverImageStyleStyleProp<ImageStyle>Style overrides for the image of the card cover
Optional
buttonStyleStyleProp<ViewStyle>Style overrides for the CTA button of the card cover
Optional
buttonTextStyleStyleProp<TextStyle>Style overrides for the CTA button text of the card cover
Optional
coverLoaderReactNodeThe loader shown while the cover is loading (defaults to a skeleton card loader)
Optional
coverErrorDisplayReactNodeOverride the default error display for the cover
Optional
hideCoverButtonBooleanHide the CTA button of the cover
Optional
modalHeaderReactNodeThe header of the modal to render instead of the default
Optional
onError(error) => voidCallback for when an error occurs during querying the embed metadata endpoint
Optional
onModalClose() => voidCallback on modal close
Optional
onModalOpen() => voidCallback on modal open
Optional
shareClickUrlStringOverride of the url that redirects a user when clicking on a share link
Optional
formPrefillValuesRecord<string, string>Prefill values for the form within the experience
Optional
extensionDataValuesRecord<string, string | number | boolean | object>Extension data values for the experience
Optional
onFileDownloadWebViewProps["onFileDownload"]Callback for when a file download is requested. Only applies to iOS. See react-native-webview docs for more details
Optional
onKomoEvent(event: KomoEvent) => voidCallback for when a Komo event is raised in the embedded experience
Optional
onWindowMessage(event: any) => voidCallback for when a window message is raised in the embedded experience
Optional

KomoEvent

NameTypeDescriptionRequired
eventNamestringThe name of the event
Required
eventDataanyObject containing the event data
Required
extensionDataRecord<string, string | number | boolean | object>Extension data raised along with the event
Required

useFetchCardMetadata Hook

Options

NameTypeDescriptionRequired
embedMetaUrlstringThe URL of the embed metadata for the card, copied from the Komo Portal
Required
isEnabledbooleanWhether the embed metadata query is enabled. Defaults to true
Optional
onError(e: any) => voidCallback for when an error occurs during querying the embed metadata endpoint
Optional

Result

NameTypeDescriptionRequired
dataCardEmbedMetadata?The embed metadata for the card
Optional
isLoadingbooleanWhether the embed metadata is loading
Required
isErrorbooleanWhether the embed metadata query failed
Required
isSuccessbooleanWhether the embed metadata query succeeded
Required
refetchAsync() => Promise<void>Function to refetch the embed metadata
Required