Implementation: ThreatMetrix SDK - Canada

Mandatory Permissions

The application must include the following permission in its manifest file:

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

Optional Permissions 

1. Gathering IMEI

Optionally, if the application includes the following extra permission, the IMEI will be gathered to bolster device identification:

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

1. Accessing WIFI State

Including this permission in their application allows the gathering of precise information of the active WIFI network (SSID, BSSID and RSSI).

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

1. Accessing Fine and Coarse Locations

Customers can use Location Services if they have one of the below mentioned permissions. Gathering fine location information is highly recommended as it enables us to detect location updates in shorter distances.

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

OR

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

If using LocationServices, then, the application MUST specify the message used during the permission prompt by adding an entry to the application .plist file:

iOS 8+

<key>NSLocationWhenInUseUsageDescription</key>
<string>Insert message here</string>

iOS 6, iOS 7

<key>NSLocationUsageDescription</key>
<string>Insert message here</string>

The Android logging system provides a mechanism for collecting and viewing system debug output. Logcat dumps a log of system messages, which include things such as stack traces when the emulator throws an error and messages that you have written from your application by using the Log class. You can run Logcat through ADB or from DDMS, which allows you to read the messages in real time.

For more information, please view the following external articles:

• Android Logging: http://developer.android.com/tools/debugging/debugging-log.html

• Android Logcat: http://developer.android.com/tools/help/logcat.html

In AndroidStudio 

• Select your application

• Select the log level

In Logcat command line

• add -v threadtime to print time, process id, and thread id

• run the grep command for SDK tag "t.c.tdm"

Please note that some devices like Huawei filter all logs, warnings and errors. Hence, enabling debug logs on these type of devices is based on the specific model and may require you to search for specific scenarios on the internet.

Upgrading to v4.x

A code change is required due to:

• A new interface name

• Removal of the TidyUp() method

Upgrading to v3.x

Significant changes have been introduced in ThreatMetrix SDK v3.x. As a result, customers upgrading to v3.x are required to make code changes. A new init() function has been introduced and must be called and completed before the doProfie() function. This init() function will ensure the environment is initialized and ready for profiling to occur. The introduction of init() provides customers with greater flexibility.

Upgrading to v2.5

ThreatMetrix SDK v2.5 is the first release that includes Java Native Interface (JNI) code. There are some additional steps required in using these native binaries. Please refer to the Getting Started Guide in the Android Documentation for more information.

If upgrading from v2.0.x-v2.1.x, ThreatMetrix SDK v2.5 is a drop in replacement (with the exception of the JNI code mentioned above).

If upgrading from v1.x, please follow the instructions below:

1. Replace the existing version with the new library

2. v2.0 now includes a new interface for initialization. This simpler interface only requires only an ORG ID to be passed when profiling is performed. The previously required calling options such as fingerprint server, custom URL and profiling options are now deprecated. This makes initialization much simpler, but will require a minor code change.

3. Implement the JNI code as mentioned above.

4. There is no change required in the backend: the Session Query API Call is still performed in the exact same manner as all other ThreatMetrix SDK implementations.

Upgrading to v2.0.x and v2.1.x

1. Replace the existing version with the new library

2. v2.0 now includes a new interface for initialization. This simpler interface only requires only an ORG ID to be passed when profiling is performed. The previously required calling options such as fingerprint server, custom URL and profiling options are now deprecated. This makes initialization much simpler, but will require a minor code change.

3. There is no change required in the backend: the Session Query API Call is still performed in the exact same manner as v1.x implementations.

Upgrading to v4.x

A code change is required due to:

• A new interface name

• Removal of the TidyUp() method

Upgrading to v3.x

Significant changes have been introduced in ThreatMetrix Mobile v3.x. As a result, customers upgrading to v3.x are required to make code changes. A new init () function has been introduced and must be called and completed before the doProfie () function. This init () function will ensure the environment is initialized and ready for profiling to occur. The introduction of init () provides customers with greater flexibility.

Upgrading to v2.x

The most significant change in v2.x of ThreatMetrix SDK for iOS is that it is now distributed as a Framework instead of a static library, simplifying implementation. A minor code change is necessary to link the framework.

Please email tmx.support@lexisnexisrisk.com and please include the following information:

1. Confirm with ThreatMetrix that your Organization (Org ID) has been activated for ThreatMetrix SDK. Profiling calls will fail if this has not been enabled.

2. Environment information:

   1. Which Platform?

      1. iOS or Android?

      2. Did this issue come from an emulator or simulator?

   2. Which version of the operating system?

      1. Which IDE?

      2. XCode or Eclipse, Java Beans, Android Studio etc.

   3. Which version(s) of TheatMetrix SDK?

3. Detailed description of the issue you are having.

4. Your expected result versus your actual result.

5. All debug log files and stack traces generated if the app is crashing

6. Any other custom fields you are passing

7. Are you passing a custom session ID or using the one automatically generated by ThreatMetrix SDK?

It is best practice to use the most recent release of any and all software, whether it be testing environments, OS version, or ThreatMetrix SDK version.

Customers implementing ThreatMetrix SDK on iOS 9 may experience errors relating to SSL Handshake between the SDK and the ThreatMetrix profiling servers. Example errors include:

CFNetwork SSLHandshake failed (-9824)
NSURLSession/NSURLConnection HTTP load failed (kCFStreamErrorDomainSSL, -9824)

Apple implemented changes requiring stronger SSL ciphers in iOS 9, as documented in the iOS 9 release notes in the Networking chapter:

https://developer.apple.com/library/prerelease/ios/releasenotes/General/RN-iOSSDK-9.0/

This has a different impact depending on the version of ThreatMetrix SDK you are using:

ThreatMetrix SDK v1.x - v3.0x

Customers must manually specify the following profiling hostname:

h-sdk.online-metrix.net

NOTE: Customer running these earlier versions of ThreatMetrix SDK are strongly encouraged to upgrade to v3.1 as this version introduces full support for iOS 9.

Each customer must be enabled in the ThreatMetrix Platform in order for the SDK to correctly communicate with our platform.

If you are seeing issues communicating with the ThreatMetrix platform, please contact Payrix Support.

Error:Execution failed 
for task 
':AuthorizationClient:transformNative_libsWithSyncJniLibsForDebug'.
> java.io.FileNotFoundException: /git/OII/AuthorizationClient_Android/AuthorizationClient/build/intermediates/bundles/debug/jni/lib/armeabi-v7a/libtdm-4.0-90-jni.so (No such file or directory)

This is a common gradle issue, it was broken after Gradle1.3.1 and fixed in 2.2-alpha5 (See: https://code.google.com/p/android/issues/detail?id=193063 ). There is however a workaround for this error:

1. Unpack the native jar file.

2. Rename the "lib" directory as "jniLibs"

3. Place the jniLibs directory in your "src/main" directory

4. Recompile and build.

Xcode 10.1 and newer versions are printing the following error when using SDK:

[NetworkInfo] Signal strength query returned error: Error Domain=NSPOSIXErrorDomain Code=13 "Permission denied", descriptor: <CTServiceDescriptor 0x28051d700, domain=1, instance=1> 

This error can be safely ignored https://forums.developer.apple.com/thread/111334 . Customers don't need to worry about this error and don't need to do anything, we can assure them that SDK is not accessing any hidden or forbidden functions. Xcode 10.1.

Google has announced their new API level requirements which can be reviewed here: https://developer.android.com/distribute/best-practices/develop/target-sdk

The new requirements state that starting in August 2021, new apps will need to target API level 30 (Android 11) or above and starting in November 2021, app updates will be required to target API level 30 or above. Existing apps that are not receiving updates are unaffected and can continue to be downloaded from the Play Store.

ThreatMetrix customers are highly recommended to update to the SDK >= 6.2 by November 2021 which can be found at SDK Downloads.

Staying on SDK 6.1 or 6.0 is not encouraged because of unexpected exceptions depending on the device state. If you would like to stay on SDK 6.1 or 6.0 versions, then two permissions will need to be added before November 2021.

• READ_PHONE_STATE

• ACCESS_FINE_LOCATION or ACCESS_COARSE_LOCATION

NOTE: Adding the above permissions might not be enough because the permissions can be revoked at any time, resulting in unexpected behavior, including crashes. SDK 5.4 or lower should not be used because it is not targeting API 30.

The Android M+ Permissions article provides more details regarding the permissions.

IMPORTANT:

As documented by Google, visibility into the inventory of installed apps is restricted when an application targets API 30. This means ThreatMetrix package scan feature can only access a limited list of applications (mainly ones installed by Google or phone manufacturers). To be able to use package scan as before, customers which fall into exception policies can include QUERY_ALL_PACKAGES permission in their application. Please see "Permitted uses of the 'query all packages' permission" and "Exceptions" sections in the above document to check if your application can use QUERY_ALL_PACKAGES permission.

If end users use Android Q, then please note the following:

• End users using Android Q might get a false positive "RandomisedID"

• Customers need to include ACCESS_FINE_LOCATION in order to use wifi positioning.

• device_imei information will not be available.

• device_id might change due to privacy restrictions in Android Q.

The following ports and protocols are used by ThreatMetrix SDK during profiling:

Yes. The WebView implementation in the ThreatMetrix SDK for both iOS and Android is used to gather the following browser based attributes from the device. This information is referenced when the device profiling information is evaluated by our platform.

1. User Agent

2. Browser Plugins

Browser Mime Types

Webview is used as it loads extremely quickly and does not make web requests so it is the most reasonable way for us to capture the aforementioned information. As said: WebView does not communicate with the network. We use native APIs to facilitate the transmission of the profiling data from the device to our platform (NSURLConnection object on iOS and java.net.HttpURLConnection on Android).

No. ThreatMetrix SDK does not use the iOS Advertising Identifier (IDFA). The use of the IDFA was retired in SDK v2.0. The Apple sanctioned Vendor ID is now being used instead.

The discontinuation of the IDFA usage does not in any way impact the existing identifiers that have been generated and assigned to devices, nor does it weaken our device identification.

References:

iOS Documentation for IDFA.

iOS Documentation for Vendor ID.

Yes. ThreatMetrix SDK adheres to all required publishing, advertising and privacy guidelines for both Google and Apple. Under no circumstances will your application be blocked at submission time, or retrospectively removed from the respective marketplaces as a result of ThreatMetrix code. The guidelines for both vendors are listed below:

Google

Google Play Developer Program Policies: https://play.google.com/about/developer-content-policy.html

Developer Distribution Agreement: https://play.google.com/about/developer-distribution-agreement.html

Apple

App Review: https://developer.apple.com/app-store/review/

App Store Review Guidelines (Requires Apple Developer Login): https://developer.apple.com/appstore/resources/approval/guidelines.html

A major design consideration for ThreatMetrix SDK is that it is compact, lightweight and efficient with little or no dependencies on third party libraries or frameworks. Our customers have large, complex applications containing many third party libraries. As a result, some customers are nearing or exceeding the ~65k method limit.

• Google has a comprehensive document on this topic: Building Apps with Over 65k Methods.

• Depending on the exact version, ThreatMetrix SDK has approximately 900 - 1,000 methods.

• There is a way of getting a rough number of methods in a jar, as follows:

dx --dex --output=temp.dex ~/Downloads/TrustDefenderMobile-3.2-53.jar 

cat temp.dex | head -c 92 | tail -c 4 | hexdump -e '1/4 "%d\n"’

•  The dx utility used above is installed with the Android SDK.

Android 6.0 removed support for the Apache HTTP client, and instead recommended the use of the HttpURLConnection class instead. This class has some known limitations, including:

• Cannot cancel network calls

• Cannot execute requests in parallel

• No connection pooling to re-use existing socket connections

• No local caching of responses

• No async interface to avoid blocking in main or UI thread

• No wrapping REST API calls

• No retry policy and backoff

As a result, ThreatMetrix evaluated several well known HTTP libraries to address the above issues. OkHttp from Square was chosen due to its performance, stability and its proven track record.

As of ThreatMetrix SDK v4.0, OkHttp is mandatory. The Apache HTTP client is no longer compatible. If the Android HttpURLConnection class is enhanced in a future Android release, or another native Android class is introduced to better handle HTTP requests, ThreatMetrix will perform an evaluation to determine if they are suitable.