VGS Collect

What is it?

VGS Collect is a JavaScript library that allows you to securely collect data from your users via forms without having to have that data pass through your systems. The form fields behave like traditional input fields while securing access to the unsecured data.

Once the fields are initialized VGS Collect communicates the state of the fields through JavaScript callbacks. The callback includes a state object that includes information about the validity, focused value and if the user has entered information in the field to allow you to control feedback to your user.

Getting Started Guide

To quick start with VGS Collect sign up and watch this video.

Proceed with integration guide to set it up.

Integration

Just a few steps separate you from using the VGS Collect library.

1. Create a VGS Vault

First of all, you should sign up with VGS and create a Vault for your organization. Skip this step if you already have one.

2. Include generated JS file into your application

Go to the Dashboard/VGS Collect tab:

'VGS Collect page'

We will generate specific JS file for your organization, which you can easily include to your project using the following code.

<script type="text/javascript" src="https://js.verygoodvault.com/vgs-collect/1/<organization-id>.js"></script>

3. Initialize VGS Collect

Use the following code to initialize VGS Collect form.

VGSCollect.create(environment, onUpdateCallback) → Form
environment String
Your vault id , that this form will submit to.
onUpdateCallback Function
Callback that will be called whenever the form state changes. It receives the state object.
state Object
Representing the current state of a form.
  • isDirty - checks if you put any changes to the field
  • isFocused - shows if the field in a focus right now
  • errorMessages - an array of error messages for a specific field
  • isValid - shows field validity
  • name - shows field name
  • isEmpty - determines whether the field is empty
return Form
Initialized VGS Collect form.

Example:

const form = VGSCollect.create('tntgwauwbm1', // Please, use your own vault id
               function(state) {
                  // Example of the `state` object:
                  //   {
                  //    "form.field_name": {
                  //      "isDirty": false,
                  //      "isFocused": false,
                  //      "errorMessages": [
                  //        "is required"
                  //      ],
                  //      "isValid": false,
                  //      "name": "form.field_name",
                  //      }, ...
                  //   }
            });

4. Create and setup form fields

You should initialize each field in a form using the code below.

Form#field(selector, properties) → Field
selector String
CSS selector that points to the element where the field will be added.
properties Object
Field settings object.
  • name - required name of the input field. Will be used when submitting the data.
  • type - required type of the input field.
  • validations - array of validations that will be used to calculate the isValid state.
  • placeholder - text displayed when the field is empty.
  • successColor - text color when the field is valid.
  • errorColor - text color when the field is invalid.
  • color - text color.
  • lineHeight- line height value.
  • fontSize - size of text.
  • fontFamily - font family used in the text.
  • serializers - you could use this to format how you want to receive the data. Example: maybe you want to take a phone number in a text field as XXX-XXX-XXX but don’t want the dashes, the example below shows how to remove them.
  • options - set the values for dropdown.
  • defaultValue - set default value to dropdown.
  • value - set value to checkbox or radio button.
return Field
Initialized VGS Collect field.

Expiration date separation

If you want to get a month and year values separately, add form.SERIALIZERS.separate() function to the expiration date field initialization.

Example:

form.field('#space-for-my-field', {
      type: 'card-expiration-date',
      name: 'expirationDateCustom',
      placeholder: '01 / 2019',
      serializers: [form.SERIALIZERS.separate({monthName: ' <month_custom_name>', yearName: '<year_custom_name>'})],
      validations: ['required', 'validCardExpirationDate']
  });

VGS Collect will pass this data in the following structure:

{expirationDateCustom: { month_custom_name: '<value>', year_custom_name: '<value>'} }

Field focus

You can explicitly add the focus to the field using our Field .focus() method:

Field#focus()

Example:

const field = form.field('#space-for-my-field', { ... });

document.querySelector('[for=filed]').addEventListener('click', function() {
  field.focus();
});

Examples of different field types:

form.field('#space-for-my-field', {
    name: 'cc-number', // REQUIRED
    type: 'card-number', // REQUIRED
    successColor: '#3c763d',
    errorColor: '#a94442',
    color: '#31708f',
    lineHeight: '1.5rem',
    fontSize: '24px',
    fontFamily: 'Comic Sans',
    placeholder: 'Card number',
    validations: ['required'],

    serializers: '[{ name:"replace", options: {old:"-", new:""}}]',
});
form.field('#space-for-my-field', {
    type: 'dropdown',
    name: 'car.manufacturer',
    placeholder:"Car manufacturer",
    options: [
        {value: "volvo", text: "Volvo"},
        {value: "saab", text: "Saab"},
        {value: "opel", text: "Opel"},
        {value: "audi", text: "Audi"}
    ],
    defaultValue: "volvo",
    validations: ['required']
});
form.field('#space-for-my-field', {
    type: 'checkbox',
    name: 'agreement',
    value: "accept",
    validations: [],
});
form.field('#space-for-my-field', {
    type: 'radio',
    name: 'profile-visible',
    value: "true",
    validations: []
});
form.field('#space-for-my-field', {
    type: 'textarea',
    name: 'comments',
    placeholder: 'Leave your comments here',
    validations: []
});

5. Take a look at additional properties field options

Available validations types:

  • required - use it for the required fields.
  • validCardExpirationDate - use it for the card expiration date field.
  • validCardNumber - use it for the card number field.
  • validCardSecurityCode - use it for the card security code field.

Available type values:

  • text - text input field
  • textarea - textarea input field
  • checkbox - checkbox input field
  • radio - radio button
  • password - input field with contains password
  • number - input field contains numbers
  • zip-code - input field for zip-code
  • card-number - input field for card number
  • card-security-code - input field for card security code
  • card-expiration-date - input field for card expiration date

Get The Last 4 Digits of Credit Card Numbers:

Property last4 is only available on type: 'card-number' values. last4 is by default null, it only contains a value when the card number is valid.

Example:

const form = VGSCollect.create('development', function(state) {
  $('#my-element').val(state["card.number"].last4);
});

6. Setup form submission

Form#submit(path, options, callback, errorCallback) → Form
path String
Path that the form will be submitted to.
options Object

Options object that can include additional serializer, data, mapDotToObject and request headers.

Option Types
serializer
deep - provides deep serialization.
flat - provides flat serialization.
serialization
json - default value. Will generate JSON data.
formData - construct a set of a key/value pairs representing form fields and their values.
mapDotToObject
Makes it possible to convert a dot-separated field name string into a JSON object:
true
false
merge - will convert a dot-separated field name string into a JSON
object and merge it with data you passed inside data property.
callback Function
Callback that will be executed when the HTTPRequest is finished. The callback receives the HTTP status code and the data as two arguments.
errorCallback Function
Error handling callback.

Example:

form.submit('/tokenize', {
  serializer: 'deep',
  serialization: 'formData',
  data: {
    customerEmail: 'joe@example.com',
  },
  headers: {
  'x-application': 'MyApplication 2.8.3',
  },
  }, function(status, response) {
    console.log("Response has been received", status, response);
  }, function(errors) {});
// field initialization
form.field('#cc-name', {
    type: 'text',
    name: 'card.name', // will convert dot to an object
    placeholder: 'Joe Business',
    validations: ['required'],
});

form.submit('/tokenize', {
    mapDotToObject: true,
    data: {
      customerEmail: 'joe@example.com',
    },
    headers: {
      'x-application': 'MyApplication 2.8.3',
    },
    },
    function(status, response) {
      console.log("Response has been received", status, response);
    }, function(errors) {}
);

// Will pass the following JSON:
   {
       customerEmail: 'joe@example.com',
       card: {
           name: '<name>',
       }
   }
// Please note! ``mapDotToObject: true`` will overwrite the data with the equivalent name inside the data property
// you passed to submit function. Use ``mapDotToObject: merge`` to merge your data and values from the form.

7. Setup inbound route

To secure data via VGS Collect form, you should create an inbound route for the fields you want to secure. You can follow our Getting Started guide to find information about how to setup inbound route properly, or add a new filter to an existing route.

VGS Collect use cases

You can try how it works on our VGS Collect Examples Page.

Use cases code examples:

Styling

Currently to style the generated form fields, you can use single classes and ids as seen in the example iframes. Using multiple classes will not apply bootstrap themes to the static-input divs. These are sandboxed styles, but we are working to make more customization available in the way VGS Collect looks in fills without manual css.