Observing States and Submitting Data

Start session

VGS Collect SDK requires vault id and environment. To create a VGSCollect for your application, you need to get your <VAULT_ID> and specify <environment>. For example:

val vgsForm = VGSCollect(this, "<VAULT_ID>", Environment.<SANDBOX>);

VGSCollect vgsForm = VGSCollect(this, "<VAULT_ID>", Environment.<SANDBOX>);

Multiple Data Regions

Please use the following configuration to set up a specific data region if needed.

val id = "<VAULT_ID>"
val environment = "sandbox-eu-1"
val vgsForm = VGSCollect(this, id, environment);

String id = "<VAULT_ID>"
String environment = "sandbox-eu-1"
VGSCollect vgsForm = VGSCollect(this, id, environment);

Add a Custom Hostname

When integrated with VGS, by default, the traffic is passed via the VGS proxy, which has tntxxxxx.sandbox.verygoodproxy.com format, where tntxxxxx is your Vault identifier. Collect SDK allows you to use your custom hostname and make requests to a non-VGS domain name or localhost (on your local machine). Before adding a new Hostname, you should create a CNAME record for your existing domain in your DNS provider’s account that should point to <VAULT_ID>.<ENVIRONMENT>.verygoodproxy.com.

** Learn more about Custom Hostnames**.

To specify your hostname, you have to initialize the Collect SDK using Builder class:

val vgsForm: VGSCollect = VGSCollect.Builder(this, "<VAULT_ID>")
    .setEnvironment(Environment.<SANDBOX>)
    .setHostname("www.customdomain.com")
    .create()

VGSCollect vgsForm = new VGSCollect.Builder(context, "<VAULT_ID>")
    .setEnvironment(Environment.<SANDBOX>)
    .setHostname("www.customdomain.com")
    .create();

• When the hostname is not valid or not registered in VGS system, it will be ignored by SDK and all the traffic will be passed via VGS proxy directly. • Only https scheme is supported.\

Data subscribing

It allows VGSCollect to bind to the input field, retrieve user data, send requests, receive responses, and deliver it to the user.

val cardNumberField = findViewById<VGSCardNumberEditText>(R.id.cardNumberField)
vgsForm.bindView(cardNumberField)

VGSCardNumberEditText cardNumberField = findViewById(R.id.cardNumberField);
vgsForm.bindView(cardNumberField);

Tracking field states

For more information about tracking states, read the developer guide.

A user can retrieve different states from a field by:

retrieving the general state with getAllStates method in the VGSCollect class.
observing the general state with OnFieldStateChangeListener listener in the VGSCollect class.
observing the general state with OnFieldStateChangeListener listener in a single secure field.
tracking focus by default View.OnFocusChangeListener listener for the single secure field.
tracking action on the editor with InputFieldView.OnEditorActionListener listener for the single secure field.

File Provider

The Collect SDK allows you to upload files to the VGS Server. VGSFileProvider may help you to manage files.

** Check guide: How to manage files.**

val fileProvider: VGSFileProvider = vgsForm.getFileProvider()

VGSFileProvider fileProvider = vgsForm.getFileProvider();

Custom data

SDK provides two options to define custom user data in request: static and dynamic. Static data could be set for all requests during session. The custom data gets automatically added by VGSCollect for every request using setCustomHeaders and setCustomData methods.

In contrast, dynamic data must be set for each request.

** Check guide: How to manage the Custom Data.**

val data = HashMap<String, Any>()
data["nonSDKValue"] = "value"\n
vgsForm.setCustomData(data)

val customData = HashMap<String, Any>()
customData.put("nonSDKValue", "value")
val request: VGSRequest = VGSRequest.VGSRequestBuilder()
          .setMethod(HTTPMethod.POST)
          .setPath(path)
          .setCustomData(customData)
          .build()

Getting a Result from an external Activity

You can also start another activity and receive a result back. To receive a result, call startActivityForResult(). For example, your app can start a camera app and receive the credit card number as a result.

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    vgsForm.onActivityResult(requestCode, resultCode, data)
}

@Override
protected void onActivityResult( int requestCode, int resultCode, Intent data ) {
    super.onActivityResult(requestCode, resultCode, data);
    vgsForm.onActivityResult(requestCode, resultCode, data);
}

Submit information

Call asyncSubmit to execute and send data on VGS Server.

Collect SDK offers several ways to submit user data to Vault Proxy Serer. Here is a list of methods that can help:

val request: VGSRequest = VGSRequest.VGSRequestBuilder()
    .setMethod(HTTPMethod.POST)
    .setPath("/path")
    .build()
vgsForm.asyncSubmit(request)

VGSRequest request = new VGSRequest.VGSRequestBuilder()
    .setMethod(HTTPMethod.POST)
    .setPath("/path")
    .build();
vgsForm.asyncSubmit(request);

Call submit to execute and send data on the VGS Server if you want to handle multithreading by yourself.

If there are two fieldNames with equal names - the earlier will be overwritten.

Nested JSON arrays

When you need to produce a JSON array, add [element_index] to the end of fieldName level of nesting fieldName[index]. Only one JSON key and array element_index is supported per nesting level. Multi-dimensional arrays are not supported.

// Define field names
val userId = "userId"
val cardNumberFieldKey = "card_data.card_number"
val cardCVCFieldKey = "card_data.cvc"
val accountId = "card_data.ids[0]"

// Select policy type
val request = VGSRequest.VGSRequestBuilder()
            .setFieldNameMappingPolicy(VGSCollectFieldNameMappingPolicy.NESTED_JSON_WITH_ARRAYS_OVERWRITE)
            .build()

// Example of transformed JSON structure
{
   "userId": "id12345",
   “card_data: {
      “card_number”:  411111111111111”,
      “cvc”: “123”,
      “ids“: [ 7 ]
   }”
}

In case additional data contains arrays on the same nesting level with VGS Collect JSON produced by fields you need to specify how to merge arrays. To configure behaviour of the merging a data set VGSCollectFieldNameMappingPolicy to setFieldNameMappingPolicy in VGSRequest.Builder

Available fieldName mapping policies:

VGSCollectFieldNameMappingPolicy.NESTED_JSON - map fieldName to JSON. Arrays are not supported. The default policy type.
VGSCollectFieldNameMappingPolicy.FLAT_JSON - map fieldName to JSON. Flat JSON format uses fieldname as a single key and does not produce any nested JSON or array.
VGSCollectFieldNameMappingPolicy.NESTED_JSON_WITH_ARRAYS_OVERWRITE - map fieldName to JSON with arrays if index is specified. Completely overwrite the extra data array with the collected array data.
VGSCollectFieldNameMappingPolicy.NESTED_JSON_WITH_ARRAYS_MERGE - map fieldName to JSON with arrays if index is specified. Also, merge the extra data array with the collected array data at the same nested level if possible.

val request: VGSRequest = VGSRequest.VGSRequestBuilder()
  .setFieldNameMappingPolicy(VGSCollectFieldNameMappingPolicy.NESTED_JSON)
  .build()
vgsForm.asyncSubmit(request)

VGSRequest request = new VGSRequest.VGSRequestBuilder()
  .setFieldNameMappingPolicy(VGSCollectFieldNameMappingPolicy.NESTED_JSON)
  .build();
vgsForm.asyncSubmit(request);

For more information about custom JSON structures check our examples.

PreviousIntegration with Vault API NextCard Scanner

Last updated 7 days ago