/

Getting Started with VGS Collect iOS SDK

Before you start, you can also check VGSCollectSDK GitHub Page, download Demo Application or browse the SDK Reference.

How to Integrate the SDK

Quickstart from Dashboard

You should have your organization registered at VGS Dashboard. Sandbox Vault will be pre-created for you. You should use your VGS Dashboard to start collecting data. If you don't have any organization registered yet, check the Quick Integration guides. Then follow VGSCollectSDK integration guide below.

Integrate VGSCollectSDK into Your iOS Project

Step 1: Install the SDK

VGSCollectSDK is distributed through CocoaPods and Carthage.

Integrate with CocoaPods

Install the latest version of CocoaPods. Go to Terminal and run the command:

sudo gem install cocoapods
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

If you don't have an existing Podfile in your project, go to your project folder and run the following command to create one:

pod init
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

And then open the file up in Xcode for editing:

open -a Xcode Podfile
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Add VGSCollectSDK pod to Podfile inside your project folder:

target 'MyApp' do
  use_frameworks!

  // Add VGSCollectSDK pod here
  pod 'VGSCollectSDK'

end
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Back to your terminal window and run the following command to install VGSCollectSDK:

pod install
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Use the <your-app>.xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on out.

Update pods(optional)

If you installed VGSCollectSDK before, you might need to update the SDK to the latest version. To do that run in terminal following command:

pod update
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Integrate with Carthage

You should have the latest version of Carthage installed.
Create new Cartfile if it still not in your project and add next line there:

Add VGSCollectSDK to Cartfile

github "verygoodsecurity/vgs-collect-ios"
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Then run in terminal:

carthage update --platform iOS
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Add Framework Builds to your project

Add the VGSCollectSDK.framework build to you project. Note that VGSCollectSDK includes Card.io as dependency for scanning card numbers. You should also link them to your project. Follow the Carthage instructions.

Next

Follow the integration guide to check the example how to create simple form for collecting credit cards data and send it to your Vault.

Step 2: Configure Your App

You need to import VGSCollectSDK framework and initialize VGSCollect instance in your app. To initialize VGSCollect you need to set your Vault id and Environment type:

import UIKit
import VGSCollectSDK

class ViewController: UIViewController {

  /// Initialize VGSCollect instance
  var vgsCollect = VGSCollect(id: "vaultId", environment: .sandbox)

  // ...
}
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format
Note
- You can have multiple VGSCollect instances, they will work independently with fields that you configure with each specific VGSCollect instance.
- All VGSCollect instances can be configured in a different way.

There are two-steps in the integration process: configuring VGS Collect UI components and sending data to VGS.

Configure UI Components

Create UI Form

Add VGS Collect UI components to your view and setup layout. More info about VGS Collect UI components described here.

import UIKit
import VGSCollectSDK

class ViewController: UIViewController {

    /// Initialize VGSCollect instance
    var vgsCollect = VGSCollect(id: "vauiltId", environment: .sandbox)

    /// VGS UI components
    var cardNumberField = VGSCardTextField()
    var cardHolderNameField = VGSTextField()
    var expCardDateField = VGSTextField()
    var cvcField = VGSTextField()

    /// Native UI components
    lazy var sendButton: UIButton = {
      let button = UIButton()
      button.layer.cornerRadius = 4
      button.backgroundColor = .systemBlue
      button.setTitle("Send", for: .normal)
      button.addTarget(self, action: #selector(sendData), for: .touchDown)
      return button
    }()

    override func viewDidLoad() {
        super.viewDidLoad()

        setupLayout()
        setupFieldsConfiguration()
    }

    /// Create UI form for collecting credit cards data
    func setupLayout() {
        let stackView = UIStackView.init(arrangedSubviews: [cardHolderNameField, cardNumberField, expCardDateField, cvcField, sendButton])
        stackView.axis = .vertical
        stackView.spacing = 8
        stackView.distribution = .fillEqually
        stackView.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(stackView)
        NSLayoutConstraint.activate([
            stackView.leftAnchor.constraint(equalToSystemSpacingAfter: view.leftAnchor, multiplier: 2),
            view.rightAnchor.constraint(equalToSystemSpacingAfter: stackView.rightAnchor, multiplier: 2),
            stackView.topAnchor.constraint(equalTo: view.topAnchor, constant: 120),
            stackView.heightAnchor.constraint(equalToConstant: 250)
        ])
    }

    func setupFieldsConfiguration() {}

    @objc
    func sendData() {}
}
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Setup VGS Collect Fields

Each VGSTextField should be configured with VGSConfiguration. More about fields configuration described here.

//...

func setupFieldsConfiguration() {

    /// Create card number field configuration
    let cardConfiguration = VGSConfiguration(collector: vgsCollect, fieldName: "card_number")
    cardConfiguration.type = .cardNumber
    cardConfiguration.isRequiredValidOnly = true

    /// Setup configuration to card number field
    cardNumberField.configuration = cardConfiguration
    cardNumberField.placeholder = "Card Number"

    /// Configure card holder name field
    let nameConfiguration = VGSConfiguration(collector: vgsCollect, fieldName: "card_cardHolderName")
    nameConfiguration.type = .cardHolderName
    cardHolderNameField.configuration = nameConfiguration
    cardHolderNameField.placeholder = "CardHolder Name"

    /// Configure card expiration date field
    let expDateConfiguration = VGSConfiguration(collector: vgsCollect, fieldName: "card_expirationDate")
    expDateConfiguration.type = .expDate
    expCardDateField.configuration = expDateConfiguration
    expCardDateField.placeholder = "Exp Date"

    /// Configure card cvc  field
    let cvcConfiguration = VGSConfiguration(collector: vgsCollect, fieldName: "card_cvc")
    cvcConfiguration.type = .cvc
    cvcField.configuration = cvcConfiguration
    cvcField.placeholder = "CVC"
    cvcField.isSecureTextEntry = true

    vgsCollect.textFields.forEach { textField in
      textfield.font = UIFont.systemFont(ofSize: 22)
      textfield.padding = UIEdgeInsets(top: 8, left: 8, bottom: 8, right: 8)
      textfield.textColor =  .darkGray
      textfield.textAlignment = .natural
      textfield.tintColor = .lightGray
    }
}

  // ...
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Observe VGSTextField States

You can observe VGSTextField state during user interaction with fields. Read more about observing states here.

//...
override func viewDidLoad() {
    super.viewDidLoad()

    setupLayout()
    setupFieldsConfiguration()

    /// Observing text fields
    vgsCollect.observeStates = { textfields in

        textfields.forEach({ textField in
            print(textField.state.description)

            /// CardState - extended state for VGSCardTextField
            if let cardState = textField.state as? CardState {
                print(cardState.cardBrand.stringValue)
            }
        })
    }
}
//...
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Securely collecting and sending information

Use vgsCollect.sendData(_:) to collect data from VGS Collect UI components and save it to your secure Vault. More about sending data to your Vault described here.

// ...
@objc
func sendData() {

    /// Check if textfields are valid
    vgsCollect.textFields.forEach { textField in
        textField.borderColor = textField.state.isValid ? .lightGray : .red
    }
    
    /// extra information will be sent together with all sensitive information from VGSCollect fields
    var extraData = [String: Any]()
    extraData["customKey"] = "Custom Value"

    vgsCollect.sendData(path: "/post", extraData: extraData) { [weak self](response) in
        switch response {
          case .success(_, let data, _):
            if let data = data, let jsonData = try? JSONSerialization.jsonObject(with: data, options: []) as? [String: Any] {
              print(String(data: try! JSONSerialization.data(withJSONObject: jsonData["json"]!, options: .prettyPrinted), encoding: .utf8)!)
            }
            return
          case .failure(let code, _, _, let error):
            switch code {
            case 400..<499:
               // Wrong request. This also can happend when your Routs not setup yet or your <vaultId> is wrong
               print("Wrong Request Error: \(code)")
            case VGSErrorType.inputDataIsNotValid.rawValue:
              if let error = error as? VGSError {
                print("Input data is not valid. Details:\n \(error)")
              }
            default:
              print("Something went wrong. Code: \(code)")
            }
          return
        }
    }
}
This is a sample VGS echo server
This is a login from access credentials
This is a password from access credentials
This is a HTTP port number to access
This is a  sample VGS alias  in a generic format
This is a sample test  vault id
This is a username/password pair of  access credentials  for a sample test vault
This is a sample  vault url, that contains the vault id and the sandbox environment
This is a sample  vault host,  which contains sample test vault id and sandbox environment
This is a current Organization ID
This is a current vault id
The unique name that identifies a specific iframe
This is a  sample VGS alias  in a generic format

Check next