> ## Documentation Index
> Fetch the complete documentation index at: https://developer.verilock.io/llms.txt
> Use this file to discover all available pages before exploring further.

# React Native

> Official React Native SDK with UI components and API client.

## Installation

```bash theme={null}
npm install @verilock/react-native-sdk
```

The package depends on `react-native-webview` for the WebView component:

```bash theme={null}
npm install react-native-webview
cd ios && pod install
```

## Overview

The React Native SDK provides three levels of integration:

| Export                 | Use Case                                                            |
| ---------------------- | ------------------------------------------------------------------- |
| `VerilockWebView`      | Simplest -- renders the hosted verification flow in a WebView modal |
| `VerilockVerification` | Native UI component that guides users through each KYC step         |
| `useVerilockSession`   | Hook for fully custom UI with direct upload/submit control          |

It also re-exports the full `Verilock` server API client from `@verilock/node-sdk` for backend calls.

## Server API Client

The SDK re-exports everything from `@verilock/node-sdk`, so you can create sessions from your backend without an additional dependency.

```typescript theme={null}
import { Verilock } from '@verilock/react-native-sdk';

const verilock = new Verilock({ apiKey: 'qi_live_...' });

// Create a session
const session = await verilock.sessions.create({
    applicant_email: 'john@example.com',
    redirect_url: 'https://example.com/callback',
});

// AML screening
const aml = await verilock.aml.screen({ name: 'John Doe' });

// Transaction monitoring
const tx = await verilock.transactions.screen({
    transaction_ref: 'TX-001',
    sender_name: 'Alice',
    receiver_name: 'Bob',
    amount: 5000,
    currency: 'USD',
});
```

<Warning>
  **Keep your API key secure.** The server API client should only be used in backend code or secure server functions, never in the React Native bundle shipped to users.
</Warning>

## VerilockWebView

The simplest integration. Renders the hosted verification flow inside a WebView modal. No camera or native module setup required.

```tsx theme={null}
import { VerilockWebView } from '@verilock/react-native-sdk';

function VerifyScreen({ sessionToken, navigation }) {
    return (
        <VerilockWebView
            sessionToken={sessionToken}
            baseUrl="https://identity.verilock.io"
            onComplete={(result) => {
                console.log(result.decision); // "approved" | "declined" | "review"
                navigation.navigate('Home');
            }}
            onError={(error) => console.error(error.message)}
            onDismiss={() => navigation.goBack()}
            presentAsModal={true}
            theme={{ backgroundColor: '#ffffff' }}
        />
    );
}
```

### VerilockWebView Props

| Prop             | Type                                                 | Default                        | Description                               |
| ---------------- | ---------------------------------------------------- | ------------------------------ | ----------------------------------------- |
| `sessionToken`   | `string`                                             | **required**                   | Session token from the API                |
| `baseUrl`        | `string`                                             | `https://identity.verilock.io` | Base URL of the Verilock Identity service |
| `onComplete`     | `(result: VerilockVerificationResult) => void`       | --                             | Called when verification completes        |
| `onError`        | `(error: VerilockVerificationError) => void`         | --                             | Called on error                           |
| `onDismiss`      | `() => void`                                         | --                             | Called when the user closes the modal     |
| `presentAsModal` | `boolean`                                            | `true`                         | Whether to render inside a `Modal`        |
| `theme`          | `{ primaryColor?, backgroundColor?, borderRadius? }` | --                             | Visual customisation                      |

## VerilockVerification

A native UI component that walks users through each step of verification (welcome, document front, document back, selfie, processing, result). Gives you full control over look and feel with native React Native views.

```tsx theme={null}
import { VerilockVerification } from '@verilock/react-native-sdk';

function VerifyScreen({ sessionToken, navigation }) {
    return (
        <VerilockVerification
            sessionToken={sessionToken}
            onComplete={(result) => {
                if (result.decision === 'approved') {
                    navigation.navigate('Dashboard');
                }
            }}
            onError={(error) => console.error(error.code, error.message)}
            onDismiss={() => navigation.goBack()}
            onStepChange={(step) => console.log('Step:', step)}
            theme={{ primaryColor: '#6366f1' }}
        />
    );
}
```

### VerilockVerification Props

| Prop           | Type                                                 | Default                        | Description                               |
| -------------- | ---------------------------------------------------- | ------------------------------ | ----------------------------------------- |
| `sessionToken` | `string`                                             | **required**                   | Session token from the API                |
| `baseUrl`      | `string`                                             | `https://identity.verilock.io` | Base URL of the Verilock Identity service |
| `onComplete`   | `(result: VerilockVerificationResult) => void`       | --                             | Called when verification completes        |
| `onError`      | `(error: VerilockVerificationError) => void`         | --                             | Called on error                           |
| `onDismiss`    | `() => void`                                         | --                             | Called when the user closes the modal     |
| `onStepChange` | `(step: string) => void`                             | --                             | Called when the verification step changes |
| `theme`        | `{ primaryColor?, backgroundColor?, borderRadius? }` | --                             | Visual customisation                      |

### Steps

The `onStepChange` callback receives one of the following step identifiers:

| Step             | Description                       |
| ---------------- | --------------------------------- |
| `loading`        | Fetching session status           |
| `welcome`        | Intro screen with requirements    |
| `document_front` | Capture front of ID               |
| `document_back`  | Capture back of ID                |
| `selfie`         | Capture selfie                    |
| `processing`     | Submitting and polling for result |
| `result`         | Final decision displayed          |

## useVerilockSession Hook

For fully custom UIs. The hook manages API communication while you control every pixel.

```tsx theme={null}
import { useVerilockSession } from '@verilock/react-native-sdk';

function CustomVerifyScreen({ sessionToken }) {
    const {
        status,
        result,
        error,
        isPolling,
        uploadDocument,
        uploadSelfie,
        uploadAddressProof,
        submitAndPoll,
    } = useVerilockSession({
        sessionToken,
        pollInterval: 2000,   // ms between status checks (default)
        pollTimeout: 120000,  // max polling duration in ms (default)
    });

    const handleDocumentCapture = async (uri: string) => {
        await uploadDocument(uri, 'front', 'passport');
    };

    const handleSelfieCapture = async (uri: string) => {
        await uploadSelfie(uri);
    };

    const handleSubmit = async () => {
        try {
            const result = await submitAndPoll();
            console.log(result.decision);
        } catch (err) {
            console.error('Verification failed:', err);
        }
    };

    if (isPolling) return <ActivityIndicator />;
    if (result) return <ResultScreen decision={result.decision} />;

    return (
        <View>
            {/* Your custom capture UI */}
        </View>
    );
}
```

### Hook Options

| Option         | Type     | Default                        | Description                               |
| -------------- | -------- | ------------------------------ | ----------------------------------------- |
| `sessionToken` | `string` | **required**                   | Session token from the API                |
| `baseUrl`      | `string` | `https://identity.verilock.io` | Base URL of the Verilock Identity service |
| `pollInterval` | `number` | `2000`                         | Milliseconds between status polls         |
| `pollTimeout`  | `number` | `120000`                       | Maximum polling duration in milliseconds  |

### Hook Return Values

| Property             | Type                                          | Description                                             |
| -------------------- | --------------------------------------------- | ------------------------------------------------------- |
| `status`             | `string \| null`                              | Current session status                                  |
| `result`             | `VerilockVerificationResult \| null`          | Final result once completed                             |
| `error`              | `VerilockVerificationError \| null`           | Error if verification fails                             |
| `isPolling`          | `boolean`                                     | Whether the hook is actively polling                    |
| `uploadDocument`     | `(uri, side, documentType?) => Promise<void>` | Upload a document image (`side`: `'front'` or `'back'`) |
| `uploadSelfie`       | `(uri) => Promise<void>`                      | Upload a selfie image                                   |
| `uploadAddressProof` | `(uri, documentType?) => Promise<void>`       | Upload an address proof document                        |
| `submitAndPoll`      | `() => Promise<VerilockVerificationResult>`   | Submit and poll until complete                          |

## Type Reference

```typescript theme={null}
interface VerilockVerificationResult {
    status: 'completed' | 'failed';
    decision: 'approved' | 'declined' | 'review' | null;
    session_id: string;
    risk_score: number | null;
    decline_reason: string | null;
}

interface VerilockVerificationError {
    code: string;
    message: string;
}
```

<Tip>
  Start with `VerilockWebView` for the fastest integration. Move to `VerilockVerification` or `useVerilockSession` when you need more control over the user experience.
</Tip>