> ## Documentation Index
> Fetch the complete documentation index at: https://docs-api.kravata.co/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native SDK

> Install the Kravata React Native SDK and render the financial widget in your app.

The React Native SDK is the `kravata-sdk-plugin` package. It exposes `KravataWidgetComponent`, which fills its container. Render it on a dedicated screen. It works with TypeScript and plain JavaScript.

## Requirements

| | Minimum |
| - | - |
| React Native | 0.71.14 |
| React | 18.2.0 |
| Android | `minSdk` 26 (Android 8.0), `compileSdk`/`targetSdk` 33, Java 11 |
| iOS | 13.4, installed with CocoaPods |
| Peer dependencies | `react-native-webview` ≥ 13.0.0, `react-native-device-info` ≥ 10.0.0, `axios` ≥ 1.7.2 |

## Install

<Steps>
  <Step title="Add the dependency">
    The package is distributed from a private GitHub repository. Add it to `package.json` with the GitHub token Kravata gives you and the version tag you want to use:

    ```json package.json theme={"dark"}
    "dependencies": {
      "kravata-sdk-plugin": "git+https://<TOKEN>@github.com/KravataGrp/kravata-sdk-react-native.git#v1.0.4"
    }
    ```

    If your Git credentials for `github.com` already have access, you can use the short form `"github:KravataGrp/kravata-sdk-react-native#v1.0.4"`.

    <Tip>
      Don't commit the token to your repository. In CI, inject it from a secret.
    </Tip>
  </Step>

  <Step title="Install the peer dependencies">
    ```bash theme={"dark"}
    npm install react-native-webview react-native-device-info axios
    ```
  </Step>

  <Step title="Install the iOS pods">
    ```bash theme={"dark"}
    cd ios && pod install && cd ..
    ```
  </Step>

  <Step title="Allow network access on Android">
    Add the Internet permission to `android/app/src/main/AndroidManifest.xml`:

    ```xml theme={"dark"}
    <uses-permission android:name="android.permission.INTERNET" />
    ```

    iOS needs no extra permissions.
  </Step>
</Steps>

## Render the widget

Get `sharedKey`, `nonce` and `clientId` from your backend first (see [Issue a widget session](/sdk/backend#1-issue-a-widget-session)), then render the widget on a full screen.

```tsx KravataScreen.tsx theme={"dark"}
import React, { useEffect, useState } from 'react';
import { ActivityIndicator, StyleSheet, View } from 'react-native';
import { KravataWidgetComponent } from 'kravata-sdk-plugin';

interface WidgetSession {
  sharedKey: string;
  nonce: string;
  clientId: string;
}

interface Props {
  userId: string;        // your own ID for this user
  phoneNumber?: string;
  onClose: () => void;
}

export default function KravataScreen({ userId, phoneNumber, onClose }: Props) {
  const [session, setSession] = useState<WidgetSession | null>(null);

  useEffect(() => {
    // Get a widget session from YOUR backend
    myApi.getKravataWidgetSession().then(setSession);
  }, []);

  if (!session) {
    return <ActivityIndicator style={styles.container} />;
  }

  return (
    <View style={styles.container}>
      <KravataWidgetComponent
        environment="prod"               // 'test' or 'prod'
        tenant="yourTenantName"          // provided by Kravata
        countryCode="57"
        sharedKey={session.sharedKey}
        nonce={session.nonce}
        clientId={session.clientId}
        userId={userId}                  // same ID you send to User Registration
        phoneClient={phoneNumber ?? ''}
        onWidgetEvent={(event) => {
          if (event.type === 'CLOSE_REQUESTED') onClose();
        }}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  container: { flex: 1 },
});
```

### With React Navigation

Register the screen without a header and navigate to it:

```tsx App.tsx theme={"dark"}
<Stack.Navigator>
  <Stack.Screen name="Home" component={HomeScreen} />
  <Stack.Screen name="Kravata" component={KravataScreen} options={{ headerShown: false }} />
</Stack.Navigator>
```

```tsx HomeScreen.tsx theme={"dark"}
navigation.navigate('Kravata');
```

## Parameters

| Parameter | Type | Required | Description |
| - | - | - | - |
| `environment` | `string` | Yes | `'test'` or `'prod'`. |
| `tenant` | `string` | Yes | Tenant name assigned to your company. Kravata gives it to you. |
| `countryCode` | `string` | Yes | Country calling code without `+`, for example `'57'` for Colombia. |
| `sharedKey` | `string` | Yes | Your company's widget key. It must come from your backend; never hard-code it. |
| `nonce` | `string` | Yes | Single-use value generated by your backend for this session. |
| `clientId` | `string` | Yes | Your company's ID as a Kravata partner. It comes from your backend. |
| `phoneClient` | `string` | Yes | User's phone number without the country code. When present, it pre-fills the phone field in the widget. Pass `''` if you don't have it. |
| `userId` | `string` | Yes, for the integration | Your own ID for the user (a UUID v4 is recommended). It is how Kravata correlates the user with your [User Registration](/sdk/backend#3-register-the-user) call and your webhooks. |
| `documentType` | `string` | No | Identity document type: `'CC'`, `'CE'`, `'PA'` or `'NIT'`. |
| `documentNro` | `string` | No | Identity document number. |
| `onWidgetEvent` | `(event) => void` | No | Receives events from the widget. See below. |
| `onLog` | `(message: string) => void` | No | Debug log callback. Leave it out in production. |

### Widget events

| `event.type` | When | Suggested action |
| - | - | - |
| `CLOSE_REQUESTED` | The user asks to leave the widget. | Navigate back to your app. |
| `DEPOSIT_COMPLETED` | The user finished a deposit in the widget. `event.payload` has the details. | Refresh balances in your app. Confirm the operation through the Stack API or [webhooks](/stack/webhooks) before acting on it. |

New event types can be added in future versions; ignore the ones you don't handle.

## Next steps

<CardGroup cols={2}>
  <Card title="Backend integration" icon="server" href="/sdk/backend">
    Issue widget sessions, receive `user.accepted_terms` and register the user.
  </Card>

  <Card title="Overview" icon="diagram-project" href="/sdk/overview">
    Environments, credentials and the end-to-end flow.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.