> For the complete documentation index, see [llms.txt](https://docs.verygoodsecurity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verygoodsecurity.com/vault/developer-tools/vgs-show/react-native-sdk/integration.md).

# Integration

### Getting started

Install the SDK in a React Native app when you need to reveal VGS-protected text, image, or PDF content into native mobile UI.

Before integrating, configure a VGS reveal route for your vault. Your app needs the vault ID, environment, route path, request payload shape, and response `contentPath` values that match that route.

### Requirements

* React `>= 19.1.0`
* React Native `>= 0.81.4`
* iOS or Android target
* A VGS vault and reveal route

Web is intentionally unsupported. Keep imports in native entrypoints or native screens only.

### Install the SDK

```bash
npm install @vgs/show-react-native
```

PDF reveal uses native renderer dependencies bundled by the SDK. Rebuild the native application after installation so React Native links native modules. Use your app's own build commands if they differ from the examples below.

For bare React Native projects:

```bash
npx pod-install
npx react-native run-ios
npx react-native run-android
```

For Expo apps, use a native development build:

```bash
npx expo prebuild
npx expo run:ios
npx expo run:android
```

### Import package-root APIs

Use only exports from `@vgs/show-react-native`.

```tsx
import * as React from "react";
import { Button, SafeAreaView, Text, View } from "react-native";
import {
  VGSShow,
  VGSShowError,
  VGSShowImage,
  VGSShowLabel,
  VGSShowPdf
} from "@vgs/show-react-native";
```

Do not import from `@vgs/show-react-native/src/...`, `lib/...`, or unstable testing helpers.

### Configure VGSShow

Create one `VGSShow` instance per screen or reveal flow. Keep vault and route configuration in build-time or secure runtime configuration, not in user input.

```tsx
const showRef = React.useRef<VGSShow | null>(null);

if (showRef.current === null) {
  showRef.current = new VGSShow({
    id: config.vaultId,
    environment: "sandbox"
  });
}

const vgsShow = showRef.current;
```

Supported initialization options:

| Option        | Description                                                                                            |
| ------------- | ------------------------------------------------------------------------------------------------------ |
| `id`          | VGS vault identifier.                                                                                  |
| `environment` | `"sandbox"`, `"live"`, or a regional live environment such as `"live-eu1"`. Defaults to `"sandbox"`.   |
| `dataRegion`  | Optional region suffix for regional vault routing when using `"sandbox"` or `"live"`.                  |
| `hostname`    | Optional custom hostname. The SDK validates it and falls back to the vault host when validation fails. |

Regional examples:

```ts
const sandboxEuShow = new VGSShow({
  id: config.vaultId,
  environment: "sandbox",
  dataRegion: "eu-1"
});

const liveEuShow = new VGSShow({
  id: config.vaultId,
  environment: "live-eu1"
});
```

### Render subscribed components

Pass the same `VGSShow` instance to every component that should update from one reveal response. Every component needs a non-empty `contentPath` matching the JSON field returned by your reveal route.

```tsx
<VGSShowLabel
  vgsShow={vgsShow}
  contentPath="json.card_number"
  placeholder="**** **** **** ****"
  isSecureText={true}
/>

<VGSShowImage
  vgsShow={vgsShow}
  contentPath="json.card_art"
  contentMode="scaleAspectFit"
/>

<VGSShowPdf
  vgsShow={vgsShow}
  contentPath="json.statement_pdf"
  style={{ width: "100%", height: 360 }}
/>
```

### Send a reveal request

Call `request()` after the components are mounted.

```tsx
async function reveal(): Promise<void> {
  try {
    const result = await vgsShow.request({
      path: "/post",
      method: "POST",
      payload: {
        recordAlias: form.recordAlias
      }
    });

    setStatus(`Reveal completed with HTTP ${result.code}.`);
  } catch (error) {
    if (error instanceof VGSShowError) {
      setStatus(`Reveal failed (${error.code}).`);
      return;
    }

    setStatus("Reveal failed.");
  }
}
```

`request()` resolves with the HTTP status only. Revealed content is decoded into subscribed SDK components and is not returned to the app.

### AI agent integration

This repository ships a public AI skill for SDK integration work:

```bash
npx skills add https://github.com/verygoodsecurity/vgs-show-react-native --skill vgs-show-react-native-guide
```

Use it when asking an AI coding agent to add or review VGS Show React Native usage in an app. It contains SDK-specific rules for secure reveal flows, masking, copy behavior, logging, analytics, tests, and supported public APIs.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verygoodsecurity.com/vault/developer-tools/vgs-show/react-native-sdk/integration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.