Behavioral Data Collector - Android Project Integration

This page describes how to integrate Vesta’s Android SDK into your Android project. During the integration, you will perform the following actions:

Import the Library - Add Vesta’s libraries to your project.
Initialize the Data Collector - Call the data collector start method to begin tracking your user’s behavior.
Provide Location Data - If you choose to track your user’s location, send Vesta the latitude and longitude from the device.
Implement Field Tagging - Add tags to the UI elements of your application so that Vesta can watch them for indications of fraud.

Visit the Downloads page to download the most up to date version of the Behavioral Data Collector files for your platform.

Import the Library

Import the library into your Android Studio project in order the begin using the data collector methods. The steps below describe how to add the library files to your project:

Select the Project Files view from the drop-down list in Android Studio, as shown below:
Expand the application module directory, which is commonly called “app”. Then, locate the “libs” directory. If the “libs” directory does not exist, create it. The image below shows the file hierarchy:
In your file explorer, search for the “android-datacollector-sdk.aar” file, and copy it. The image below shows how to copy the file:
Paste the “android-datacollector-sdk.aar” file into the “libs” directory in your Android project, as shown in the image below:
Locate your “app/build.gradle” file and paste the code below into it:
```
implementation fileTree(dir: "libs", include: ["*.aar"])
```

Declare the following dependencies in your main app, which is commonly called “:app” in your Android Studio project:

// Dependencies required by the Vesta Data Collector SDK
implementation "androidx.lifecycle:lifecycle-livedata-ktx:2.3.0-alpha03"
implementation "com.squareup.okhttp3:logging-interceptor:4.7.2"
implementation "com.squareup.okhttp3:okhttp:4.7.2"
implementation 'com.squareup.retrofit2:converter-gson:2.7.2'
implementation 'com.squareup.retrofit2:retrofit:2.7.2'
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.3.7"
//  Adding the Kotlin standard library as a dependency
//  does not add Kotlin support to your project nor does it
//  pose any restrictions to the language you are using.
//  This is a regular library dependency.
implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk7:1.3.72"
   

If any of the dependencies listed above are already included in your project, do not include them a second time.

NOTE: These dependencies must be declared manually because the Data Collector SDK is not currently distributed as an artifact repository. The dependencies primarily support backwards compatibility. Contact Vesta if the dependencies cause problems or conflicts.

Now that the SDK is included in your project, you must set it up to initialize when your app launches.

Initialize the Data Collector

Initialize the Data Collector at the beginning of your app flow so that it can report the data that it tracks to Vesta.

To initialize the Data Collector, call the VestaDataCollector.start() method as soon as your app launches and pass it the following parameters:

Parameter Name	Description	Type
Application	An instance of the current application. Call the `getApplication()` method from your current activity to obtain the instance.	android.app.Application
WebSessionID	The WebSessionID used for vSafe apps. Send a POST request to the `GetSessionTags` endpoint to obtain a WebSessionID.	String
LoginID	The user’s LoginID.	String

The code below provides and example of how to initialize the data collector using the VestaDataCollector.start() method:

protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);
    
    // Initialize the VestaDataCollector SDK during your main Activity's creation
    VestaDataCollector.start(getApplication(), "the WebSessionId from the GetSessionTags API response", "LoginID of the user");
}

Provide Location Data

If you choose to track your customer’s location, use the VestaDataCollector.sendLocationData() method to send the latitude and longitude values from your user’s device to Vesta. Vesta uses the location data to augment our fraud detection and risk analysis. Tracking location data is optional. If you choose not to track location, proceed to the Implement Field Tagging section.

The table below defines the parameters that you must pass to the VestaDataCollector.sendLocationData() method:

Parameter Name	Description	Type
latitude	The latitude value obtained from your customer’s device.	Double
longitude	The longitude value obtained from your customer’s device.	Double

The code below provides and example of how to call the sendLocationData() method:

VestaDataCollector.sendLocationData(37.4219999, -122.0862515);

Implement Field Tagging

Field tagging identifies the UI elements that Vesta will watch to track your customer’s behavior. See the Data Collector Integrations page for additional details about field tagging. The information below describes how to implement field tagging in your Android app:

When defining UI elements in your application’s layout XML files, use Vesta’s TrackingEditText class instead of the standard EditText class.
Add the property app:tracking_tag to the TrackingEditText object definition and assign one of the Vesta-defined values for field tagging.

The code below shows an example of the TrackingEditText object with the app:tracking_tag attribute value set to LoginID:

<?xml version="1.0" encoding="utf-8"?>
<androidx.constraintlayout.widget.ConstraintLayout 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">

    <com.vesta.sdk.widget.TrackingEditText
        android:layout_width="@dimen/match_constraint"
        android:layout_height="wrap_content"
        app:layout_constraintEnd_toEndOf="parent"
        app:layout_constraintStart_toStartOf="parent"
        app:layout_constraintTop_toTopOf="parent"
        app:tracking_tag="LoginID" />

</androidx.constraintlayout.widget.ConstraintLayout>

It is possible to add TrackingEditText objects to your UI programmatically by searching for the appropriate field and assigning the correct values to the object’s attributes. The code below provides an example of using Constrain Layout as the root container to implement field tagging programmatically:

@Override
protected void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    setContentView(R.layout.activity_main);

    // Initialize the VestaDataCollector SDK
    VestaDataCollector.init(getBaseContext(), getApplication(), "login id of the user");

    // Get a reference to an existing TrackingEditText in the XML layout file.
    // The new TrackingEditText (generated below) will be placed under this TrackingEditText
    TrackingEditText trackingEditTextUserName = findViewById(R.id.vestaTrackingEditTextUsername);

    // Obtain the parent, root or container layout where the new
    // EditText/TrackingEditText will be added programmatically
    ConstraintLayout constraintLayout = findViewById(R.id.rootConstraintLayout);

    // Create a LayoutParams object, this define the size of the TrackingEditText within it's parent/container
    // 0 means, this view will respect the constraints passed via ConstraintSet below
    ConstraintLayout.LayoutParams layoutParams = new ConstraintLayout.LayoutParams(0, LinearLayout.LayoutParams.WRAP_CONTENT);
    // Add a margin
    layoutParams.topMargin = (int) getResources().getDimension(R.dimen.common_margin);

    // Create the actual TrackingEditText
    TrackingEditText trackingEditTextPassword = new TrackingEditText(this, TrackingTag.Password);

    // Add the properties to the TrackingEditText
    trackingEditTextPassword.setLayoutParams(layoutParams);
    trackingEditTextPassword.setId(ViewCompat.generateViewId());
    trackingEditTextPassword.setHint(R.string.hint_password);
    trackingEditTextPassword.setInputType(InputType.TYPE_TEXT_VARIATION_PASSWORD);
    trackingEditTextPassword.setTransformationMethod(PasswordTransformationMethod.getInstance());

    // add the newly created TrackingEditText to the container/layout
    constraintLayout.addView(trackingEditTextPassword, 0);

    // Create a ConstraintSet instance, this object will help us to arrange child elements in the ConstraintLayout
    ConstraintSet constraintSet = new ConstraintSet();
    constraintSet.clone(constraintLayout);
    constraintSet.connect(trackingEditTextPassword.getId(), ConstraintSet.START, ConstraintSet.PARENT_ID, ConstraintSet.START);
    constraintSet.connect(trackingEditTextPassword.getId(), ConstraintSet.END, ConstraintSet.PARENT_ID, ConstraintSet.END);
    constraintSet.connect(trackingEditTextPassword.getId(), ConstraintSet.TOP, trackingEditTextUserName.getId(), ConstraintSet.BOTTOM);

    // Once we have all the constraints/rules via ConstraintSet, they're applied to the layout
    constraintSet.applyTo(constraintLayout);
}