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

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:

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

For Expo apps, use a native development build:

npx expo prebuild
npx expo run:ios
npx expo run:android

Import package-root APIs

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

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.

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:

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.

<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.

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:

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.