FraudForce is now Device Risk. Our device-based products, such as Device Risk and Device-Based Authentication (formerly ClearKey), are critical components of our fraud and identity solutions; the new names make it easy to quickly understand our extensive capabilities. We have united these solutions under the TransUnion TruValidate brand. We have taken care not to update anything that might affect your implementations; as a result you'll still see legacy names in some places.

Follow these steps to implement the TruValidate Device Risk SDK for Android.

TransUnion identifies devices through information collected by the Device Risk SDK run on an end-user’s mobile device. The Device Risk SDK inspects the device to generate a blackbox that contains all device information available. This blackbox must then be transmitted to your servers to be used in a risk check.

The Device Risk SDK integrates with native and hybrid apps. Hybrid apps mix native code with content that runs inside a web view.

NOTE Android 12 introduced the BLUETOOTH_CONNECT permission, protected at the dangerous level. Refer to the official Android documentation on how to include it.

NOTE Regarding Android 11 background location changes: The Device Risk SDK neither requires nor requests location when the application is in a background state.

NOTE If the permissions listed are not required by the application, the values collected using those permissions will be ignored. The permissions are not required to obtain a usable blackbox, but they do help obtain some unique device information.

NOTE Android 10 introduced the ACCESS_BACKGROUND_LOCATION permission, protected at the dangerous level as is the case for ACCESS_FINE_LOCATION. Refer to the official Android documentation for when to incorporate this permission.

Version 5.2.1 of the TruValidate Device Risk SDK for Android supports Android 5.0 or higher.

1. Download iovation-android-sdk-5.2.1.zip from here: iovation Mobile SDK for Android. 

2. Unzip iovation-android-sdk-5.2.1.zip.

3. Depending on your IDE, do one of the following:

   • In Maven, deploy the AAR file to your local Maven repository, using maven-deploy. For more information, see Guide to installing 3rd party JARs.

   • If you are using Gradle, add the fraudforce-lib-release-5.2.1.aar file to your application module's libs directory. Then, edit the build.gradle file in order to add the libs directory as a flat-file repository to the buildscript and repository sections. This makes the fraudforce-lib-release-5.2.1.aar file accessible to Gradle.

     buildscript {
         repositories {
             flatDir {
                 dirs 'libs'
             }
         }
     }
     
     repositories {
         flatDir {
             dirs 'libs'
         }
     }
     

     Also in the application module's build.gradle file, make sure that fraudforce-lib-release-5.2.1 is included as a dependency:

     dependencies {
         ...
         implementation(name:'fraudforce-lib-release-5.2.1', ext:'aar')
     }
     

     Alternatively, you can include the dependency without exposing your libs folder as a repository by declaring it in the module's build.gradle file as follows:

     dependencies {
         ...
         implementation files('libs/fraudforce-lib-release-5.2.1.aar')
     }
     

     Save the build.gradle file.

4. If you are not already using Java 8 in your project, please include the following code into your application's 'build.gradle' file.

   android {
       compileOptions {
           sourceCompatibility JavaVersion.VERSION_1_8
           targetCompatibility JavaVersion.VERSION_1_8
       }
   }
   

NOTE If you are using an older version of the Android Gradle Plugin and encounter UnsatisfiedLinkErrors in the course of your testing, you may need to add the following to your ProGuard configuration: -keep public class com.iovation.mobile.android.details.RP { public native java.lang.String a(); public native java.lang.String b(); }

To integrate into native apps:

1. In your Application class, import the FraudForceManager and FraudForceConfiguration objects.

   Java

   import com.iovation.mobile.android.FraudForceConfiguration;
   import com.iovation.mobile.android.FraudForceManager;
   

   Kotlin

   import com.iovation.mobile.android.FraudForceConfiguration
   import com.iovation.mobile.android.FraudForceManager
   

2. Create a configuration object with your subscriber key, and enable or disable network calls to TransUnion servers. Entering the subscriber key is strongly recommended for all integrations, and it is required for network connections.

   NOTE Please review the Network Calls section of this document before enabling network calls.

   IMPORTANT Please contact your TransUnion customer success team representative to receive your subscriber key.

   Java

   FraudForceConfiguration configuration = new FraudForceConfiguration.Builder()
       .subscriberKey([YOUR-SUBSCRIBER-KEY-HERE])
       .enableNetworkCalls(true) // Defaults to false if left out of configuration
       .build();
   

   Kotlin

   val configuration = FraudForceConfiguration.Builder()
           .subscriberKey([YOUR-SUBSCRIBER-KEY-HERE])
           .enableNetworkCalls(true)
           .build()
   

3. Initialize the FraudForceManager class using the generated FraudForceConfiguration object, and the application context.

   Java

   FraudForceManager fraudForceManager = FraudForceManager.INSTANCE;
   fraudForceManager.initialize(configuration, context);
   

   Kotlin

   FraudForceManager.initialize(configuration, applicationContext)
   

4. Call the refresh() method in the same Activity/Fragment/ViewModel where getBlackbox() will be called. The integrating application only needs to call this method on the Fragments where the getBlackbox() method will be called.

   NOTE: This method calls updates the geolocation and network information, if enabled.

   NOTE: As with initialization, pass the application context when refreshing.

   Java

   FraudForceManager.INSTANCE.refresh(context);
   

   Kotlin

   FraudForceManager.refresh(applicationContext)
   

5. To generate the blackbox, call the getBlackbox(Context context) function on an instance of FraudForceManager. This method is a blocking call so it is recommended to call it on a background thread/coroutine.

   Java

   String blackbox = FraudForceManager.INSTANCE.getBlackbox(context);
   

   Kotlin

   val blackbox : String = FraudForceManager.getBlackbox(applicationContext)
   

6. To generate the blackbox using a coroutine, declare the desired scope and call the getBlackbox(Context context) function on an instance of FraudForceManager. You can use the withContext(context: CoroutineContext) suspend function to utilize the blackbox data in another scope.

   Kotlin Coroutines Example

   private val uiScope = CoroutineScope(Dispatchers.IO)
   
   uiScope.launch {
       ...
       val blackbox : String = FraudForceManager.getBlackbox(applicationContext)
       withContext(Dispatchers.Main) {
           ...
           useBlackbox(blackbox)
       }
   }
   

Integrate into hybrid apps by implementing the following workflow for collecting and sending blackboxes:

1. An HTML page loads in a WebView.

2. The user submits a transaction on the HTML page by submitting a form or completing another action. 

3. This calls the inject_bb function, which creates a hidden iframe that calls the iov:https:// URL. The iframe then deletes itself.

4. The shouldOverrideUrlLoading function inside of the WebView object in Java is called. This function detects the iov:https://blackbox/fill#dom_id URL.The dom_id is the ID of the object on the HTML page where the blackbox will be written, such as a hidden form field.

5. The shouldOverrideUrlLoading function runs JavaScript that automatically injects the blackbox into that object.

1. In your Application class, import the FraudForceManager and FraudForceConfiguration objects.

   import com.iovation.mobile.android.FraudForceConfiguration;
   import com.iovation.mobile.android.FraudForceManager;
   

2. Create a configuration object with your subscriber key, and enable or disable network calls to TransUnion servers. Entering the subscriber key is strongly recommended for all integrations, and it is required for network connections.

   NOTE Please review the Network Calls section of this document before enabling network calls.

   FraudForceConfiguration configuration = new FraudForceConfiguration.Builder()
       .subscriberKey([YOUR-SUBSCRIBER-KEY-HERE])
       .enableNetworkCalls(true) // Defaults to false if left out of configuration
       .build();
   

3. Initialize the FraudForceManager class using the generated FraudForceConfiguration object, and the application context.

   FraudForceManager fraudForceManager = FraudForceManager.INSTANCE;
   fraudForceManager.initialize(configuration, context);
   

4. In your WebView Activity's onCreate() function, set your WebView's shouldOverrideUrlLoading() function, as well as the onPageStarted() function.

   wv.setWebViewClient(new WebViewClient() {
       @Override
       public void onPageStarted(WebView view, String url, Bitmap favicon) {
           FraudForceManager.INSTANCE.refresh(getContext());
           super.onPageStarted(view, url, favicon);
       }
   
       @Override
       public boolean shouldOverrideUrlLoading(WebView view, String url) {
           String[] ref = url.split("#");
           if (url.startsWith("iov:https://") && ref.length > 1 && ref[1] != null) {
           String injectedJavascript="javascript:(function() { " +
               "document.getElementById('" + ref[1] + "').value = '"
               + FraudForceManager.INSTANCE.getBlackbox(wv.getContext())
               + "';})()";
               wv.loadUrl(injectedJavascript);
               return true;
           }
           return false;
       }
   });
   

5. On your HTML page, include a javascript function called inject_bb that injects an iframe with a call to the iov:https:// URL.

   function inject_bb(id) {  
   	var iframe = document.createElement('IFRAME');  
   	iframe.setAttribute('src', 'iov:https://blackbox/fill#' + id);  
   	iframe.name="ioOut";  
   	document.documentElement.appendChild(iframe);  
   	iframe.parentNode.removeChild(iframe);  
   	iframe = null;  
   }
   

6. You must inject the blackbox into a DOM object for collection. To do this, call the inject_bb function with the ID of the DOM object, which will automatically call the shouldOverrideUrlLoading() function. For example, set ID to a hidden form field where the blackbox will be stored. When the form containing the field is submitted, the blackbox is returned to your server back-end, and can then be sent to TransUnion to evaluate along with the transaction.

The SDK includes the ability to make a network call to TransUnion TruValidate's service. This enables additional functionality in the Device Risk SDK, including:

• Collect additional network information
• Configuration updates to root detection
• Collect information on potential high-risk applications on the device

By default this functionality is disabled and will need to be enabled in the configuration object. Usage of this feature requires a subscriber key be provided. Please contact your TransUnion client representative to acquire a subscriber key.

1 In Android Studio, select File | Open or click Open Existing Android Studio Project from the quick-start screen.

2. From the directory where you unzipped fraudforce-lib-release-5.2.1.zip or cloned the repo, open the android-studio-sample-app directory.

3. In the project navigation view, open app/src/main/java/com/iovation/mobile/android/sample/MainActivity.java to run the Java sample app. To run the Kotlin sample app, open kotlinApp/src/main/java/com/iovation/mobile/android/sample/MainActivity.kt.

4. Right-click the file editing view and select Run Main Activity.

   • IMPORTANT! If the option to run the module does not appear, select FILE -> PROJECT STRUCTURE and open the Modules panel. From there, set the Module SDK drop-down to your target Android SDK version.

   Alternatively, you can right-click on the build.gradle file, and select Run 'build'.

5. Select either an attached physical device, or an Android virtual device to run the app on. The app should now compile and launch.

6. When the app compiles successfully, you will see a view with a button that allows you to display a blackbox.

• Update target SDK to 33.
• Adjusted collection details.
• Bug fix for collection issue.

• Adjusted collection details.

• Java 8 is now required.
• The SDK has migrated to Kotlin (1.5.30).
  • If your application does not already include the Kotlin standard library (i.e. your application
  • is written entirely in Java), then you must include the kotlin stdlib as a dependency.
• FraudForceManager can be accessed as a Kotlin object or via FraudForceManager.INSTANCE when using Java).
• Targeting Android 12 (API 31).
• Changes to cryptography uses.
• Adjusted collection details.
• Improvements to detail caching.
• Fixed Proguard rules.

• Adjusted root detection.

• Update target and compilation SDK versions to 31.
• Adjusted collection details.
• Compatible with the new bluetooth changes/permissions in Android 12.
• Fixed crashes on devices running below SDK version 24.

• Minimum supported Android version updated, from 16 to 21.
• Update target and compilation SDK versions to 30.
• Bug fixes for NPEs sometimes encountered during asynchronous calls to initialize and/or refresh.

• Several obfuscation-related updates/fixes, including preservation of base package.

• Update target SDK to 29

• Updated compileSdkVersion to 29.

• Behavioral changes for apps targeting API 29.

• Adjusted recognition details.

• Enhanced support for Android 9.0 Pie.

• Further improvements to location data collection process.

• Resolved Google Play alerts regarding encryption methods.

• Support for Android 9.0 Pie.

• Fix for issue related to the Turkish character set.

• Improved location data collection process.

• Improved blackbox data collection performance.

• More efficient network calls to iovation.

• New API objects, FraudForceConfiguration and FraudForceManager. Prior API objects have been removed.

• Compatibility with Android 8.0.

• Introduced network calls back to iovation service for additional functionality.

• Dropped support for Android API level 8 through API level 15.

• Compatibility with Android 7.0.

• Improved error handling.

• Improved permission checking.

• Fixes crash with invalid locale.

• Fixes error with Bluetooth permission.

• More robust error handling.

• Compatibility with Android 6.0 permission system.

• Enhanced recognition with additional details added in Android 6.0.

• Enhanced geolocation services with mock location detection capabilities.

• Enhanced carrier detection and home carrier detection.

• Compatibility with older versions of Android build-tools.

• Enhanced recognition with the collection of additional details.

• Fix bug with permissions that would crash applications.

• New API method, getBlackbox, handles low-priority asynchronous collection of device data. The ioBegin method remains for backwards compatibility.

• Expanded the android-studio-sample-app with a WebView integration example.

• Added WebView integration instructions.