/

Observing States and Sending Data

There are three types of states available that depends on choosen FieldType in VGSConfiguration: State, CardState and SSNState.

State

An object you use for observing VGSTextField parameters that depends on input and VGSConfiguration.

Declaration

class State
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

You should not create State object by itself. Instead, get access to it from VGSTextField.state attribute. State object and it's attributes are read-only.

Some of State attributes

AttributeType/Default value
fieldNameVGSConfiguration.fieldName associated with VGSTextField
isValidContains VGSTextField current validation state
inputLengthContains user input characters count in VGSTextField

To get a full list of State attributes check VGSCollectSDK Reference docs

CardState

An object you use for observing VGSTextField parameters when VGSConfiguration.type defined as FieldType.cardNumber.

Declaration

class CardState: State
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

CardState extends default State with more specific attributes related to credit card numbers

CardState attributes

AttributeType/Default value
last4Last 4 digits of the valid card number
binBin digits of the valid card number
cardBrandCardType object describing Credit Card Brand of the card number
Note
- bin and last4 attributes will be empty until the input card number is valid.

To get a full list of supported card brands check VGSCollectSDK Reference docs

SSNState

An object you use for observing VGSTextField parameters when VGSConfiguration.type defined as FieldType.ssn.

Declaration

class SSNState: State
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

SSNState extends default State with more specific attributes related to social security numbers

SSNState attributes

AttributeType/Default value
last4Last 4 digits of the valid card number
Note
- last4 attributes will be empty until the input social security number is valid.

Code example

/// Observe active textfield
vgsCollect.observeState = { textField in

   /// CardState is extended State for textfields with type .cardNumber
   if let cardState = textField.state as? CardState {
      if cardState.cardBrand.cardLengths.contains(cardState.inputLength) {
        print("User add full card number")
      }
      if cardState.isValid {
        print("\(cardState.cardBrand.stringValue): \(cardState.bin)******\(cardState.last4)")
      }
   }

   /// SSNState is extended State for textfields with type .ssn
   else if let ssnState = textField.state as? SSNState {
      if ssnState.isValid {
        print("\(ssnState.last4)")
      }
   }
}
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

VGSCollect

An object you use for observing VGSTextField states and send data

Declaration

class VGSCollect
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

Creating a VGSCollect

init(id: String, environment: 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
• All VGSCollect instances in the app will be working independently and only with fields that have them in VGSConfiguration settings.
• All VGSCollect instances can be configured differently.

Catching States from text fields

You can observe states every time VGSTextField input is changed. Observer callback will be called on each VGSTextField's interaction event. For more granular editing events handler, check VGSTextFieldDelegate methods.

/// Observe only focused text field
var observeFieldState: ((_ textField: VGSTextField) -> Void)?

/// Observe all text fields registered in a VGSCollect instance
var observeStates: ((_ form: [VGSTextField]) -> Void)?
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

Code example

// ...

/// Observe all textfields states on editing
vgsCollect.observeStates = { textFields in

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

         /// CardState is extended state for textfields with type .cardNumber
         if let cardState = textField.state as? CardState, cardState.isValid {
              print("\(cardState.cardBrand.stringValue): \(cardState.bin)******\(cardState.last4)")
         }
    })
}
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 data

Send data to your organization vault

func sendData(path: String, method: HTTPMethod = .post,
                         extraData: [String: Any]? = nil,
                  completion block: @escaping (VGSResponse) -> Void)
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
  • path: String, inbound rout path
  • method: HTTPMethod, default is .post
  • extraData: [String: Any]?, any data you want to send together with data from VGSTextFields, default is nil
  • completion: VGSResponse completion block, called in the main thread.

Send data request will return VGSResponse.failure(_:) case if:

  • response status code is not valid(other then [200..<300])
  • request is not available by iOS system(like no internet connection)
  • when data that user try to send is not valid in accordance with VGSConfiguration settings.

Errors can be returned in the NSURLErrorDomain and VGSCollectSDKErrorDomain.
For more details check SDK Reference Docs.

Note
• Data will be collected from all text fields that registered to current VGSCollectinstance and send to your organization vault id.
• By default aliases are not a part of response data for sendData(_:) request. It's your responsibility to configure a response for the client after the data goes through the Inbound Proxy to your backend. However, if you test sendData(_:) request with our echo server, you will get a response with the same body as in the request, where the raw data will be redacted to aliases.

Code example

// ...

/// Send data to your organization vault
func sendData(_ sender: UIButton) {

    /// extra information can be sent together with all sensitive data from VGSTextFields
    var extraData = [String: Any]()
    extraData["cardHolderName"] = "Joe Business"

    /// send data to your Vault
    vgsCollect.sendData(path: "/post", method: .post, extraData: extraData) { [weak self](response) in
      switch response {
        case .success(let code, let data, let response):
          // parse data
        case .failure(let code, let data, let response, let error):
          // handle failed request
          switch code {
            // handle error codes
          }
      }
    }
}
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
• If you need to send files data, check VGSFilePickerController.

Sending custom data

In case if you need to send any extra data you can add it to extraData field insendData(_:) request.

Code example

// ...

/// extra information can be sent together with all sensitive data from VGSTextFields
var extraData = [String: Any]()
extraData["cardHolderName"] = "Joe Business"

/// send data to your Vault
vgsCollect.sendData(path: "/post", extraData: extraData) { [weak self](response) in
  switch response {
    // ...
  }
}
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

Setting Custom API Headers

In case if you need additional headers in sendData(_:) request, there is possibility to add them

var customHeaders: [String: String]?
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

Code example

// ...

/// set custom headers
vgsCollect.customHeaders = [
    "custom header": "custom data"
]
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

VGSResponse

An object you use to handle SDK request completion.

Declaration

@frozen enum VGSResponse

    /// Success response case
    case success(_ code:Int, _ data:Data?, _ response: URLResponse?)

    /// Failed response case
    case failure(_ code:Int, _ data:Data?, _ response: URLResponse?, _ error:Error?)
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 more details about VGSResponse at SDK Reference Docs

Advanced Settings

Setting Custom JSON Structure

When you need to send data in a specific json structure you can do it by adding . notation into VGSConfiguration fieldName string. Each . in a fiealdName will create a new level of nesting.

Code example

/// Define field names
let userId = "userId"
let cardNumberFieldKey = "card_data.card_number"
let cardCVCFieldKey = "card_data.cvc"

/// Example of transformed JSON structure on sendData(_:)
{
  "userId": "id12345",
  “card_data: {
           “card_number”:  411111111111111”,
           “cvc”: “123”
         }”
}
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
• If there are two fieldNames with equal names - they will be overwritten.
• If object structure and field name in extraData are same as defined in VGSConfiguration fieldName, value in extraData will be overwritten by data collected from VGSCollect elements with same name on sendData(_:).

Dot "." notation doesn’t work for extraData params on sendData(_:). You can set preferred structure of extraData before adding it to sendData(_:).

For more details about available attributes and functionality check VGSCollectSDK Reference docs