Menu

Device Data Collection

API v1
Coming soon

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 FraudSight is a two-step process. Step one is to collect the device data. Step two is to submit anassessmentthat 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 FraudSight assessment request so it forms part of the risk assessment.

How to get the SDK

Note: This will be released shortly, this documentation is for preview only

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.

Copied!
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.

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

Optional permissions

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.

PlaceholderDescription
ORG_ID
  • For testing use: afevfjm6
  • For live use: dzppsd1h
FP_SERVER
  • For testing use: ddc-test.worldpay.com
  • For live use: ddc.worldpay.com

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.

Copied!
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()
 }
}
public class LoginActivity extends Activity
{
    private EditText    username;
    private EditText    password;

    @Override
    protected void onCreate(Bundle savedInstanceState)
    {
        username   = findViewById(R.id.editTextUsername);
        password  = 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. */
    TMXConfig config = new TMXConfig()
       //(REQUIRED) Organization ID
            .setOrgId(ORG_ID)
       // (REQUIRED) FPserver/Profiling domain
            .setFPServer(FP_SERVER)
       // (REQUIRED) Application Context
            .setContext(getApplicationContext())
       // (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 , call your code which starts profiling */
        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.

Copied!
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())

 }
void doProfile()
{
  /*(OPTIONAL) Assign some custom attributes to be included along with the  
   profiling Information*/
   List<String> list = Arrays.asList("attribute 1", "attribute 2");

    TMXProfilingOptions options = new 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,new 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.

Copied!
/* 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

    }
}
/* TMXEndNotifier implementation called when profiling is completed */

private class CompletionNotifier implements TMXEndNotifier
{

    private String sessionID;

  /*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
    public void complete(TMXProfilingHandle.Result result)
    {
    //Get the session id to use in API call (AKA session query)
        sessionID = result.getSessionID();
        result = result.getStatus();

    }
}

Linking the device data with the assessment

When sending theFraudSight assessmentrequest, include the sessionId in deviceData.collectionReference.

Next steps


Assessment