How to Integrate

Before you start, you can also check VGS Show SDK GitHub Page.

Make sure that you check our best practices to ensure secure configurations.

Quickstart from Dashboard

You should have your organization registered at the VGS Dashboard. Sandbox vault will be pre-created for you. You should use your vault id to start reveal data. Follow integration guide below.

Integrate VGS Show SDK into Your Android Project

To use the SDK in your project you just need to add the following line of dependency in your module build.gradle file and then rebuild project.

Check out our latest releases.

dependencies {
    //...
    implementation 'com.verygoodsecurity:vgsshow:<latest-version>'
    //...
}

Include additional configurations

In case you have minifyEnabled enabled don't forget to add next line to your project R8 configuration.

//...
-keep public class com.google.android.material**  { *; }
//...

Configure Your App

Specifying app manifest

Declaration of FileProvider in app manifest required only for VGS Show SDK v1.2.0 - v1.3.2.

Add a <provider> element to your app manifest. Set the android:name attribute to the FileProvider you created. Set the unique android:authorities attribute to a URI authority. Set the element android:resource attribute to @xml/file_paths (without specifying the .xml extension).

<manifest>
    ...
    <application>
        ...
        <provider
             android:name="androidx.core.content.FileProvider"
             android:authorities="{applicationID}.fileprovider"
             android:exported="false"
             android:grantUriPermissions="true"
             tools:replace="android:authorities">\n
                 <meta-data
                     android:name="android.support.FILE_PROVIDER_PATHS"
                     android:resource="@xml/file_paths"
                     tools:replace="android:resource"
                     />
        </provider>
        ...
    </application>
</manifest>

Define <paths> in file_paths.xml file.

<?xml version="1.0" encoding="utf-8"?>
<paths>
    <files-path
        name="my_docs"
        path="docs/" />
</paths>

Please follow the link for more information.

Initialize SDK

To initialize VGSShow, you have to set your vault id and Environment type.

import android.os.Bundle\n
import androidx.appcompat.app.AppCompatActivity
import com.verygoodsecurity.demoshow.R
import com.verygoodsecurity.vgsshow.VGSShow
import com.verygoodsecurity.vgsshow.core.VGSEnvironment
class MainActivity : AppCompatActivity() {
    private lateinit var vgsShow: VGSShow
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.main_activity)
        vgsShow = VGSShow(this, "<VAULT_ID>", VGSEnvironment.Sandbox())
    }
    override fun onDestroy() {
        super.onDestroy()
    }
}

import android.os.Bundle;\n
import androidx.annotation.Nullable;
import androidx.appcompat.app.AppCompatActivity;
import com.verygoodsecurity.demoshow.R;
import com.verygoodsecurity.vgsshow.VGSShow;
import com.verygoodsecurity.vgsshow.core.VGSEnvironment;
public class MainActivity extends AppCompatActivity {
    private VGSShow vgsShow;
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main_activity);
        vgsShow = new VGSShow(this, "<VAULT_ID>", new VGSEnvironment.Sandbox());
    }
    @Override
    protected void onDestroy() {
        super.onDestroy();
    }
}

Configuring UI Elements

Add the VGS secure field to R.layout.main_activity layout file:

You must set up contentPath to the VGSTextView in other way field will be ignored by VGSShow.

<?xml version="1.0" encoding="utf-8"?>
<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    android:orientation="vertical"
    android:padding="16dp">

    <com.verygoodsecurity.vgsshow.widget.VGSTextView
        android:id="@+id/infoField"
        android:layout_width="match_parent"
        android:layout_height="wrap_content"
        app:contentPath="<CONTENT_PATH>"
        app:gravity="center"
        app:textColor="@android:color/black"
        app:textStyle="bold" />

    <Button
        android:id="@+id/revealButton"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:layout_marginTop="16dp"
        android:text="Reveal" />
</LinearLayout>

Revealing Sensitive Data on Android

Use subscribe(VGSView) to attach a view to VGSShow.

If you use kotlin please check if you added apply plugin: 'kotlin-android-extensions' in your build gradle, or use findViewById(R.id.infoField) otherwise.

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.verygoodsecurity.demoshow.R
import com.verygoodsecurity.vgsshow.VGSShow
import com.verygoodsecurity.vgsshow.core.VGSEnvironment
class MainActivity : AppCompatActivity() {
    private lateinit var vgsShow: VGSShow
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.main_activity)
        vgsShow = VGSShow(this, "<VAULT_ID>", VGSEnvironment.Sandbox())
        vgsShow.subscribe(infoField)
    }
    override fun onDestroy() {
        super.onDestroy()
    }
}

import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.appcompat.app.AppCompatActivity;
import com.verygoodsecurity.demoshow.R;
import com.verygoodsecurity.vgsshow.VGSShow;
import com.verygoodsecurity.vgsshow.core.VGSEnvironment;
public class MainActivity extends AppCompatActivity {
    private VGSShow vgsShow;
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main_activity);
        vgsShow = new VGSShow(this, "<VAULT_ID>", new VGSEnvironment.Sandbox());
        vgsShow.subscribe(findViewById(R.id.infoField));
    }
    @Override
    protected void onDestroy() {
        super.onDestroy();
    }
}

Reveal data

Create a request payload with fieldNames and related aliases.

private fun createRequestPayload(): JSONObject {
    return JSONObject(mapOf("<CONTENT_PATH>" to "<REVEAL_ALIAS>"))
}

private JSONObject createRequestPayload() {
    Map<String, String> data = new HashMap<>();
    data.put("<CONTENT_PATH>" to "<REVEAL_ALIAS>");
    return new JSONObject(data);
}

Call requestAsync to execute and send data on the VGS Server on a background thread, and call request to execute the request on the main thread.

Executing network request on main thread will cause android.os.NetworkOnMainThreadExceptionprivate fun createRequestPayload(): JSONObject { return JSONObject(mapOf("<CONTENT_PATH>" to "<REVEAL_ALIAS>"))

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.verygoodsecurity.demoshow.R
import com.verygoodsecurity.vgsshow.VGSShow
import com.verygoodsecurity.vgsshow.core.VGSEnvironment
import com.verygoodsecurity.vgsshow.core.network.client.VGSHttpMethod
import com.verygoodsecurity.vgsshow.core.network.model.VGSResponse
import kotlinx.android.synthetic.main.main_activity.*
import org.json.JSONObject
class MainActivity : AppCompatActivity() {
    private lateinit var vgsShow: VGSShow
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.main_activity)
        vgsShow = VGSShow(this, "<VAULT_ID>", VGSEnvironment.Sandbox())
        vgsShow.subscribe(infoField)
        vgsShow.requestAsync("/post", VGSHttpMethod.POST, createRequestPayload())
    }
    override fun onDestroy() {
        super.onDestroy()
    }
    private fun createRequestPayload(): JSONObject {
        return JSONObject(mapOf("<CONTENT_PATH>" to "<REVEAL_ALIAS>"))
    }
}

import android.os.Bundle;\n
import androidx.annotation.Nullable;
import androidx.appcompat.app.AppCompatActivity;\n
import com.verygoodsecurity.demoshow.R;
import com.verygoodsecurity.vgsshow.VGSShow;
import com.verygoodsecurity.vgsshow.core.VGSEnvironment;
import com.verygoodsecurity.vgsshow.core.network.client.VGSHttpMethod;\n
import org.jetbrains.annotations.NotNull;
import org.json.JSONObject;
import java.util.HashMap;
import java.util.Map;
public class MainActivity extends AppCompatActivity {\n
    private VGSShow vgsShow;
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main_activity);
        vgsShow = new VGSShow(this, "<VAULT_ID>", new VGSEnvironment.Sandbox());
        vgsShow.subscribe(findViewById(R.id.infoField));
        vgsShow.requestAsync("/post", VGSHttpMethod.POST, createRequestPayload());
    }
    @Override
    protected void onDestroy() {
        super.onDestroy();
    }
    private JSONObject createRequestPayload() {
        Map<String, String> data = new HashMap<>();
        data.put("<CONTENT_PATH>" to "<REVEAL_ALIAS>");
        return new JSONObject(data);
    }
}

Handling Responses

To receive the response status, you need to implement VGSOnResponseListener:

import android.os.Bundle
import androidx.appcompat.app.AppCompatActivity
import com.verygoodsecurity.demoshow.R
import com.verygoodsecurity.vgsshow.VGSShow
import com.verygoodsecurity.vgsshow.core.VGSEnvironment
import com.verygoodsecurity.vgsshow.core.listener.VgsShowResponseListener
import com.verygoodsecurity.vgsshow.core.network.client.VGSHttpMethod
import com.verygoodsecurity.vgsshow.core.network.model.VGSResponse
import kotlinx.android.synthetic.main.main_activity.*
import org.json.JSONObject\n
class MainActivity : AppCompatActivity() {\n
    private lateinit var vgsShow: VGSShow\n
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContentView(R.layout.main_activity)\n
        vgsShow = VGSShow(this, "<VAULT_ID>", VGSEnvironment.Sandbox())
        vgsShow.subscribe(infoField)\n
        vgsShow.addOnResponseListener(object : VGSOnResponseListener {\n
            override fun onResponse(response: VGSResponse) {
                when (response) {
                    is VGSResponse.Success -> {
                        val successCode = response.code
                    }
                    is VGSResponse.Error -> {
                        val errorCode = response.code
                        val message = response.message
                    }
                }
            }
        })
        vgsShow.requestAsync("/post", VGSHttpMethod.POST, createRequestPayload())
    }\n
    override fun onDestroy() {
        super.onDestroy()
    }\n
    private fun createRequestPayload(): JSONObject {
        return JSONObject(mapOf("<CONTENT_PATH>" to "<REVEAL_ALIAS>"))
    }
}

import android.os.Bundle;
import androidx.annotation.Nullable;
import androidx.appcompat.app.AppCompatActivity;
import com.verygoodsecurity.demoshow.R;
import com.verygoodsecurity.vgsshow.VGSShow;
import com.verygoodsecurity.vgsshow.core.VGSEnvironment;
import com.verygoodsecurity.vgsshow.core.listener.VgsShowResponseListener;
import com.verygoodsecurity.vgsshow.core.network.client.VGSHttpMethod;
import com.verygoodsecurity.vgsshow.core.network.model.VGSResponse;
import org.jetbrains.annotations.NotNull;
import org.json.JSONObject;
import java.util.HashMap;
import java.util.Map;\n
public class MainActivity extends AppCompatActivity {\n
    private VGSShow vgsShow;\n
    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main_activity);\n
        vgsShow = new VGSShow(this, "<VAULT_ID>", new VGSEnvironment.Sandbox());
        vgsShow.subscribe(findViewById(R.id.infoField));
        vgsShow.addOnResponseListener(new VGSOnResponseListener() {\n
            @Override
            public void onResponse(@NotNull VGSResponse response) {
                if(response instanceof VGSResponse.Success) {
                    int successCode = ((VGSResponse.Success)response).getCode();
                } else {
                    int errorCode = ((VGSResponse.Error)response).getCode();
                    String message = ((VGSResponse.Error)response).getMessage();
                }
            }
          });
        vgsShow.requestAsync("/post", VGSHttpMethod.POST, createRequestPayload());
    }\n
    @Override
    protected void onDestroy() {
        super.onDestroy();
    }\n
    private JSONObject createRequestPayload() {
        Map<String, String> data = new HashMap<>();
        data.put("<CONTENT_PATH>" to "<REVEAL_ALIAS>");
        return new JSONObject(data);
    }
}