Idea
KillBot anti-fraud integration via API is achieved by placing JS code on the website. This code collects and sends browser data to the server. The verification result can be obtained via a server request including the session number.
To collect data, you need to include the script https://data.killbot.ru/js/c.js — this script will send data to the server in 4 requests with a total volume of 5-15 KB.
The KillBot script does not collect personal data or form input data. KillBot does not request access to the microphone, location, camera, or other de-identifying objects.
The verification result is obtained by making a request to the server at https://data.killbot.ru/r/get.php. Since we do not know exactly when all 4 data requests have reached the server, the request to https://data.killbot.ru/r/get.php should be made with a timeout. If the response is not ready, you need to repeat the request.
Adding the data sending script c.js
The following shows a sample JavaScript code that initializes sending data to the KillBot server.
const kbKey = "Stitjtzrjo"; /* Obtain this from your KillBot dashboard - it is located in the first line of the code to be placed on your site. */
let kbUserID = Math.floor(Math.random()*900000000); // User ID, stored in the KillBot database, can be stored as a long-lived cookie, type - MySQL BigInt
let kbSessionID = Math.floor(Math.random()*900000000); // Session ID, stored in the KillBot database, can be stored as a cookie with a short lifetime, type - MySQL BigInt
var kbB = null; // This variable is not used here, but without it, the script will throw an error. It can stay for now; we'll fix it in future versions.
try{
// Load the c.js script that collects and sends browser data to the server
var kbTS = document.createElement("script");
kbTS.type = "text/javascript";
kbTS.async = true;
kbTS.src = "https://data.killbot.ru/js/c.js?hash_str=" + kbKey + "&r="+ btoa(document.referrer)+"&url="+btoa(location.href)+"&c="+kbSessionID+"&kbUserID="+kbUserID;
document.head.appendChild(kbTS);
}
catch(e){
let message = 'KB Error: ' + e.name + ":" + e.message;
console.log(message);
alert(message);
die(message);
}
Example of getting the verification result with JavaScript
The verification result should be retrieved via a GET request with the session parameter. Example request:https://data.killbot.ru/r/get.php?c={{kbSessionID}}
The verification result can be obtained using either JS or backend methods. When obtaining the verification result with JS, keep in mind that a bot might fake our server, so for reliability, the result can also be obtained on the backend.
Below is an example of obtaining the verification result with JS: if the data is not received, the script makes another request to the server.
const kbTimeout = 2000; /* The period after which to make a request to the server for the result. */
const kbMaxRequests = 10; /* Maximum number of requests to the server to retrieve the result. */
let response = null;
let requestCount = 0;
function makeRequest() {
if (requestCount >= kbMaxRequests) {
if (response){
complete(response);
}else{
fail();
}
return;
}
requestCount++;
const xhr = new XMLHttpRequest();
xhr.open('GET', 'https://data.killbot.ru/r/get.php?c='+kbSessionID, true);
xhr.timeout = 15000;
xhr.onreadystatechange = function () {
if (xhr.readyState === 4) { // 4 means the request is done.
if (xhr.status === 200) { // 200 means a successful return.
try {
response = JSON.parse(xhr.responseText);
if (!response || response.hasOwnProperty("error") === true || response.l === false) {
setTimeout(makeRequest, kbTimeout);
} else {
complete(response);
}
} catch (e) {
console.error('Error parsing JSON response:', e);
setTimeout(makeRequest, kbTimeout);
}
} else {
console.error('HTTP error: '+xhr.status+"; "+xhr.statusText);
setTimeout(makeRequest, kbTimeout);
}
}
};
xhr.send();
}
function complete(response){
// Actions on successful data retrieval from the KillBot server
}
function fail(){
// Actions on error when data is not retrieved
}
Example server response for the request https://data.killbot.ru/r/get.php :
{
"bot":false, // Result of bot check according to the KillBot script settings; fraud.true means it's a bot
"fraud":false, // Same as the bot parameter; if bot.true, it's a bot
"l":true, // Whether the script has loaded completely or not. Simple bots may not fully load the script as they optimize their operation time. However, due to internet connectivity, the script may also not fully load for a real user in some cases. l.true means the script is fully loaded without errors
"d":false, // Parameter from script settings: whether to block the visit or not. If d.true, the visit should be blocked from accessing the site
"snsht":2969538378, // Main browser snapshot
"snsht_d":2696850341, // Detailed browser snapshot
"ua":"Chrome", // Browser of the visit, for information - taken from the user-agent
"sess":"457868305", // Session number: kbSessionID
"UserID":"468073784", // User ID: kbUserID
"capt":false, // Parameter from script settings: whether to show a captcha or not. If capt.true, a captcha should be shown for this visit
"bl":false, // Whether the browser snapshot snsht is in the known bots group.
"wl":true, // Whether the browser snapshot snsht is in the known browsers group.
"wld":false, // Whether the detailed browser snapshot snsht is in the known browsers group.
"bld":false, // Whether the detailed browser snapshot snsht_d is in the known bots group.
"ip":"51.158.237.65", // IP address from which the visit occurred
"inf":false, // Parameter from script settings: whether to show an infinite captcha or not. If inf.true, an infinite captcha (one that cannot be bypassed) should be shown for this visit
"sc":true, // System parameter for internal use in KillBot - not needed
"t":true, // Whether the script is paid or not; if t.true, the script operates in paid mode without restrictions
"utm":"bot", // Parameter from script settings: the name of the HTTP parameter where the bot check result should be placed.
"url": "" // Parameter from script settings: the URL to which to redirect for this visit
}
In case of an error, the response will contain an error field with the error message.
Example of an erroneous response:
{
"error_code":100, // Error code. error_code=100: Session ID (kbSessionID) does not exist, error_code=200: any other error - see description
"error":true, // This means an error occurred
"m":"KillBot session does not exist kbSessionID=255483105" // Error message
}
Sample HTML code showing how the KillBot API works
Here is a page with code that sends browser data to the server and receives the verification result: https://killbot.ru/snpsht.html
Check the code on this page, copy it for your own use, and create your own applications based on it.