Getting Started

Getting Started with VGS Collect React Native SDK

Before you start, you can also check @vgs/collect-react-native GitHub Page and Example Application.

How to Integrate the SDK

Quickstart from Dashboard

You should have your organization registered at VGS Dashboard. A Sandbox Vault will be pre-created for you. Use your VGS Dashboard to start collecting data, then follow the VGSCollectSDK integration guide below.

Integrate VGSCollectSDK into your React Native Project

Step 1: Install the SDK

AI Agent Integration & Assisted Development

To accelerate your integration and ensure your implementation follows VGS best practices, you can use the AGENTS.md file as a context for AI Coding Agents. Attach or reference the URL to the AGENTS.md file to your agent's context: https://github.com/verygoodsecurity/vgs-collect-react-native-public/blob/main/AGENTS.md.

Example System Prompt: "You are an autonomous engineering agent integrating the VGS Collect RN SDK into an existing ReactNative app. Use the contents of AGENTS.md as your authoritative policy. Goals:

1. Add a secure card form (Number, Name, Expiration, CVC).

2. Validate all fields before submission.

3. Provide unit tests for valid/invalid card inputs.”

Manual Installation

VGS Collect SDK is distributed through npm.

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

npm install @vgs/collect-react-native
    

yarn add @vgs/collect-react-native

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

Next

Follow the steps below to build a simple form that collects credit card data and submits it securely to your Vault.

Step 2: Configure Your App

Import the SDK Components:

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

To initialize VGSCollect instance you need to set your Vault id and Environment type.

Initialize VGSCollect:

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

• You can have multiple VGSCollect instances; they will work independently with the fields you configure for each specific instance. - All VGSCollect instances can be configured differently.

There are two steps in the integration process:

• Configuring VGS Collect UI components

• Sending data to VGS

Configure UI Components

Create UI Form with VGS Input components

VGS Collect UI inputs have pre-defined configurations, such as validation and masking. To use a pre-defined configuration, you should use the type field. Available types are described in VGSInputType. More information about VGS Collect UI components is described here.

import { StyleSheet, SafeAreaView, View, Text, TouchableOpacity } from 'react-native';
import { VGSCollect, VGSTextInput, VGSCardInput, VGSCVCInput } from '@vgs/collect-react-native';

const App = () => {
  // Setupt your vauldId and environment
  const collector = new VGSCollect('yourVaultId', 'sandbox');
  
  return (
    <SafeAreaView style={styles.safeArea}>
      <View style={styles.container}>
        <Text style={styles.title}>VGS Collect Example</Text>
        <VGSTextInput
          collector={collector}
          fieldName="card_holder"
          type="cardHolderName"
          placeholder="Name"
          onStateChange={(state: any) => {
            console.log('card_holder state: ', state);
          }}
          containerStyle={styles.inputContainer} // Container-specific styles
          textStyle={styles.inputText} // text-specific styles
        />
        <VGSCardInput
          collector={collector}
          fieldName="card_number"
          placeholder="4111 1111 1111 1111"
          onStateChange={(state: any) => {
            console.log('card_number state: ', state);
          }}
          containerStyle={styles.inputContainer} // Container-specific styles
          textStyle={styles.inputText} // text-specific styles
        />
        <VGSTextInput
          collector={collector}
          fieldName="expiration_date"
          type="expDate"
          placeholder="MM/YY"
          divider="-"
          onStateChange={(state: any) => {
            console.log('expiration_date state: ', state);
          }}
          containerStyle={styles.inputContainer} // Container-specific styles
          textStyle={styles.inputText} // text-specific styles
        />
        <VGSCVCInput
          collector={collector}
          fieldName="card_cvc"
          placeholder="CVC/CVV"
          onStateChange={(state: any) => {
            console.log('card_cvc state: ', state);
          }}
          containerStyle={styles.inputContainer} // Container-specific styles
          textStyle={styles.inputText} // text-specific styles
        />
        <TouchableOpacity
          style={[styles.button, { backgroundColor: 'blue' }]}
          onPress={handleSubmit}
        >
          <Text style={{ color: 'white' }}>Submit</Text>
        </TouchableOpacity>
      </View>
    </SafeAreaView>
  );
};

Setup styles attributes

const styles = StyleSheet.create({
  safeArea: {
    flex: 1,
    backgroundColor: 'white',
  },
  container: {
    flex: 1,
    paddingHorizontal: 20,
    paddingTop: 40,
  },
  title: {
    fontSize: 20,
    marginBottom: 10,
  },
  inputContainer: {
    height: 50,
    borderWidth: 2,
    borderRadius: 8,
    paddingHorizontal: 12,
    backgroundColor: 'white',
    marginBottom: 20,
  },
  inputText: {
    fontSize: 16,
    color: 'black',
  },
  button: {
    backgroundColor: 'blue',
    padding: 15,
    borderRadius: 8,
    alignItems: 'center',
  },
});

Securely collecting and sending information

Use vgsCollect.submit(_:) to collect data from VGS Collect UI components and save it to your secure Vault. You can find additional information on how to send data to your Vault here.

// 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);
    }
  }
};

Check next

• UI Components

• Inputs State

• Submit data