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 onReact Native code
in the right sidebar. - Copy the
Card embed meta URL
and use it as the value of theembedMetaUrl
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 theformPrefillValues
prop onKomoCardWidget
orExperienceModal
. - 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 theNative 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 andisLoading
state. - The
imageUrl
andimageAspectRatio
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 andonClose
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
oronKomoEvent
props on theExperienceModal
orKomoCardWidget
. - The
onWindowMessage
prop exposes anywindow.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.
- Note: User Interaction Events will also appear in the
<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
andKomoCardWidget
components allow you to set extension data on the user interaction events. - The
extensionDataValues
prop is a plainRecord<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
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 |
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. See react-native-webview docs for more details | 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 |
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 (including both image and CTA button) | 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 (defaults to a skeleton card loader) | 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. See react-native-webview docs for more details | 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 |
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 |