Table of Contents

• Introduction
• Features
• Installation
• AI Agent Integration
• Prerequisites
• Quick Start
  • UI Inputs
  • Masking Inputs
  • Custom Validation
• iOS Privacy Manifest
• Privacy
• Documentation
• Releases
• License

Introduction

The @vgs/collect-react-native SDK by Very Good Security (VGS) enables you to securely collect and manage sensitive data such as credit card information and Social Security Numbers (SSNs) within your React Native applications. Leveraging VGS's data protection infrastructure ensures that sensitive information is handled securely, simplifying compliance and enhancing user trust.

Features

• Secure Data Collection: Tokenize sensitive data before it reaches your servers.
• Customizable Input Components: Pre-built components for various data types (e.g., Card Number, CVC, Expiration Date, Social Security Number).
• Real-time Validation: Instant feedback on input validity to enhance user experience.
• Pre-defined Masking: Automatically setup input masks based on data type.
• Easy Integration: Simple setup and integration with existing React Native projects.
• Compliance Ready: Assists in achieving PCI DSS compliance by minimizing the handling of sensitive data.

Installation

Install the @vgs/collect-react-native package using npm or yarn:

# Using npm
npm install @vgs/collect-react-native

# Using yarn
yarn add @vgs/collect-react-native

Ensure you have React Native set up in your project. If not, follow the official React Native "Getting Started" guide.

AI Agent Integration

Use AGENTS.md as the single authoritative context for autonomous coding agents integrating or maintaining this React Native SDK. It lists public APIs, security constraints, validation rules, upgrade & testing expectations.

Minimal System Prompt Example:

You are an autonomous engineering agent integrating the VGS Collect React Native SDK into an existing app.
Use the full contents of AGENTS.md as the authoritative policy.
Constraints:
- Only public exports from package root (no internal imports).
- No raw sensitive data (PAN, CVC, SSN, exp date) in logs or tests.
- Validate all registered fields before submission or tokenization.
- Never persist raw field values; only use provided state booleans/metadata.
Goals:
1. Add a secure card form (card number, name, exp, cvc) with redacted logging (brand + last4 only when valid).
2. Implement a flow that submits data to the sandbox vault and returns aliases.
3. Provide Jest tests for valid/invalid card number and past expiration edge case.
Return: Modified source files only. Do not commit secrets.

Developer Prompt (Inline Example for a Single Task):

Task: Add custom tokenization to include exp date split into month/year using ExpDateSeparateSerializer.
Follow AGENTS.md sections on tokenization & serializers.
Do not alter existing public API; add tests asserting alias keys exp_month & exp_year are returned.

When updating prompts for agents:

• Always reference AGENTS.md explicitly (do not duplicate entire content inline).
• Keep constraints explicit (public API, no sensitive logs, validation required).
• Include concrete acceptance criteria (e.g., which tests must pass, which fields to add).

Prerequisites

You should have your organization registered at the VGS Dashboard. A Sandbox vault is pre-created for you. Use the Dashboard to configure routes and begin collecting data. If you don’t have an organization yet, see the Quick Integration guides. Use your <vaultId> to start collecting data.

Example app

You can check our example application here. To run the example application, follow these steps:

# 1. Download SDK repository
# 2. In root folder run:
npm install
# 3. Navigate to example folder
cd example
# 4. Build example app for iOS or Android
npm run ios
# 5. Later you can start expo server(optional)
npx expo start --clear

Quick Start

Import the SDK Components:

import { VGSCollect, VGSTextInput } from '@vgs/collect-react-native';

Initialize VGSCollect:

const collector = new VGSCollect('yourVaultId', 'sandbox'); // Use 'live' for production

Create Secure Input Fields:

<VGSTextInput
  containerStyle={styles.inputContainer}
  textStyle={styles.inputText}
  collector={collector}
  fieldName="card_holder"
  type="cardHolderName"
  placeholder="Name"
  onStateChange={handleFieldStateChange}
/>

Handle Form Submission:

// Handle submit request
const handleSubmit = async () => {
  try {
    const { status, response } = await collector.submit('/post', 'POST');
    if (response.ok) {
      try {
        const responseBody = await response.json();
        const json = JSON.stringify(responseBody, null, 2);
        console.log('Success:', json);
      } catch (error) {
        console.warn(
          'Error parsing response body. Body can be empty or your <vaultId> is wrong!',
          error
        );
      }
    } else {
      console.warn(`Server responded with error: ${status}\n${response}`);
    }
  } catch (error) {
    if (error instanceof VGSError) {
      switch (error.code) {
        case VGSErrorCode.InputDataIsNotValid:
          for (const fieldName in error.details) {
            console.error(
              `Not valid fieldName: ${fieldName}: ${error.details[fieldName].join(', ')}`
            );
          }
          break;
        default:
          console.error('VGSError:', error.code, error.message);
      }
    } else {
      console.error('Network or unexpected error:', error);
    }
  }
};

NOTE: Each input must set a fieldName that exactly matches the field key configured in your Vault Route settings. This identifier is required for redact/reveal operations on inbound/outbound routes.

UI Inputs

The SDK provides pre-built UI input components for securely collecting sensitive data. The following input components are available:

• VGSTextInput: A versatile, customizable input component.
  • Field Types: You can configure the input's behavior by setting the type prop.
    • Supported types:
      • 'text': General-purpose text input with no predefined settings.
      • 'card': For collecting card numbers.
      • 'cardHolderName': For collecting card holder names.
      • 'expDate': For collecting card expiration dates.
      • 'cvc': For collecting CVC/CVV codes.
      • 'ssn': For collecting social security numbers.
    • Each type includes default configurations for:
      • Validation Rules: Enforces data integrity and compliance.
      • Input Mask: Provides visual guidance and improves user experience.
      • Keyboard Type: Optimizes the on-screen keyboard for the input type.
• VGSCardInput: A specialized input component for collecting card numbers.
  • Features:
    • Predefined type='card'.
    • Dynamically displays the detected card brand based on user input.
• VGSCVCInput: A specialized input component for collecting CVC/CVV codes.
  • Features:
    • Predefined type='cvc'.
    • Displays an icon to guide users in entering the CVC/CVV code.

Masking Inputs

VGS Input components allow you to apply a mask to the input field using the mask prop. This prop accepts a string pattern that defines how the input should be formatted. It uses placeholder characters to define the allowed characters in each position of the mask. The following placeholders are supported:

• #: Any digit (0-9)
• @: Any letter (a-zA-Z)
• a: Any lowercase letter (a-z)
• A: Any uppercase letter (A-Z)
• *: Any alphanumeric character (a-zA-Z0-9)

Here's how to use the mask prop:

<VGSTextInput
  //... other props
  mask="#### #### #### ####" // Example mask for a credit card number
/>

Custom Validation

VGS Input components allow you to re-define default or add custom validation rules to ensure that the input data meets certain criteria. You can use the validationRules prop to pass an array of ValidationRule objects.

Here's a list of the available validation rules:

• NotEmptyRule: Checks if the input is not empty.
• LengthRule: Validates the input length against a minimum and maximum length.
• LengthMatchRule: Checks if the input has an exact specified length.
• PatternRule: Validates the input against a regular expression pattern.
• CardExpDateRule: Checks if the input is a valid card expiration date in the specified format ('mmyy' or 'mmyyyy').
• PaymentCardRule: Validates if the input is a valid payment card number based on the card brand and Luhn check.
• LuhnCheckRule: Performs a Luhn check on the input to validate its integrity (commonly used for credit card numbers).

Here's how to set validation rules:

import { NotEmptyRule, LengthRule, PatternRule } from '@vgs/collect-react-native';

<VGSTextInput
  //... other props
  validationRules={[
    new NotEmptyRule('This field is required'),
    new LengthRule(5, 10, 'Length must be between 5 and 10 characters'),
    new PatternRule('/^[a-zA-Z]+$/', 'Only letters are allowed'),
  ]}
/>

iOS Privacy Manifest

The SDK does not directly package or embed the Privacy Manifest file into your iOS project. Instead, manually copy and update the privacy information from the VGS Privacy Manifest file. Follow the instructions in our documentation.

Privacy

The SDK tracks a few key metrics about feature usage to guide improvements. No personal or raw sensitive data is tracked.

You can opt-out of metrics collection via VGSAnalyticsClient:

VGSAnalyticsClient.getInstance().shouldCollectAnalytics = false

Documentation

• SDK Documentation: https://www.verygoodsecurity.com/docs/vgs-collect/rn-sdk

Releases

To follow @vgs/collect-react-native updates and changes, check the releases page.

License

The VGS Collect React Native SDK is released under the MIT license. See LICENSE for details.