- About the IPQS APIs
- Proxy & VPN Detection API
- Email Verification API
- Phone Number Validation API
- Malicious URL Scanner API
- Device Fingerprint API
- Mobile Device Fingerprinting SDK
- Gaming Fraud Detection SDK
- Dark Web Leak API
- Malware File Scanner API
- Request List API
- Fraud Reporting API
- Account Management APIs
- Bulk Validation CSV
- Allowlist Blocklist APIs
- Plugins Platforms Integrations
- IP Reputation Database
- IP Address Abuse Feed
- Email Verification Database
-
Custom Integrations
- Getting Started
- Authentication
- Refresh Secret
- IP & Proxy Checks
- Email Verification Checks
- Phone Number Validity Checks
- Device Tracker
- List Device Trackers
- Device Tracker Statistics
- Login Tokens
- Overview Statistics
- Recent Proxy Statistics
- Recent Email Statistics
- Fraud Reporting
- Retrieve Requests by ID
- Country List API Documentation
- Release Notes
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( |
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: |
| 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( |
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: |
| 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: |
| 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( |
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;
}
}