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(<String> 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:
 <bool> 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(<IPQSResults> 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:
 <IPQSResults> 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:
 <bool> True if key/value pair is successfully added to the fingerprint. False otherwise.
FindUserLocation(<bool>) 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(<bool>) 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(<bool>) 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(<bool>) If parameter is true, the device fingerprinter will get a deeper fingerprint, resulting in a more accurate fraud score. 

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.
SetHttpsTimeout(<int> 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(<OnIPQSCompletion>) 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?>
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).

 

 

The below table provides an explanation of all IPQSResults fields:

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

Ready to eliminate fraud?

Start fighting fraud now with 5,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