Last Updated: 20 September 2023 | Change Log

Android Device Data

When combined with order and transaction details, device data (IP Address, Device Id, Geolocation Information, etc.) can be a strong indicator for fraud or used via GeoIP lookup to create manual rules based on location. Utilizing device data with Access Exemptions is a two-step process. Step one is to collect the device data. Step two is to submit an assessment that will use the device data for evaluation. Described below is step one for Android.

ThreatMetrix Android SDK

The ThreatMetrix Android SDK provides mobile application developers with Android specific libraries. It leverages the ThreatMetrix Platform to detect fraud and security vulnerabilities originating from mobile devices in real-time.

The instructions are applicable to ThreatMetrix SDK version V6-2.

Overview of implementation

1. Include the ThreatMetrix SDK in the application.

2. Call the init() method to initialize the SDK.

3. Call the profile() method to begin device profiling. ThreatMetrix SDK will transmit the collected attributes and a unique sessionId to the ThreatMetrix Platform.

4. Apply the sessionId in the Exemption assessment request so it forms part of the risk assessment.

How to get the SDK

Modules to include

• TMXProfiling: This module is responsible for performing profiling exclusively. It does not transfer anything over the network, so the module does not send or receive data on its own. You must pair this module with TMXProfilingConnections module or a custom profiling connections module to send and receive data to and from the backend for successful profiling.

• TMXProfilingConnections: It is the default networking module provided by ThreatMetrix. This module only transfers data over the network without changing the data.

Include AAR files of TMXProfiling and TMXProfilingConnections modules into your app/libs folder. Then add these dependencies into your app-level build.gradle file.

implementation files('libs/TMXProfiling-6.2-107.aar')
implementation files('libs/TMXProfilingConnections-6.2-107.aar')

Permissions

Mandatory permissions

You must include the following permission in the manifest file of your application.

<uses-permission android:name="android.permission.INTERNET" \/>

Optional permissions

<uses-permission android:name="android.permission.READ_PHONE_STATE"/\>

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/\>  

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/\>

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/\>

<uses-permission android:name="android.permission.CHANGE_WIFI_STATE"/\>

Using ThreatMetrix SDK

Profiling

Profiling is a mechanism by which ThreatMetrix collects information about the device that is accessing a customer's online service, either via a website or a native application.

Identify the screen in your native application that provides the optimal opportunity for profiling. The majority of profiling is completed in a short span and may take up to 5 seconds to collect the full set of profiling attributes.

Common screens where we can initiate profiling are Account creation screen, Payments screen and Login screen.

Details required

To create a config instance, pass the below details to the init() method.

Get instance and initialize

The ThreatMetrix SDK is initialized asynchronously at startup by calling the init() function which is configured with the Config object.

You must at least specify Context, Org ID and the FP server/Profiling domain. The getInstance() method of TMXProfiling class is used to return a singleton instance of the ThreatMetrix Object. The instance is only required to be initialized once.

Here’s an example of how you can get instance and initialize for profiling.

class MainActivity : AppCompatActivity() {

override fun onCreate(savedInstanceState: Bundle?) {
  super.onCreate(savedInstanceState)

  val username: EditText = findViewById(R.id.editTextUsername)
  val password: EditText = findViewById(R.id.editTextPassword)

 /* Creating a config instance to be passed to the init() method. This instance must  
  include orgId and application context otherwise the init()method will fail. */

  var config = TMXConfig()
 	//(REQUIRED) Organization ID
                   .setOrgId(ORG_ID)
	// (REQUIRED) FPserver/Profiling domain
    		    .setFPServer(FP_SERVER)
	// (REQUIRED) Application Context
    		   .setContext(applicationContext)
  // (Optional) Register for location services
	// Requires ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION permission		            
          .setRegisterForLocationServices(true)


  /*Getting instance of ThreatMatrix object by passing config object to it*/
  TMXProfiling.getInstance().init(config)
  /*Once the valid instance is created for further calls, fire a profile
   request*/
  doProfile()
 }
}

Start profiling

Create a method to start profiling and send some additional attributes along with profiling information. Here’s a code sample of a method that starts profiling.

fun doProfile(){

  /*(OPTIONAL) Assign some custom attributes to be included along with the  
   profiling Information*/
    val list = listOf("attribute 1", "attribute 2")

    var options: TMXProfilingOptions = TMXProfilingOptions()
        		.setCustomAttributes(list)
   //Start the profiling request
   /*The instance of TMXEndNotifier must be passed to the profile() method, the   
     CompletionNotifier is an implementation of TMXEndNotifier which is explained
     in obtaining profiling result section*/
     TMXProfiling.getInstance()
                 .profile(options, CompletionNotifier())

 }

Obtaining profiling result and sessionID

1. Create a class which implements the TMXEndNotifier interface.
2. Implement the complete() method.
3. Pass an instance of that class as part of the call to the profile() method as shown above.

The complete() method of that instance will be called with the result of the profiling once profiling has finished.

Use result.status/ result.getStatus() method to know the status of profiling. This method returns string “Okay” on successful profiling.

Here's an example of the implementation.

/* TMXEndNotifier implementation called when profiling is completed */

class CompletionNotifier: TMXEndNotifier {

  /*This method gets called when the profiling has finished. Be careful here    
    because we are not going to be called on the UI thread, and if we want to
    update UI elements we can only do it from the UI thread.*/

     override fun complete(result: TMXProfilingHandle.Result) {

	 //Get the session id to use in API call (AKA session query)
	 val sessionID = result.sessionID
         val status = result.status

    }
}

Linking the device data with the assessment

When sending the Exemption assessment request, include the sessionId in deviceData.collectionReference.

Next steps

Assessment