Last Updated: 20 September 2023 | Change Log

iOS 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 iOS.

ThreatMetrix iOS SDK

The ThreatMetrix iOS SDK provides mobile application developers with iOS 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 modules for profiling in the application.

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

3. Call the doProfile() method to begin device profiling. ThreatMetrix SDK modules 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. This module needs to be paired with the 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.

Download .dmg files of TMXProfiling and TMXProfilingConnections modules and extract them to get .xcframework file.

Copy the .xcframework files to your application directory as a dependency.

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

Pass the below details to configure() method.

Get instance and initialize

1. Create the instance of the TMXProfiling inside initProfile() method.
2. Call configure() method by passing at a minimum TMXOrgId and TMXFingerprintServer/Profiling domain.

The sharedInstance() method of TMXProfiling class is used to return a singleton instance of the ThreatMetrix Object. The instance is only required to be initialized once.

Start profiling

Create a method doProfile() to start profiling and send some additional attributes along with profiling information.

Here’s an example of how you can create instance and initialize profiling by creating initProfile() and doProfile() methods.

import TMXProfiling
import TMXProfilingConnections
class TmxProfileController : ObservableObject{

    //Get a singleton instance of TMXProfiling
    let profile: TMXProfiling!       = TMXProfiling.sharedInstance()
    var sessionID     : String  = ""

    func initProfile(){

        // The profile.configure method is effective only once and subsequent calls to it will be ignored.
        // Please note that configure may throw NSException if NSDictionary key/value(s) are invalid.
        // This only happen due to programming error, therefore we don't catch the exception to make sure there is no error in our configuration dictionary

            profile.configure(configData:[
                                // (REQUIRED) Organisation ID
                                TMXOrgID              :"afevfjm6",
                                // (REQUIRED) Enhanced fingerprint server
                                TMXFingerprintServer  :"ddc-test.worldpay.com"
                                ])

    }

   func doProfile()
    {

        let customAttributes : [String : Array<String>] = [TMXCustomAttributes: ["attribute 1", "attribute 2"]]

        // Fire off the profiling request.
        // You will be notified of the profiling result in the closure passed in callbackBlock
        let profileHandle: TMXProfileHandle = profile.profileDevice(profileOptions:customAttributes, callbackBlock:{(result: [AnyHashable : Any]?) -> Void in
                let results:NSDictionary! = result! as NSDictionary
                let status:TMXStatusCode  = TMXStatusCode(rawValue:(results.value(forKey: TMXProfileStatus) as! NSNumber).intValue)!

                let statusString: String =
                status == .ok                  ? "OK"                   :
                status == .networkTimeoutError ? "Timed out"            :
                status == .connectionError     ? "Connection Error"     :
                status == .hostNotFoundError   ? "Host Not Found Error" :
                status == .internalError       ? "Internal Error"       :
                status == .interruptedError    ? "Interrupted Error"    :
                "Other"
                print("\nProfile completed with: \(statusString)\nSession ID: \(self.sessionID)")
        })
        // Session id is immediately available on the instance of TMXProfileHandle following to the call to profile.profileDevice()
        self.sessionID = profileHandle.sessionID;
        print("Session equals :- \(self.sessionID)");
    }

}

Obtaining profiling result

Obtain the result of profiling using TMXStatusCode and get SessionId using profileHandle.sessionId. Profiling is successful, if the status of profiling result is returned as OK.

Linking the device data with the assessment

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

Next steps

Assessment