# React Native Embedding
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
// ...
;
```
### 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` 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
```
## 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
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
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
{
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
{
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` object.
- Make sure PII is not passed in as extension data, as it is passed directly to your tag manager integrations.
```js
```
### 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
;
```
#### UTM Tracking Example
```js
```
#### Dynamic Campaign Tracking
```js
function CampaignScreen() {
const route = useRoute();
const { campaignId, source } = route.params;
return (
);
}
```
#### User Segment Tracking
```js
function ContestScreen() {
const { userSegment, subscriptionTier } = useUser();
return (
);
}
```
#### Combining with Other Props
Query parameters work alongside form prefill and extension data:
```js
```
#### Using with ExperienceModal
The `ExperienceModal` component also supports `queryParams`:
```js
function CustomModal() {
const [isOpen, setIsOpen] = useState(false);
return (
<>