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.
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 standardEditText
class. - Add the property
app:tracking_tag
to theTrackingEditText
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);
}