# Komo React Native SDK
Embed Komo content in your React Native applications.
## Installation
```sh
pnpm add @komo-tech/react-native
```
NOTE: This package 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 [`KomoCard`](#komocard-props) 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.
```js
import { KomoCard } from '@komo-tech/react-native';
// ...
;
```
### Provider Auth
Use `KomoClientProvider` when your app should share one authenticated Komo session across all `KomoCard` and direct `KomoExperienceModal` usage beneath it.
```tsx
import { KomoCard, KomoClientProvider } from '@komo-tech/react-native';
({
type: 'jwt',
token: await getHostJwt()
})}
>
;
```
`getIdentityToken` is required. It must return the identity payload used by Komo session exchange.
Authentication failures are reported as `KomoAuthError`. Use `onAuthError` for global logging/UI and catch `identify()` for user-triggered retry flows.
```tsx
import { isKomoAuthError } from '@komo-tech/react-native';
{
const token = await getHostJwt();
return token ? { type: 'jwt', token } : { type: 'none' };
}}
onAuthError={(error) => {
switch (error.code) {
case 'identity_provider_failed':
showAuthServiceUnavailableMessage();
break;
case 'invalid_identity':
reportSdkConfigurationError(error.message);
break;
case 'token_invalid':
promptUserToSignInAgain();
break;
default:
logAuthError(error.code, error.message, error.retryable);
break;
}
}}
>
;
const retryIdentify = async () => {
try {
await komo.identify();
} catch (error) {
if (isKomoAuthError(error) && error.retryable) {
showRetryPrompt();
}
}
};
```
`KomoAuthError.code` values:
| Code | Source | Meaning |
| --------------------------- | ------ | -------------------------------------------------------------------------------- |
| `identity_provider_failed` | `app` | `getIdentityToken` threw or rejected |
| `invalid_identity` | `sdk` | Identity payload missed required fields, for example empty JWT token |
| `network_error` | `sdk` | SDK could not reach Komo auth endpoints |
| `session_request_failed` | `komo` | Komo request failed without a known structured reason |
| `app_not_found` | `komo` | Workspace app was not found, active, or available |
| `origin_not_permitted` | `komo` | Request origin is not permitted for this workspace app |
| `type_not_permitted` | `komo` | Identity type or custom provider is not permitted for this workspace app |
| `token_invalid` | `komo` | Host JWT is expired, malformed, tampered, wrong-signature, or has invalid claims |
| `attendee_not_found` | `komo` | Eventbase or Thuzi custom provider attendee was not found |
| `upstream_unavailable` | `komo` | Eventbase, Thuzi, or Rainfocus custom provider service was unavailable |
| `oauth2_not_supported` | `komo` | OAuth2 SDK exchange is not supported |
| `contact_resolution_failed` | `komo` | Komo could not resolve the authenticated contact |
| `handoff_invalid` | `komo` | Handoff token is invalid |
| `handoff_expired` | `komo` | Handoff token is expired |
| `handoff_consumed` | `komo` | Handoff token was already used |
| `sdk_instance_mismatch` | `komo` | Handoff token was issued to another SDK instance |
| `unknown` | `sdk` | Failure did not match a known error shape |
Host JWT expiry maps to `token_invalid`.
Provider mode appends `komo_session` to embedded experience URLs. It does not use legacy per-open `embedAuthUrl` or `authPassthroughParams` flows. If those props are supplied under `KomoClientProvider`, they are ignored and a development-only warning is logged.
Apps that do not use `KomoClientProvider` keep existing behavior, including Auth0 session transfer with `embedAuthUrl` and `authPassthroughParams`.
### 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 [`KomoCard`](#komocard-props) or [`KomoExperienceModal`](#komoexperiencemodal-props).
- 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 [`useCardMetadataQuery`](#usecardmetadataquery) hook and the `Native embed URL` copied from the platform to fetch the [CardEmbedMetadata](#cardembedmetadata).
- The [CardEmbedMetadata](#cardembedmetadata) has the information required to render the cover image (`imageUrl`) and the URL (`embedUrl`) that the [KomoExperienceModal](#komoexperiencemodal-props) 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](#cardembedmetadata), you can pass that to the other components that you want to use.
```js
import { useCardMetadataQuery } from '@komo-tech/react-native';
// ... rest of your component
const { data, isLoading, isError } = useCardMetadataQuery({
embedMetaUrl: KomoCardNativeEmbedUrl
});
// ... use the data.
```
### Render a Card Cover
- The [`KomoCardCover`](#komocardcover-props) 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](#cardembedmetadata).
```js
import { KomoCardCover } from '@komo-tech/react-native';
// ... rest of your component
doSomethingOnCoverClicked()}
metaButtonStyle={metadata?.buttonStyle}
containerStyle={{ borderRadius: 8 }}
/>;
```
### Using the Experience Modal
- The [`KomoExperienceModal`](#komoexperiencemodal-props) 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](#cardembedmetadata).
- If you have forced OAuth enabled and are not using `KomoClientProvider`, you also need to pass through the `embedAuthUrl` from [CardEmbedMetadata](#cardembedmetadata).
```js
import { KomoExperienceModal } from '@komo-tech/react-native';
// ... 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 [`KomoExperienceModal`](#komoexperiencemodal-props) without rendering our KomoCardCover.
```js
// ... rest of your component
const { data, isLoading } = useCardMetadataQuery({
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 [`KomoExperienceModal`](#komoexperiencemodal-props) or [`KomoCard`](#komocard-props).
- The `onWindowMessage` prop exposes any `window.postMessage` events from the embedded experience.
- The `onKomoEvent` prop exposes any [User Interaction Events](https://developers.komo.tech/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 [`KomoExperienceModal`](#komoexperiencemodal-props) and [`KomoCard`](#komocard-props) components allow you to set [extension data](https://developers.komo.tech/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 the embedded experience URL using the `queryParams` prop.
#### Usage
```js
import { KomoCard } from '@komo-tech/react-native';
;
```
#### Common Use Cases
**UTM Tracking:**
```js
```
**Dynamic Campaign Tracking:**
```js
import { KomoCard } from '@komo-tech/react-native';
import { useRoute } from '@react-navigation/native';
function CampaignScreen() {
const route = useRoute();
const { campaignId, source } = route.params;
return (
);
}
```
**User Segment Tracking:**
```js
import { KomoCard } from '@komo-tech/react-native';
import { useUser } from './hooks/useUser';
function ContestScreen() {
const { userSegment, subscriptionTier } = useUser();
return (
);
}
```
#### Combining with Other Props
Query parameters work alongside form prefill and extension data:
```js
```
#### Using with KomoExperienceModal
The `KomoExperienceModal` component also supports `queryParams`:
```js
import { KomoExperienceModal } from '@komo-tech/react-native';
function CustomModal() {
const [isOpen, setIsOpen] = useState(false);
return (
<>