KillBot предоставляет несколько АПИ, которые можно использовать:
- Для интеграции KillBot в свой сервис через кнопку: https://killbot.ru/node/48
- Для создания своего продукта с поддержкой алгоритмов KillBot: https://killbot.ru/API-partner
- Простое JS АПИ для программного получения информации кому принадлежит визит: пользователю или боту, описание - ниже.
АПИ для коммерческого использования (Тариф АПИ):
А если вы хотите интегрировать именно алгоритмы выявления ботов в своё решение, то используйте АПИ ниже. По АПИ можно запрашивать расширенные данные (пример: https://killbot.ru/waf/myUserID)
Идея
Подключение антифрода KillBot по АПИ осуществляется размещением JS кода на сайте. Этот код собирает и отправляет браузерные данные на сервер. Результат проверки нужно забирать отдельным запросом к серверу с передачей номера сессии.
Для сбора данных нужно подключить скрипт https://data.killbot.ru/js/cn.js - этот скрипт отправит данные на сервер 4-мя запросам с общим объемом отправляемых данных 5-15Kb.
Скрипт KillBot не собирает персональных данных, не собирает данные ввода форм, не запрашивает доступ к микрофону, локации, видеокамере и другим де-идентифицирующим объектам.
Получение результата проверки и сопутствующих данных осуществляется запросом на сервер https://data.killbot.ru/r/get.php или по ивенту kbDataReceived.
Подключение скрипта отправки данных c.js
Ниже демонстрируется пример кода на JS, инициализирующий отправку данных на сервер KillBot.
const kbKey = "Stitjtzrjo"; /* Нужно получить в личном кабинете KillBot - находится в первой строчке кода для размещения на сайте. */
let kbUserID = Math.floor(Math.random()*900000000); // ID пользователя, сохраняется в базе данных KillBot, можно сохранять как долгожитвущую куку, тип - MySQL BigInt
let kbSessionID = Math.floor(Math.random()*900000000); //ID сессии, сохраняется в базе данных KillBot, можно сохранять как куку с коротким временем жихни, тип - MySQL BigInt
var kbB = null; //Эта переменная здесь не используется, но без неё скрипт выдаст ошибку. Пусть пока остаётся, в следующих версиях исправим.
try{
//Подключаем скрипт c.js который собирает и отправляет браузерные данные на сервер
var kbTS = document.createElement("script");
kbTS.type = "text/javascript";
kbTS.async = true;
kbTS.src = "https://data.killbot.ru/js/cn.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);
}
Пример 1 получения результата проверки на JS
Когда данные проверки на бота получены, то скрипт килбота cn.js генерирует событие kbDataReceived, т.е. нужно слушать когда придет событие и просто забрать данные:
document.addEventListener("kbDataReceived", function(event) {
if (kbRes != null) return;
try {
if (event.detail){
kbRes = JSON.parse(event.detail);
}
} catch (error) {
kbRes = null;
}
//Обрабатываем данные от килбота kbRes
});
Может быть, что ивент может не сработать (боты могут вырезать JS - если он подключен через файл, например), для этого сгенерируем ивент по таймауту:
setTimeout(function() {
if (kbRes != null) return;
// или тут можно попробовать запросить данные через get запрос - как написано в следующем пункте: xhr.open('GET', 'https://data.killbot.ru/r/get.php?waf=1&c='+kbSessionID, true);
// или отправить сообщение таймаут без данных, как ниже
const event = new CustomEvent("kbDataReceived", {
detail: JSON.stringify({
error: true,
m: "timeout"
})
});
document.dispatchEvent(event);
}, 2 * kbSliderTimeout);
Пример 2 получения результата проверки на JS
Результат проверки нужно получать GET запросом с передачей параметра сессии, пример запроса: https://data.killbot.ru/r/get.php?waf=1&c={{kbSessionID}}
Результат проверки можно получать средствами JS или на бекенде. При получении результата проверки средствами JS помните, что бот может имитировать наш сервер фейковым, поэтому, для надёжности, результирующий ответ можно получать и на бекенде. Ниже пример получения результата проверки на JS: если данные не получены, то скрипт делает запрос на сервер ещё раз.
const kbTimeout = 2000; /* период через который делать запрос на сервер для получения результата. */
const kbMaxRequests = 10; /* максимальное число запросов на сервер чтобы забрать результат. */
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?waf=1&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){
//Действия при успешном получении данных от сервера KillBot
}
function fail(){
//Действия на ошибку, когда данные не получены
}
Пример ответа cервера response на запрос https://data.killbot.ru/r/get.php :
{
"bot":false, //Результат проверки на бота по всей логике скрипта, выставелнной в настройках скрипта KillBot, fraud.true - то это бот
"fraud":false, //То же самое что и параметр bot, если bot.true - то это бот
"l":true, //Прогружен скрипт полностью или нет. Простые боты могут не прогружать скрипт полностью, так как они оптимизируют время своей работы. Но из-за интернет соединения в некоторых случаях для реального пользователя скрипт так же может не прогрузится. l.true - значит скрипn прогружен польностью без ошибок
"d":false, //Параметр из настроек скрипта: запретить заход или нет. Если d.true, то для этого визита нужно запретить заход на сайт
"snsht":2969538378, //Слепок браузера основной
"snsht_d":34562346, //Слепок браузера детализированный
"net_id":2696850341, //Идентификатор сети
"ua":"Chrome", //Браузер витзита, для информации - берётся из user-agent
"sess":"45786830545786830", //Номер сессии: kbSessionID
"UserID":"468073784468073784", //ID пользователя: kbUserID
"capt":false, //Параметр из настроек скрипта: показать капчу или нет. Если capt.true, то для этого визита нужно запретить показать капчу
"bl":false, //Есть ли слепок браузера snsht в группе известных ботов.
"wl":true, //Есть ли слепок браузера snsht в группе известных браузеров.
"ip":"51.158.237.65", //ip с которого произошел визит
"sc":true, //Системный параметр для внутреннего использования в KillBot - он не нужен
"t":true, //Показать или скрыть метрику, если t.true - значит показать метрику - иначе код метрики загружать не нужно
"utm":"bot" //Параметр из настроек скрипта: название http параметра в который нужно поместить результат проверки на бота.
"url": ""; //Параметр из настроек скрипта: url страницы на который нужно совершить редирект для этого визита
"waf": - дополнительные параметры WAF - структура показана ниже.
}
WAF данные - с их помощью можно создавать правила фильтрации:
killbot:
UserID: 429434077125846125 // Уникальный идентификатор пользователя (не зависит от куки)
bot: false // Визит от бота или нет? (true/false)
capt: false // Была ли показана капча (факт показа, а не решения капчи)
deny: false
vpn: true // Доступен ли заблокированный роскомнадзором сайт из твоей сети (true — да, false — нет)
snsht: 65519223 // Слепок браузера
snsht_det: 2467088659 // Детальный слепок браузера
net_id: 3957945795 // Идентифкатор сети
net_t: corp // Тип сети: corp — корпоративная (если есть открытые порты), mob — мобильная (если IP не пингуется), home — домашняя (если IP пингуется и нет открытых портов)
bl: false // Слепок браузера в черном списке (blacklist)
wl: true // Слепок браузера в белом списке (whitelist)
ffp: 3329686866 // Идентифкатор как именно у тебя отрисовываются щрифты (Фингерпринт шрифтов)
host: Faraday
adt: false // Используется ли технология антидетекта
tm: 2 // Время обработки запроса (сек)
user:
timezone: Asia/Novosibirsk // Часовой пояс пользователя
locale: en-US // Системный язык
net:
ip: 94.237.108.10 // IP-адрес пользователя
host: 94-237-108-10.nl-ams1.upcloud.host // Обратное DNS-имя (хостнейм, на какой домен резолвится IP)
asn: 202053 // ASN
country: FI // Страна по IP
ports: {"80":{"port":80,"ttl":52,"rtt":41}} // Открытые порты на IP-адресе
ping: true // IP пингуется (true/false)
ttlOS: Linux // ОС по TTL пакета
ttl: 54 // TTL (время жизни пакета)
ttl_b: 52
rtt: 93.25 // RTT (время отклика сети)
request:
user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/139.0.0.0 Safari/537.36 // User-Agent браузера
referer: // Реферер — с какого сайта пришли
accept-language: ru,zh;q=0.9,en;q=0.8,en-US;q=0.7 // Языки, поддерживаемые браузером
url: https://killbot.ru/adm/script/list/table // URL запроса
browser:
name: Chrome // Название браузера
language: ru // Язык, установленный в браузере
webdriver: false // Запущен ли браузер под програмным управлением (если true, то точно бот)
innerheight: 919 // Высота области просмотра (в пикселях)
innerwidth: 1920 // Ширина области просмотра (в пикселях)
outerheight: 1040
outerwidth: 1920
device:
width: 1920 // Ширина экрана (в пикселях)
height: 1080 // Высота экрана (в пикселях)
os: Windows // Операционная система устройства
gc: ANGLE (NVIDIA, NVIDIA GeForce GT 710 (0x0000128B) Direct3D11 vs_5_0 ps_5_0, D3D11) // Графический процессор (GPU)
В случае ошибки ответ response будет содержать поле error с текстом ошибки.
Пример ошибочного ответа:
{
"error_code":100, //Код ошибки. error_code=100: ID сессии (kbSessionID) не существует, error_code=200: любая другая ошибка - смотрите описание
"error":true, //это значит что произошла ошибка
"m":"KillBot session does not exist kbSessionID=255483105" //текст ошибки
}
Пример рабочего HTML кода с демонстрацией работы API KillBot.
Вот страница c кодом, который отправляет данные браузера на сервер и получает результат проверки: https://killbot.ru/snpsht.html
Смотрите код этой страницы, копируйте себе и на её основании создавайте свои приложения.