Title: TransUnion TruValidate Device Risk SDK for iOS

Device Risk SDK for iOS

What is TruValidate Device Risk?

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.

--

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

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

Integration Files and Requirements

File	FraudForce.xcframework
Version	5.2.0
Required OS Version	iOS 11.0 and higher
Supported Devices	iPhone 5S & up, iPod Touch 6th Gen & up, iPad Air & up
Required Frameworks	CoreTelephony, Security, SystemConfiguration
Optional Frameworks	AdSupport, CoreLocation

New XCFramework Installation

1. Download and unzip the SDK from Github. The XCFramework version of the SDK is attached to the current release as FraudForce.xcframework.zip.

2. Bring FraudForce.xcframework into your project repository.

3. Drag and drop (or select the "+" button) to add the FraudForce.xcframework into the "Frameworks, Libraries, and Embedded Content" section of the "General" pane of the Xcode target editor. .

   • This should also result in FraudForce.xcframework being added to appropriate sections of the "Build Phases" pane ("Link Binary With Libraries" and "Embed Frameworks").

4. Optionally add these frameworks (i.e. "Linked Frameworks and Libraries") if your app makes use of them (and Auto Linking is off): * AdSupport.framework — If your app displays ads. Do not include if your app does not use the ad framework, because the App Store will reject apps that include the framework but don't use it or does not ask for permission from the user. * CoreLocation.framework — If your app uses location monitoring. Do not include this framework unless your application requests geolocation permission from the user.

5. If your app has enabled the "Keychain Sharing" capability:

   • Add "com.iovation.stm" to its list of Keychain Groups
   • Add the key AppIdentifierPrefix with the string value $(AppIdentifierPrefix) to your app's Info.plist.

6. For Xcode 10 (and above), allow Device Risk to collect wireless network information: * Configure your app to include the "Access WiFi Information" capability. * Turning the capability on for your application target in Xcode 10 (and above) will update the app's entitlements file and provisioning profile.

   • This entitlement is not required for (and breaks automatic code signing of) apps built by earlier versions of Xcode.

Upgrade from Universal to XCFramework Installation

1. Download and unzip the XCFramework from Github

2. In the "Frameworks, Libraries, and Embedded Content" section of the "General" pane of the Xcode target editor, remove FraudForce.framework.

3. Bring FraudForce.xcframework into your project repository.

4. Drag and drop (or select the "+" button) to add the FraudForce.xcframework into the "Frameworks, Libraries, and Embedded Content" section of the "General" pane of the Xcode target editor.

5. In the "Build Phases" pane of the Xcode target editor, remove the formerly required Run Script phases related to the Universal version of the framework (which were named "Slim Frameworks For Build" and "Clean For Next Build" in prior documentation).

6. The XCFramework now handles the architectures changes for Simulator and Devices.

Submission Preparation

XCFramework Notice

The utility of .bcsymbolmap files continues to hold true for XCFramework packaged dynamic libraries. The FraudForce.xcframework.zip archive includes the required .bcsymbolmap file for the ios-arm64 platform. The archive script provided in the SDK distribution has not yet been updated to support XCFramework based integrations, but the workload it accomplishes for Universal based integrations is a valid template for users of XCFramework.

The Device Risk framework provides full support for Apple's bitcode technology. If your iOS app includes bitcode then additional configuration of your Xcode project is required to enable symbolication of Device Risk stack frames in the crash logs of your app. The necessary symbolic information must be included in the Xcode archive (i.e. .xcarchive bundle) of your application prior to its submission to the App Store.

1. Bring the framework .bcsymbolmap files into your project repository.

   • Create a new directory named "Frameworks-bcsymbolmap". We recommend this directory be located alongside the app's .xcodeproj file.
   • Copy the .bcsymbolmap file from the SDK distribution (FraudForce_SDK/BCSymbolMaps) into your "Frameworks-bcsymbolmap" directory.
     • There should be one such file (representing the arm64 architecture).

2. Add a script to the "Archive" scheme of your application target.

   • Copy the shell script add-framework-symbols-to-app-archive.sh from the SDK distribution (FraudForce_SDK/build_scripts) into your project repository.

   • From the target popup button in the Xcode toolbar, ensure your application target is selected and chose "Edit Scheme…" from the popup menu.

     

   • In the scheme editor, select the disclosure triangle for the "Archive" item and then select "Post-actions".

     • Select the "+" button in order to create a "New Run Script Action".
     • The new action is initially named "Run Script". The suggested name for this action is "Archive Framework Symbols" (though the name does not affect the function of this action).

     

   • Configure and confirm the new script action.

     • The "Shell" text field should read "/bin/sh" (which is the default value).
     • The "Provide build settings from" popup button should be set to the application target.
     • In the text-input area, enter the absolute path to the TransUnion-provided script add-framework-symbols-to-app-archive.sh.
       • For example, if the script is located in a bin directory that is alongside the app's .xcodeproj file then it should read, "${PROJECT_DIR}/bin/add-framework-symbols-to-app-archive.sh"
       • The quotes are an important concern, since this allows for proper execution when path elements include spaces.

3. Ensure that the initial environment variables within this script are set to appropriate values (i.e. those established in both the above steps and in the Installation section).

   • Specifically, BUILD_FRAMEWORKS_DIR (Frameworks-build) and INPUT_BCSYMBOLMAP_DIR (Frameworks-bcsymbolmap) variables must be set to the absolute paths for the appropriate directories.
   • As provided, the script expects both directories to be located alongside the app's .xcodeproj file.

4. (optional) Customize the logging of script output as you desire.

   • By default, Xcode does not handle or display output from scheme-based scripts, thus, the script redirects stdout and stderr to a (unique) log file in /var/tmp.
   • Change the output redirection or ignore all script output by removing redirection (which is declared near the start of the script).

Sample Projects

This download includes two sample Xcode projects that demonstrate the integration of the Device Risk SDK for iOS. These projects require at least Xcode 10 and iOS 11.0.

• The iovSample/iovSampleSwift.xcodeproj project uses Swift to demonstrate two integration techniques: UIKit and WebKit. Each is implemented in its own view controller, and may be tested in a tabbed interface on a simulator or device.

• The iovSample/iovSample.xcodeproj project uses Objective-C to demonstrate two integration techniques: UIKit and WebKit. Each is implemented in its own view controller, and may be tested in a tabbed interface on a simulator or device.

Usage

Use the FraudForce API to enable the Device Risk SDK to start collecting blackbox data asynchronously, and to generate a new blackbox to submit to your back-end service.

1. Import it into your app delegate and call +start when the application becomes active:

   [FraudForce start];
   

   This method starts a low-priority thread that silently collects data from the device with minimal impact on your app.

2. Include your "Subscriber Key" in your application's Info.plist, using the key IOVSubKey.

   <key>IOVSubKey</key>
   <string>6S7EJX4BM7HuKUmriUOuQvXta9mBUs4tAVtGToP6tUY=</string>
   

   This is strongly recommended for all integrations, and it is required for network connections.

3. (optional) Provide a FraudForceDelegate object, which is required for network connections.

   - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
   {
       [FraudForce delegation:self];
   

   …

   - (BOOL)shouldEnableNetworkCalls
   {
       return YES;
   }
   

4. To generate a new blackbox, call +blackbox:

   NSString *blackbox = [FraudForce blackbox];
   

5. Submit the blackbox to your service. The service should then send it to TransUnion to evaluate the transaction. See the iovSample Xcode projects included with the download for a sample implementation.

New Features!

Versions 5.0.0 and above include the ability to make a network call to TransUnion TruValidate's service. This enables the Device Risk SDK to collect additional network information. By default this functionality is turned off and will need to be enabled via a FraudForceDelegate object. Usage of this feature requires a subscriber key be provided. Please contact your TransUnion client representative to acquire a subscriber key.

Important!

The blackbox returned from +blackbox should never be empty. An empty blackbox indicates there is a problem with the integration of the SDK or that the protection offered by the system may have been compromised.

Asynchronous Processing Integration

Each of the native and hybrid integration methods described below benefit from starting the SDK asynchronous processing whenever your application becomes active. To do so, import FraudForce and call +start in the -applicationDidBecomeActive: method of your app delegate:

#import "SampleAppDelegate.h"
@import FraudForce;

-applicationDidBecomeActive:(UIApplication *)application
{
    [FraudForce start];
}

The +start method automatically registers a notification handler to be called when the application goes into the background. This handler asks the OS for time to finish any tasks it has running.

Integrating Into Native Apps

To integrate into a native app using UIKit:

1. Start the asynchronous data collection as described in the Asynchronous Processing Integration section.

2. Import FraudForce and call +blackbox wherever you need a blackbox:

    #import "SampleViewController.h"
    @import FraudForce;
   
    @implementation SampleViewController
    @property (strong, nonatomic) UILabel *blackbox;
   
    // Button press updates text field with blackbox value
    - (IBAction)changeMessage:(id)sender
    {
        self.blackbox.text = [FraudForce blackbox];
    }
   
    @end
   

A more extensive example, including submitting a blackbox in an HTTP request, may be found in the SampleUIKitViewController class for both Swift (iovSampleSwift) and Objective-C (iovSample) in the sample Xcode projects included in the Device Risk SDK download.

WebKit Integration

For a hybrid application using WebKit, create a JavaScript message handler and add it to the context of the web view.

1. Start the asynchronous data collection as described in the Asynchronous Processing Integration section.

2. Build a view controller that implements the WKScriptMessageHandler protocol. Here’s an example in Swift:

   import UIKit
   import WebKit
   import FraudForce
   
   class SampleWebKitViewController: UIViewController, WKScriptMessageHandler
   {
       weak var webView: WKWebView?
   
       override func viewDidLoad() {
           super.viewDidLoad()
           // Set up Blackbox.injectInto() via a user script.
           var js = "var Blackbox = { injectInto: function (id) {\n"
                  + "    window.webkit.messageHandlers.bb.postMessage(id)\n"
                  + " } }\n"
           let userScript = WKUserScript(
               source: js, 
               injectionTime: .atDocumentEnd, 
               forMainFrameOnly: true)
   
           // Set up bb notification.
           let userContentController = WKUserContentController()
           userContentController.addUserScript(userScript)
           userContentController.add(self, name: "bb")
           let configuration = WKWebViewConfiguration()
           configuration.userContentController = userContentController
   
           // Create the web view.
           let webKitView = WKWebView(frame: self.view.bounds, configuration: configuration)
           self.view.addSubview(webKitView)
           webKitView.translatesAutoresizingMaskIntoConstraints = true
           webKitView.autoresizingMask = [.flexibleHeight, .flexibleWidth]
           webView = webKitView
       }
   }
   

   In this example, we added a script handler called "bb" and appointed the view controller itself as the delegate. The Blackbox.injectInto() function calls into this handler.

3. To hook up this script handler, add the following method to handle notifications from JavaScript running in the web view. This example assumes that an HTML ID for a hidden form field will be passed in the message body:

   func userContentController(
       _ userContentController: WKUserContentController,
       didReceive message: WKScriptMessage)
   {
       // Consider checking properties of message.webView.URL, such as the host
       // property, to ensure that it's a request from a known source.
       guard message.name == "bb" else {
           return
       }
   
       // Inject the blackbox.
       message.webView?.evaluateJavaScript(
           "document.getElementById('\(message.body)').value = '\(FraudForce.blackbox())'", 
           completionHandler: nil)
   }
   

   The last statement simply injects the blackbox from a call to FraudForce.blackbox() into the hidden form field. Consider adding code to check the domain and other attributes of the requesting web page to ensure it is allowed to have a blackbox.

4. Then, invoke FraudForce.injectinfo() function any place in the HTML that you need a blackbox:

   <form name="txn" onsubmit="try { FraudForce.injectInto('bbox'); } catch(e) {} return true;">
       <input type="hidden" id="bbox" name="bbox" />
       <!-- Other fields as required --->
       <input type="submit" />
   </form>
   

   NOTE: The try/catch statement ignores errors if none of the FraudForce.injectInto object hierarchy exists. This is essential if the HTML will be used outside of your app.

5. If you have full control over the HTML that will be loaded into WKWebView, including the name of a hidden field into which to inject a blackbox, append the code to inject the blackbox to the user script. Change the JavaScript variable declaration above to:

   var js = "var Blackbox = { injectInto: function (id) {\n"
          + "    window.webkit.messageHandlers.bb.postMessage(id)\n"
          + " } }\n"
          + "document.getElementById('bbox').value = '\(FraudForce.blackbox())'\n"
   

Find a complete example in the SampleWKWebViewViewController class for Swift (iovSampleSwift) and SampleWebKitViewController class for Objective-C (iovSample) in the sample Xcode projects included in the Device Risk SDK download.

Changes

v5.2.0

• Performance improvements.
• Improved handling of background tasks.
• OS requirement raised to iOS 11.
  • SDK supports 64-bit devices only.
• XCFramework artifact released.

v5.1.0

• Blackbox format improvements.
• Performance improvements.
• Addressed all "Main Thread Checker" complaints.
  • Additional protections silence extraneous warnings and streamline development in newer Xcode environments.
  • FraudForce.blackbox continues to be safe to call from any thread.
• Updated sample projects to resolve Xcode 11 build errors.

v5.0.4

• Improved thread safety.
• Updated integration scripts to support macOS Catalina.

v5.0.3

• SDK built with Xcode's "New Build System", the default as of Xcode 10.
• Updated sample projects.

v5.0.2

• Minor recognition improvements.
• Updated the iovSample project (Objective-C) to the latest language, project, and system standards.
  • Removed the UIWebView integration sample.
• Minor improvements to the iovSampleSwift project.
• Note a new entitlement is recommended for apps built with Xcode 10 (and above). See the Installation steps for details.

v5.0.1

• Minor recognition improvements.
  • Recognized devices previously returned (via CheckTransactionDetails) the following attributes
    • mobile.app.procName
    • mobile.system.voipAllowed
  • These values are no longer returned. In place of mobile.app.procName, use mobile.app.exeName which returns the same value.

v5.0.0

• New SDK distribution format, FraudForce.framework supersedes the iovation.framework. The new framework employs a dynamic library (in place of the historical "static archive" approach), which is the modern, recommended (iOS 8 and above), and more stable approach for library distribution.
• New ability to collect additional network information. See "New Features!" in the Usage section.
• New blackbox compression on iOS (up to 40% reduction in blackbox size).
• Improved Swift compatibility.
• New Swift sample project iovSample/iovSampleSwift.xcodeproj.
• Renamed DevicePrint class to FraudForce.
• Removed legacy iovation class (+ioBegin), which was deprecated and replaced in version 4.0.
• OS requirement raised to iOS 9.

v4.3.0

• Define the framework as a module, which removes integration obstacles for Swift clients and improves the overall compatibility with current Xcode build strategies.
• Deprecated the collection of device attributes that were dependent on the ExternalAccessory framework (given restrictions to their availability in recent versions of iOS).

v4.2.0

• Added support for bitcode apps.
• Dropped support for iOS 5, as required to support bitcode-enabled apps.
• Improved jailbreak detection.
• Improved cross-application device recognition for apps using a shared keychain. See the Installation steps for details.

v4.1.0

• Minor updates for improved iOS 9 compatibility.
• Converted the iovSample WebKit demo class from Swift to Objective-C for better compatibility with new releases of Xcode.
• Minor recognition improvements.

v4.0.0

• New API, DevicePrint, handles low-priority asynchronous collection of device data. The old iovation class and +ioBegin method remain in place for backward compatibility.
• Now requires the SystemConfiguration framework.
• Expanded the iovSample project with classes demonstrating both native and hybrid implementations.
• Added WebKit and UIWebView integration instructions.
• Removed autolayout from the iovSample.xcode5 project so that it can be compiled and run against iOS 5.

v3.1.0

• Collecting additional attributes to be used in forthcoming jailbreak business rule.

v3.0.1

• Updated and enhanced library compression. Binary size is now at 434K.

v3.0.0

• Now distributed as a framework instead of standalone .a and .h files.
• Collects additional device attributes and data.
• Restored collection of the advertising identifier, but only if your app includes the optional AdSupport framework.
• The CoreLocation framework is now optional; the SDK will not use it if it's not included in your app.
• Now require the ExternalAccessory and CoreTelephony frameworks.
• Added 64 bit support.
• Simplified the iovSample application code to more closely match current iOS SDK functionality.
• Added iPad and Retina display support to iovSample.

Copyright

Copyright (c) 2010-2021 TransUnion. All rights reserved.