Introduction to ThreatMetrix SDK and FAQ

ThreatMetrix separates Software Development Kits (SDKs) into Android, iOS, OSX, Windows, and Java. Follow the information below to get and use a ThreatMetrix SDK. 

Using ThreatMetrix SDK

Downloading ThreatMetrix SDK

  1. ThreatMetrix SDKs are available under SDK Downloads. Open the appropriate SDK and download the file. 

    1. In order to access the Downloads section, your company must have a contract with ThreatMetrix.  Please contact your Account Manager, or contact the support team:

  2. Once you have determined that you have the necessary support level in place, you may contact ThreatMetrix Support and request to gain access to the ThreatMetrix SDK and the Downloads sections which is located within the Knowledge Base.

  3. A member of the ThreatMetrix support staff will then add the privilege to your user account, after which, you will be able to access these sections upon logging in.

Required Operating System Permissions

Required operating system permissions are introduced as a result of implementing ThreatMetrix SDK.
A major design goal is that wherever possible, additional permissions are optional, instead of making them mandatory

  • The Getting Started and Project Configuration article for each respective platform describes the process of specifying the below permissions during development.

Permissions are described below:

Click to Expand
Mandatory Permissions

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

<uses-permission android:name=
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=
  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=


<uses-permission android:name=
Click to Expand

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+
<string>Insert message here</string>
iOS 6, iOS 7
<string>Insert message here</string>

Viewing ThreatMetrix SDK Logs

Click to Expand

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:

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.


Please see the following article for iOS logging and debugging information:

Upgrading ThreatMetrix SDK

While ThreatMetrix strives to ensure that newer versions of ThreatMetrix SDK are a 'drop-in' replacement, there may be some features or interface changes introduced in newer versions that require code changes.

This document provides an overview of these changes for each major version release. As ThreatMetrix SDK is a standalone library you do not need to upgrade versions sequentially. Upgrading from v1.0 to v2.5 (E.g. skipping v2.1) is a common practice is and is supported. 

Please refer to the documentation for each relevant platform to view the full implementation instructions and code samples:

Android - Upgrading
Click to Expand
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.

iOS - Upgrading
Click to Expand
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.

Using an SSL Certificate to Communicate to the ThreatMetrix Profiling Server

Customers are required to use the ThreatMetrix Enhanced Profiling Service for all ThreatMetrix SDK Implementations. This involves acquiring an SSL certificate as described in Enhanced Profiling via Hosted SSL.

The reasons for this requirement are:

  • Secures the traffic between the ThreatMetrix SDK and the ThreatMetrix Profiling Server

  • Makes it more difficult for fraudsters to identify that data is being routed to a third party from the native app

  • Enables ThreatMetrix to uniquely identify customer specific profiling traffic originating from the ThreatMetrix SDK

  • Enables ThreatMetrix to throttle or disable traffic originating from compromised ThreatMetrix SDK instances

  • Enables ThreatMetrix to allocate additional resources to specific customer implementations with high profiling traffic volume

ThreatMetrix SDK Support Lifecycle Policy

The ThreatMetrix SDK Support Lifecycle Policy provides consistent and predictable guidelines for the availability of support.

ThreatMetrix releases major SDK versions about once every year and minor versions as the need arises. The software product version will show as (Major).(Minor) (e.g., 5.1). 

The SDK is fully supported and maintained until the End of Maintenance (EOM) date in accordance with the following conditions:

  • ThreatMetrix will provide code-level maintenance in the form of bug fixes, work-arounds, maintenance releases, or patches.

    • Bugs must be reproducible by the customer's app development/support team before any fix request is submitted. 

  • ThreatMetrix will determine the best way to resolve reported issues which will commonly require an upgrade to the latest release, as full support is only for the latest major version.

    • Any patch to a major version will require an upgrade to the latest minor version as well.

    • Fixes for critical security issues observed as a result of penetration testing or recently discovered vulnerabilities can be extended to one prior major version.

  • Technical support will continue to be available and provided during this phase as long as a valid support contract exists and is paid in full.

The EOM Period for a Major Software release, “N,” starts when the N+1 release reaches General Availability (GA) (where the product is available for Sale, Support, and Maintenance). The End of Maintenance (EOM) period of a Major Software release is the lessor of: two (2) years from General Availability or one (1) year after the N+1 version reaches General Availability.

Once End of Life (EOL) has been reached, the following applies:

  • The SDK may continue to operate and may be used on an “as-is” basis within the terms of licensing agreements, but future operation is not guaranteed.

  • Technical support and software updates will no longer be available once a product has reached its End of Life date.

  • Historical information in the Knowledgebase or other online resources may still be present, but it is no longer updated and is provided on an “as-is” basis.

The EOL period of a Major Software release is the lessor of: three (3) years from the date it first became Generally Available or two (2) year after the N+1 version becomes Generally Available. Access to ThreatMetrix’s technical support team will be available until a product reaches its End-of-Life date provided that an active support contract exists.

Frequently Asked Questions (FAQ)

See below frequently asked questions regarding the usage and support of ThreatMetrix .

Support Questions

Where can I get support for a ThreatMetrix SDK?

Click to Expand

Please email 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.

 What is the error "HTTP Load Failed" / SSL Handshake errors on iOS 9?

Click to Expand

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:

Customers using ThreatMetrix SDK that are referencing the old profiling infrastructure either via our generic hostname ( or via Enhanced Profiling via Hosted SSL (whereby ThreatMetrix hosts an SSL certificate on behalf of the customer) will be affected. ThreatMetrix  has responded by offering new profiling servers that meet these requirements.

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:

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.

ThreatMetrix SDK v3.1 and newer

This version will use the new profiling hostname by default. Customers that have explicitly  referenced the old profiling infrastructure either via our generic hostname ( or via  Enhanced Profiling via Hosted SSL (whereby ThreatMetrix hosts an SSL certificate on behalf of the customer) should remove these references from their code when implementing ThreatMetrix SDK v3.1. This will cause the SDK to automatically reference the new profiling hostname.


Customers may also choose to obtain a new Enhanced Profiling SSL certificate that meets these stronger SSL cipher requirements. This should be done before deploying ThreatMetrix SDK  in iOS 9 apps. Please contact our support department by clicking the Technical Support button above.

 Why is the SDK unable to communicate with the ThreatMetrix Platform?

Click to Expand

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 ThreatMetrix Technical Support.

What do I do if I get a "FileNotFound" Exception when building the app?

Click to Expand
Error:Execution failed 
for task 
> /git/OII/AuthorizationClient_Android/AuthorizationClient/build/intermediates/bundles/debug/jni/lib/armeabi-v7a/ (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: ). 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.

What do I do if I see an error in Xcode 10.1 and newer?

Click to Expand

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

Use Questions

What are the impacts of Google's requirement to target Android API 30?

Click to Expand

Google has announced their new API level requirements which can be reviewed here:

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.



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.


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.

 Will users of Android Q be impacted?

Click to Expand

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.

 What ports and protocols does ThreatMetrix SDK use?

Click to Expand

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







Used to transmit the profiling data from the device to the ThreatMetrix platform.



Used for Proxy Piercing. A connection is established from the client to the ThreatMetrix platform to expose the True IP address of the device.



Used for DNS IP detection. A connection is established from the device to their configured DNS server, which in turn queries a specialized DNS server in the ThreatMetrix platform to expose the DNS Server IP address used by the device. Theoretically, the DNS server in use by the device should be within a close proximity to the True IP address of the device.


Does ThreatMetrix SDK use WebView?

Click to Expand

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 on Android).

Does the ThreatMetrix SDK use the iOS Advertising Identifier?

Click to Expand

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.


iOS Documentation for IDFA.

iOS Documentation for Vendor ID.

Is ThreatMetrix SDK compliant with Google and Apple app store publishing guidelines?

Click to Expand

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 Play Developer Program Policies:

Developer Distribution Agreement:


App Review:

App Store Review Guidelines (Requires Apple Developer Login):

How many methods are there in ThreatMetrix SDK for Android?

Click to Expand

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.

Why does the ThreatMetrix SDK require the OkHttp library?

Click to Expand

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.