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. |
The code to the right is a complete illustration of how to use the UnitySDK. Each section will have a detailed explanation below.
| 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. |
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.
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?> |
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. |
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.
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 | 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 |
We're happy to answer any questions or concerns.
Chat with our fraud detection experts any day of the week.