Mobile Device Fingerprinting SDK Documentation - Integrating The IPQS SDK

This feature uses a mixture of IPQualityScore's web fingerprinting and the IPQS mobile device fingerprinting SDK to enable your android app to accurately identify fraud and abuse with mobile device fingerprinting. Verify new or returning users and identify high risk behavior, such as mobile emulators, residential botnets, location spoofing, bots, non-human requests, fake accounts, and hijacked devices. Easily identify app install quality and see greater insights into your audience's KPIs. Detect duplicate accounts and prevent free trial abuse, fraudulent users, fake installs, and much more.

Please see the instructions below for further guidance on setting up the Android Device Fingerprint SDK.

Gradle Setup

Step #1: In your app's top level build.gradle file you'll need to add two entries to your repositories list.

maven {
            url = uri("https://downloads.ipqualityscore.com/maven2/")
            credentials {
				username "ipqs"
                password "<YOUR_API_KEY>"
            }
            authentication {
                basic(BasicAuthentication)
            }
        }

As an example your repository list should now look like this:

allprojects {
	repositories {
		google()
		jcenter()
		maven {
            url = uri("https://downloads.ipqualityscore.com/maven2/")
            credentials {
				username "ipqs"
                password "<YOUR_API_KEY>"
            }
            authentication {
                basic(BasicAuthentication)
            }
        	}
		}
		}

Step #2: In your app's module build.gradle file you'll need to add a few different entries to your dependencies list:

implementation 'com.ipqualityscore:FraudEngine:1.2.7'

Step #3: Remember to replace "<YOUR_API_KEY>" with your actual API Key and sync your gradle.build file by clicking on the "elephant".

Step #4: (Optional) The IPQS SDK can take advantage of the following permissions if you add them to your app. Permissions are added to the «mainifest» section of your AndroidManifest.xml file. These permissions help us provide better results and create a better overall picture of your users. We highly recommend adding at least the ACCESS_NETWORK_STATE, ACCESS_WIFI_STATE and READ_PHONE_STATE permissions listed below. The location permissions are only useful if you intend to use the allowLocationRequest() system or your app already collects location data from your users.

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.READ_PHONE_STATE"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.MODIFY_AUDIO_SETTINGS" />

Android App Integration

Now you're ready to configure the IPQualityScore SDK.

Please login or create an account to access your API Key.

You'll want to configure the SDK inside of your android app's activity, preferably your main activity. This may change based on the way you wish to implement the SDK:

import com.ipqualityscore.FraudEngine.IPQualityScore;

...

IPQualityScore api = IPQualityScore.getInstance();
api.setAppKey("api_key_here");
api.setActivity(this); // Not required if using the Proxy/Email portions of the SDK.

Device Fingerprinting

At this point you'll be able to call our mobile device fingerprinting anywhere inside your application's activities. Here's an example of how to retrieve the fraud score for a given device using the SDK:

import android.widget.Toast;
import android.content.Context;
import com.ipqualityscore.FraudEngine.MobileTracker;
import com.ipqualityscore.FraudEngine.IPQualityScore;
import com.ipqualityscore.FraudEngine.Interfaces.OnMobileTrackerResult;
import com.ipqualityscore.FraudEngine.Utilities.IPQualityScoreException;

...

try {
	/*
	* Set custom variables if you have them before calling performFraudCheck()
	* MobileTracker.addCustomVariable("userID", "1234");
	*/
	
	MobileTracker.performFraudCheck(new OnMobileTrackerResult(){
		@Override
		public void onResult(MobileTrackerResult result){

			// Display a result via a toast.
			Context context = IPQualityScore.getInstance().getContext();
			CharSequence text = "You have a fraud score of " + result.getFraudScore().toString() + "!";

			int duration = Toast.LENGTH_SHORT;
			Toast toast = Toast.makeText(context, text, duration);
			toast.show();

		}
	});
} catch(IPQualityScoreException e){

	// Display the error via toast.
	Context context = IPQualityScore.getInstance().getContext();
	CharSequence text = e.getMessage();

	int duration = Toast.LENGTH_SHORT;
	Toast toast = Toast.makeText(context, text, duration);
	toast.show();

}

Sample App

Here's a complete "sample app". The app will close if the user's fraud score is greater than 85.

package com.ipqualityscore.testsdk;

import android.os.Bundle;
import android.widget.TextView;

import androidx.appcompat.app.AppCompatActivity;

import com.ipqualityscore.FraudEngine.IPQualityScore;
import com.ipqualityscore.FraudEngine.MobileTracker;
import com.ipqualityscore.FraudEngine.Results.MobileTrackerResult;
import com.ipqualityscore.FraudEngine.Interfaces.OnMobileTrackerResult;
import com.ipqualityscore.FraudEngine.Utilities.IPQualityScoreException;

public class MainActivity extends AppCompatActivity {

	@Override
	protected void onCreate(Bundle savedInstanceState) {
		try {
			IPQualityScore api = IPQualityScore.getInstance();
			api.setAppKey("api_key_here");
			api.setActivity(this);
			
			/*
			* Set custom variables if you have them before calling performFraudCheck()
			* MobileTracker.addCustomVariable("userID", "1234");
			*/
			
			MobileTracker.performFraudCheck(new OnMobileTrackerResult(){
				@Override
				public void onResult(MobileTrackerResult result){
					if(result.getFraudScore() > 85){
						android.os.Process.killProcess(android.os.Process.myPid());
						System.exit(1);
					}
				}
			});
		} catch(IPQualityScoreException e){
				
				// Display the error via toast.
				Context context = IPQualityScore.getInstance().getContext();
				CharSequence text = e.getMessage();

				int duration = Toast.LENGTH_SHORT;
				Toast toast = Toast.makeText(context, text, duration);
				toast.show();
				
		}
	}
}

Additional Settings

Our SDK allows you to specify that you'd like us to attempt to capture location information from your user via a permission request check. You can enable this like such:

IPQualityScore api = IPQualityScore.getInstance();
api.setAllowLocationRequest(true);

Our SDK allows you to specify custom variables for statistics, postback and enhanced scoring purposes. We only accept strings for both the key and values specified. Please make sure you cast/convert the type of your data appropriately. You can set a custom variable like such:

MobileTracker.addCustomVariable("userID", "1234");

Some apps may not want to collect the advertising ID or may get flagged by google for doing such. We've added a method to disable it (You no longer need to include 'androidx.ads:ads-identifier:1.0.0-alpha04' in your build.gradle):

IPQualityScore api = IPQualityScore.getInstance();
api.setCaptureAdvertisingID(false);

Result Methods

Our SDK offers a wide range of result methods/functions to enhance your experience and help prevent fraudulent activity. The variable "result" below signifies an object of com.ipqualityscore.FraudEngine.Results.MobileTrackerResult.

Name	Function	Description	Type
getRaw	result.getRaw()	Get the raw json string response from our API. This can be useful for debugging purposes, providing feedback and long term storage.	String
getMessage	result.getMessage()	Get the response message string for this request. This is generally 'Success', but can include administrator level information on why a request failed. (Out of credits, etc...)	String
getSuccess	result.getSuccess()	A boolean containing the request's success or failure status. True on success, false on failure.	Boolean
getRequestID	result.getRequestID()	The unique ID associated with this request. Helpful for debugging and postbacks.	String
getFraudScore	result.getFraudScore()	Number 0 - 100 describing how likely this device is to commit fraud. 0 being not at all, 100 being definitively fraud. We suggest blocking users greater than 85.	Float
getCountryCode	result.getCountryCode()	A two character country code based on this user's IP address.	String
getRegion	result.getRegion()	A string describing the region this user's IP is from.	String
getCity	result.getCity()	A string describing the city this user's IP is from.	String
getISP	result.getISP()	A string describing the ISP this user's IP belongs to.	String
getOrganization	result.getOrganization()	A string describing the Organization this user's IP belongs to.	String
getASN	result.getASN()	The ASN assigned to the ISP this user's IP belongs to.	Integer
getLatitude	result.getLatitude()	The latitude this user's IP is at.	Float
getLongitude	result.getLongitude()	The longitude this user's IP is at.	Float
getIsCrawler	result.getIsCrawler()	Returns true if this user's IP is from a known search engine crawler.	Boolean
getTimezone	result.getTimezone()	Returns the timezone this user's IP is from.	String
getHost	result.getHost()	Returns the hostname of this user's IP address.	String
getIsProxy	result.getIsProxy()	Returns true if this user's IP is a known proxy.	Boolean
getIsVPN	result.getIsVPN()	Returns true if this user's IP is a known VPN.	Boolean
getIsTOR	result.getIsTOR()	Returns true if this user's IP is a known or suspected TOR node.	Boolean
getRecentAbuse	result.getRecentAbuse()	Returns true if this user's IP has been reported for being abusive recently or if this device has been seen preforming abusive actions.	Boolean
getBotStatus	result.getBotStatus()	Returns true if this user's IP has been reported for botting or if this device has been seen preforming bot like actions.	Boolean
getConnectionType	result.getConnectionType()	Classification of the IP address connection type as "Residential", "Corporate", "Education", "Mobile", or "Data Center".	String
getDeviceSuspicious	result.getDeviceSuspicious()	Returns true if this device has suspicious properties or if this device has been seen preforming suspicious activities recently.	Boolean
getDeviceEmulated	result.getDeviceEmulated()	Returns true if this device has been emulated or appears to have been emulated.	Boolean
getDeviceID	result.getDeviceID()	A unique identifier for this device.	String

Retrieve Results & Risk Analysis Using The Postback API Or Request List API

Postback Example to Retrieve Latest Request by UserID
Please make sure your initial API request passed a valid "userID" value (or any variable of your choice) using the "addCustomVariable" function. The variable name must be set on your custom tracking variables.

Retrieve multiple requests with the Request List API and also search by Device ID and IP Address.
Please make sure your initial API request passed a valid "userID" value (or any variable of your choice) using the "addCustomVariable" function. The variable name must be set on your custom tracking variables.

Explore our other APIs for user validation and fraud scoring, such as the IP Reputation SDK and Email Validation SDK.