IPQS
Using the SDK

About

This page details how to integrate the UnitySDK into your project's code. A detailed explanation of each section is given as well as a description of the resulting fraud score. The process described below is the same, regardless of which platform your game targets.

It is best practice to place SDK method calls in try/catch statements and include the given Debug.Log commands.

Note

The SDK call MUST be on the main thread. Everything that can be ran asynchronously is already configured to do so.

Full Example

The code to the right is a complete illustration of how to use the UnitySDK. Each section will have a detailed explanation below.

Parameters

Parameter Description
API_KEY This value must be set to your project's individual API key.
IPQSUnitySDK An object of this type handles all interactions between your project and the SDK.
ipqsResults This object holds the fraud score results after GetScore() has been executed. See IPQSResults Object below for more details.

Methods

IPQS_Interface Example Class Methods:

Method Description
AddCustomVariable( key, <String?> value) Attaches user created data to the fingerprint as a dictionary entry. Allows you to attach custom variables from anywhere in your project. Parameters: key = String value used as the dictionary entry's key `ƒvalue = String value used as the dictionary entry's value Return: True if key/value pair is successfully added to the fingerprint. False otherwise.
GetResults() Getter method for accessing the fraud score if one has been received. Otherwise it returns null. See IPQSResults Object below for more details. Return: <IPQSResults?>
OnCompletion( results) This call back method is sent to the UnitySDK and is automatically called after the fingerprinter and the api call are complete. See OnCompletion() below for more details. Parameters: results = the results of the api call as a non-null IPQSResults object. **Return:**void
GetScore() This sets all custom fingerprint settings, adds custom variables, completes a device fingerprint, makes an api call to IPQualityScore servers, and retrieves an IPQSResult object. Return: void

IPQSUnitySDK Class Methods:

All are public non-static instance methods.

Warning

Some of these settings will require you to gain user permission before calling GetScore(). See Customizing the Fingerprint: Permission below for more details.

Method Description
AddCustomVariable( key, value) Attaches user created data to the fingerprint as a dictionary entry. Parameters: key = String value used as the dictionary entry's key `ƒvalue = String value used as the dictionary entry's value Return: True if key/value pair is successfully added to the fingerprint. False otherwise.
FindUserLocation() If parameter is true, the fingerprinter will get the user's location. See Customizing the Fingerprint: Permission below for more details. Return: True if fingerprinter is currently set to getting location data. False otherwise.
FindUserAdvertisingID() If parameter is true, the fingerprinter will get the user's advertising id (if present). See Customizing the Fingerprint: Permission below for more details. Return: True if fingerprinter is currently set to getting the advertising id. False otherwise.
CopyUserClipboard() If parameter is true, the fingerprinter will get get what's currently on the user's clipboard. See Customizing the Fingerprint: Permission below for more details. Return: True if fingerprinter is currently set to getting clipboard data. False otherwise.
SetIsEnhancedScore() If parameter is true, the device fingerprinter will get a deeper fingerprint, resulting in a more accurate fraud score.
SetHttpsTimeout( length) This sets the timeout value for the HTTPS call to the IPQualityScore servers. Default value is 15 seconds. Parameter: Time in seconds as an integer. Return: True if new time setting has been successfully set. False otherwise.
GetScore() This starts the process of fingerprinting the device and getting a fraud score. Parameters: A callback method of type OnIPQSCompletion delegate. Callback method must have a single String parameter. See OnCompletion() below for more details. Return:
GetResults() Getter method for accessing the fraud score if one has been received. Otherwise it returns null. See IPQSResults Object below for more details. Return: <IPQSResults?>

SetIsEnhancedScore() fields

Warning: A true setting takes an average of 7 seconds to fully fingerprint a device. See Customizing the Fingerprint: Permission below for more details and how to avoid the added delay. Return: True if fingerprinter is currently set to getting an enhanced score. False otherwise.

OnCompletion() Callback Method

This method allows all the asynchronous portions of the SDK to finish before recording the API response (the device's fraud score). The only mandatory element is ipqsResults = results;

If your project is using the fraud score immediately after receiving it, this is the optimal place to include whatever code is necessary for your project to utilize the fraud score data.

An example is given that adds the fraud score to the editor log.

Warning

This should be for testing only. Do not include the log in final production. Logging the fraud score will only make fraud easier for scammers.

Customizing the Fingerprint

The IPQS Unity SDK Class Methods allow you to customize your project's fraud score fingerprint. This includes sending custom data points you collect, not collecting data that will require a user to grant permission, and completing an exhaustive fingerprint that could take more time than desired. Each method will return a boolean indicating the current fingerprinter setting.

This section is not necessary if you do not have custom variables and wish to use the default "false" settings. However, it is best practice to go ahead and set them to ensure the correct settings are used.

Permission:

If a user's permission is required, the UnitySDK does not prompt the user. This way, each project can ask for permission in a manner and time that is best for the intended audience. Some devices automatically prompt the user for permission if it has not already been granted or refused.

The UnitySDK does not wait for replies to these automatic prompts or control the permission's message. So, the program may stall until a response is received, or it may not collect any data even if the user chooses yes. To avoid this, ask for user permission before calling GetScore().

Enhanced Score:

This is a more in-depth fingerprint of the user's device. As such, it will result in a significantly more accurate fraud score. However, the fingerprint takes an average of 7 seconds to complete. This is expected to be longer on slower devices. A standard fingerprint and score take less than 1 second on all tested devices. Therefore, getting an enhanced fraud score is best when the end user expects to wait (for example, during the initial game load or a major scene transition). This way, the fraud score is ready when needed, and the end user is not inconvenienced.

IPQS Results Object

All fields can be null or except for "success," "message", and "request_id". A failed fingerprint or API call will still return an IPQSResults object, however only the "success" and "message" keys will exist. Their values will be logged on the stack trace.

Each parameter can be accessed by evoking <IPQSResults_INSTANCE_VARIABLE>.field_name (ex: ipqsResults.fraud_score).

{
	success : "true",
	message : "Success",
	fraud_score : 25,
	country_code : "US",
	region : "California",
	city : "Mountain View",
	ISP : "Frontier Communications",
	ASN : 5164,
	latitude : 37.422942,
	longitude : -122.08424100314876,
	is_crawler : false,
	timezone : "America/LA",
	host : "64-233-176-113.lwvl.ca.frontiernet.net",
	proxy : false,
	vpn : false,
	tor : false,
	ip_address : "64.233.176.113",
	organization : "Frontier Communications",
	recent_abuse : false,
	bot_status : false,
	connection_type : "Corporate",
	suspicious_device : null,
	device_emulated : false,
	device_id : "9b91c28d819cf80db2dd19e48d1e1d4725c495bac5f3639f0c1eaf29a2ab3de6",
	revision : 2,
	request_id: "FvkMEbNwiY"
}

The below table provides an explanation of all IPQSResults fields:

Field Description Type
success A boolean containing the request's success or failure status. True indicates existence of a fraud_score, false otherwise. Boolean
message 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
fraud_score 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
country_code A two letter country code based on this user's IP address. String
region A string describing the region this user's IP is from. String
city A string describing the city this user's IP is from. String
ISP A string describing the ISP this user's IP belongs to. String
ASN The ASN assigned to the ISP this user's IP belongs to. Integer
latitude The latitude of this user's IP location. Float
longitude The longitude of this user's IP location. Float
is_crawler Returns true if this user's IP is from a known search engine crawler. Boolean
timezone Returns the timezone this user's IP is from. String
host Returns the hostname of this user's IP address. String
proxy Returns true if this user's IP is a known proxy. Boolean
vpn Returns true if this user's IP is a known VPN. Boolean
tor Returns true if this user's IP is a known or suspected TOR node. Boolean
ip_address The device's unique public ip address. String
organization A string describing the organization this user's IP belongs to. String
recent_abuse 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
bot_status Returns true if this user's IP has been reported for botting or if this device has been seen preforming bot like actions. Boolean
connection_type Classification of the IP address connection type as "Residential", "Corporate", "Education", "Mobile", or "Data Center". String
suspicious_device Returns true if this device has suspicious properties or if this device has been seen preforming suspicious activities recently. Boolean
device_emulated Returns true if this device has been emulated or appears to have been emulated. Boolean
device_id A unique identifier for this device. String
revision API version String
request_id The unique ID associated with this request. Helpful for debugging and postbacks. String
using IPQualityScore.UnitySDK;
using Newtonsoft.Json;
using System;
using UnityEngine;

/*
 * IPQS_Interface
 * 
 * A simple example for how to use the IPQualityScore.UnitySDK
 * 
 * SETUP:
 *    - Place your IPQS API key int the constant "API_KEY"
 *    - Place the IPQualityScore.UnitySDK.<Platform>.dll file 
 *          in the folder Assets/Plugins
 * 
 * DO NOT!!!
 *    Do not run ipqsUnitySDK.GetScore(OnCompletion) asynchronously.
 *          (marked below)
 *    Everything in the SDK that can run asynchronously is already
 *          set up to do so.
 *    There are a few important items that will crash if not 
 *          ran on the main thread.
 *    
 */

#nullable enable

public class IPQS_Interface
{
    /*
	 * Parameters
	 */
    // Your API Key
    private const string API_KEY = "<< YOUR KEY HERE >>";

    // The SDK object
    private static IPQSUnitySDK ipqsUnitySDK = new IPQSUnitySDK(API_KEY);

	// The IPQualityScore fraud score
	private static IPQSResults? ipqsResults;


    /*
     * Method for receiving a fraud score
     */
    public void GetScore() {
        try {

            /* 
             * Set custom fingerprint settings: Optional
             * default = false
             * parameter = bool: true obtains a better fraud score, 
			 *      false otherwise.
             * return = bool indicating what the fingerprinter
             *      has been set to
             * 
             * WARNING!!! If FindUserLocation or CopyUserClipboard are
             *      true you must prompt the user BEFORE 
             *      calling GetScore().
             *      Otherwise that data will not be collected.
             */
            ipqsUnitySDK.FindUserLocation(false);
            ipqsUnitySDK.FindUserAdvertisingID(false);
            ipqsUnitySDK.CopyUserClipboard(false);
            ipqsUnitySDK.SetIsEnhancedScore(false);

            /*
             * Add all custom variables.
             *      Not necessary if not collecting additional data
             *      
             * These custom keys must be set up in your IPQualityScore 
             *      dashboard beforehand.
             * 
             * AddCustomVariable(<String> key, <String?> value)
             * 
             * return = bool.  true = the fingerprinter actually contains
             *      the given key and value.  false otherwise
             * An alternative way of doing this is given at the bottom
             *      of this class
             */
            ipqsUnitySDK.AddCustomVariable("Key #1", "Value #1");
            ipqsUnitySDK.AddCustomVariable("Key #2", "Value #2");
            ipqsUnitySDK.AddCustomVariable("Key #3", "Value #3");
            ipqsUnitySDK.AddCustomVariable("Key #4", "Value #4");


            /* 
             *  Customize HTTPS Timeout Length: OPTIONAL
             *      Default = 15 seconds
             *      Must be set before getting score to see effect
             *  
             *  SetHttpsTimeout(<int> length)
             *  Parameter = custom length of time in seconds
             *  return = true if time length setting was properly set,
             *      false otherwise
             */
            ipqsUnitySDK.SetHttpsTimeout(15);


            /*
             * Gets the device fingerprint and fraud score.
             * This MUST be executed on the main thread
             * Parameter: A callback method (illustrated below)
             */
            ipqsUnitySDK.GetScore(OnCompletion);
        }
        catch (Exception e) {
            /* 
             * This log will help diagnose any unexpected 
             * exceptions: please include
             */
            UnityEngine.Debug.Log("IPQualityScore.IPQS_Interface:GetScore: "
                                  + e.ToString());
        }
    }



    /*
     * Callback Method for GetScore(<callback method>)
     * 
     * This is ran once the SDK receives a fraud 
     *     score response.
     *      
     * Parameter results = a copy of the fraud score results
     *     as an IPQSResults object
     */
    private static void OnCompletion(IPQSResults results) {
        try {
            
			// record fraud score
			ipqsResults = results;

            /*
             * Run any methods necessary to your project that 
             * utilize the fraud score
             */
        }
        catch (Exception e) {
            /* 
             * This log will help diagnose any unexpected 
             * exceptions: please include
             */
            UnityEngine.Debug.Log("IPQualityScore.IPQS_Interface:OnCompletion: "
                                  + e.ToString());
        }
    }



    /*
     * Alternative way to add custom variables from elsewhere
     *  	in the project.
	 *
	 * Return: 
	 *		true if key/value pair successfully added
	 * 	    false otherwise 
	 *
     * NOT REQUIRED
     */
    public bool AddCustomVariable(String key, String? value) {
        return ipqsUnitySDK.AddCustomVariable(key, value);
    }



    /*
     * GetResults()
     * 
     * A simple getter method for the fraud score after a
	 *     successful API call.
     * 
     * return = IPQSResult?
     *     null if fraud score has not been obtained yet.
     *
     * NOT REQUIRED if using the fraud score results in the
     *     call back method above, onCompletion(<IPQSResults>).
     */
    public static IPQSResults? GetIPQSResults() {
        return ipqsResults;
    }

}

Ready to eliminate fraud?

Start fighting fraud now with 1,000 Free Lookups!

We're happy to answer any questions or concerns.

Chat with our fraud detection experts any day of the week.

Call us at: (800) 713-2618