Описание метода API CleanTalk Anti-Spam "check_bot"

Этот метод лучше всего подходит для фильтрации ботов во время простого просмотра страницы. Просто запустите его в фоновом режиме и заблокируйте любую страницу/сообщение, если облако вернет коэффициент бота (разрешить = 0). Размещайте пример в любое удобное для вас время, код не прерывает посетителей и не влияет на их общение.

1. Соберите данные с веб-формы.
2. Отправьте данные JSON через запрос POST на https://moderate.cleantalk.org/api2.0
3. Проанализируйте ответ и примите решение.
4. Этот метод работает в сочетании с методом frontend_data. Метод frontend_data должен использоваться путем включения следующего файла javascript в код сайта.
   

   <script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js"></script>

Запрос

Пример данных JSON

{
    "method_name":"check_bot",
    "auth_key":"your_acccess_key",
    "message_to_log":"some useful text you can see in the log",
    "event_token":"sha_256_string_of_event_token",
    "agent":"your_super_user_agent v.1.77",
    "event_type":"GENERAL_BOT_CHECK"|"CONTACT_DECODING",
    "event_javascript_data":"",
    "browser_sign":"",
    "sender_ip":"127.0.0.1",
    "page_url":"https://your-great-site.com/page1",
    "sender_info": {
        "REFERRER": "https:/referrer-site.com",
        "USER_AGENT": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/77.0.3835.0 Safari/537.36"
    }
}

Обработка данных

Необходимая информация об обработке данных.

Обязательные параметры

Данные параметры обязательны.

Дополнительные параметры

Эти параметры улучшат фильтрацию.

Ответ

Пример ответа

Ответ сервера на зависит от платформы.

{
	"allow" : 1,
	"bot_expectation" : "0.2",
	"ip_frequency_10min" : 2,
    "ip_frequency_1hour" : 0,
    "ip_frequency_24hour" : 0,
	"comment" : "Allowed",
}

Объяснение ответа

Примеры кода

Используя Wget

Пример CLI 

wget -O- --post-data='{"method_name":"check_bot","auth_key":"your_acccess_key","sender_ip":"127.0.0.1"}' https://moderate.cleantalk.org/api2.0

Используя PHP

PHP бакенд

Скачайте библиотеку CleanTalk отсюда. Путь к папке библиотеки должен совпадать с путем к файлу PHP. Кроме того, вы можете установить библиотеку с помощью Composer.

Структура файлов:

CheckBot
    CheckBot.php
    CheckBotConfig.php
lib
    Cleantalk.php
    cleantalk-php-patch.php
    CleantalkAntispam.php
    CleantalkAPI.php
    CleantalkHelper.php
    CleantalkRequest.php
    CleantalkResponse.php
    CleantalkResponse.php
    TransportException.php
search_form_with_check_bot.php
searchform.html

Файл search_form_with_check_bot.php

                                

                                    
                                    Copy link
                                    
                                    
                                    Copy code
                                
                               <?php

require_once(dirname(__FILE__) . '/lib/Cleantalk.php');
require_once(dirname(__FILE__) . '/lib/CleantalkRequest.php');
require_once(dirname(__FILE__) . '/lib/CleantalkResponse.php');
require_once(dirname(__FILE__) . '/lib/CleantalkHelper.php');
require_once(dirname(__FILE__) . '/CheckBot/CheckBot.php');
require_once(dirname(__FILE__) . '/CheckBot/CheckBotConfig.php');

if ( empty($_POST) ) {
    return;
} else {
    $post = $_POST;
}

handle_search_form($post);

/**
 * Main search from handler.
 * @param $post
 * @return void
 * @throws Exception
 */
function handle_search_form($post)
{
    if ( empty($post['search_field']) ) {
        return;
    }

    // set new CheckBotConfig
    $config = new CheckBotConfig(
        array(
            /*
             * Your CleanTalk access key. This example get the key from the system environment,
             * you can use your onw way or insert key string directly.
             */
            'access_key' => getenv("CLEANTALK_TEST_API_KEY"),
            /*
             * Set this to true if you trust CleanTalk decision and do not want
             * to perform additional custom checks
             */
            'trust_cleantalk_decision' => false,
            /*
             * Message for blocked visitor
             */
            'common_block_message' => 'Visitor blocked. It seems to be a bot.',

            /**
             * Attention! Settings below affected only if the property "trust_cleantalk_decision
             * is set to false.
             */

            /*
             * Custom check - set maximum bot probability percentage. For example, 0.5 is 50%.
             * If CleanTalk API responsed
 with bot_expectation 0.53 - visitor will be blocked,
             * if 0.47 - passed.
             */
            'bot_expectation' => 0.5,
            /*
             * Custom checks - set how to block a visitor whose IP address detected by CleanTalk
             * service in the period. For example, if CleanTalk response contains
             * ip_frequency_24hour = 1000, and the config property ip_frequency_24hour = 500,
             * visitor will be blocked.
             */
            'ip_frequency_24hour' => 50,
            'ip_frequency_1hour' => 15,
            'ip_frequency_10min' => 5,
            /*
             * Set to true if you want to see the log, false otherwise.
             */
            'do_log' => true
        )
    );
    $bot_checker = new CheckBot($post, $config);

    //call visitor check
    $is_bot = $bot_checker->check()->getVerdict();
    if ( $is_bot ) {
        die ($bot_checker->getBlockMessage());
    }

    //implement your search form handler here replacing echo
    echo('You searched for this: ' . $post['search_field']);
}

Класс CheckBot/CheckBot.php

                                

                                    
                                    Copy link
                                    
                                    
                                    Copy code
                                
                               <?php

use Cleantalk\Cleantalk;
use Cleantalk\CleantalkRequest;
use Cleantalk\CleantalkResponse;

class CheckBot
{
    /**
     * Configuration obj.
     * @var CheckBotConfig
     */
    private $config;
    /**
     * $_POST
     * @var array
     */
    private $post;
    /**
     * Bot detector JS library event token
     * @var string
     */
    private $event_token;
    /**
     * CheckBot final verdict. True if visitor is bot.
     * @var bool
     */
    private $verdict = false;
    /**
     * The message for blocked visitor.
     * @var string
     */
    private $block_message = '';

    public function __construct(array $post_data, CheckBotConfig $config)
    {
        $this->post = $post_data;
        $this->config = $config;
    }

    /**
     * Get Bot-Detector event token form POST data.
     * @return string
     */
    private function getEventToken()
    {
        $event_token = isset($this->post['ct_bot_detector_event_token'])
            ? $this->post['ct_bot_detector_event_token']
            : '';
        if ( $event_token && is_string($event_token) && strlen($event_token) === 64 ) {
            return $event_token;
        }
        return '';
    }

    private function setEventToken($event_token)
    {
        $this->event_token = $event_token;
    }

    /**
     * Call check_bot CleanTalk API method. Return false on failure, CleantalkResponse obj on succes.
     * @return CleantalkResponse|false
     */
    private function checkBotApiCall()
    {

        $ct_request = new CleantalkRequest();
        $ct_request->event_token = $this->event_token;
        $ct_request->auth_key = $this->config->access_key;

        if ( empty($ct_request->auth_key) ) {
            $this->writeLog('CleanTalk check_bot: access key is empty. Check skipped.');
            return false;
        }

        if ( empty($ct_request->event_token) ) {
            $this->writeLog('CleanTalk check_bot: event token not found. Check skipped.');
            return false;
        }

        $ct = new Cleantalk();
        $ct->server_url = $ct_request::CLEANTALK_API_URL;
        $ct_result = $ct->checkBot($ct_request);
        $this->writeLog('CleanTalk check_bot result: ' . var_export($ct_result, true));

        return $ct_result;
    }

    public function getVerdict()
    {
        return $this->verdict;
    }

    public function getBlockMessage()
    {
        return $this->block_message;
    }

    /**
     * Makes decision if visitor is bot using CleanTalk libraries, exactly check_bot method.
     * @return CheckBot
     */
    public function check()
    {
        //get event token
        $this->setEventToken($this->getEventToken());
        //call CleanTalk API
        $check_bot_result = $this->checkBotApiCall();

        //handle response
        if ( false === $check_bot_result ) {
            $this->verdict = false;
            return $this;
        }

        if (!empty($check_bot_result->errstr)) {
            $this->writeLog('CleanTalk check_bot failed. Check method call parameters. Error: ' . $check_bot_result->errstr);
            $this->verdict = false;
            return $this;
        }

        $this->block_message = !empty($this->config->common_block_message)
            ? $this->config->common_block_message
            : $check_bot_result->comment;

        //block if CleanTalk decision is enough for you
        if ( $this->config->trust_cleantalk_decision ) {
            $this->verdict = isset($check_bot_result->allow) && $check_bot_result->allow != 1;
            $this->writeLog('CleanTalk check_bot: visitor blocked on CleanTalk decision.');
            return $this;
        }

        //run custom checks for response properties
        foreach ( $this->config->custom_checks_properties as $property ) {
            if ( $check_bot_result->$property > $this->config->$property ) {
                $this->verdict = true;
                $this->writeLog('CleanTalk check_bot: visitor blocked by custom setting: ' . $property . ' > ' . $this->config->$property);
                return $this;
            }
        }

        return $this;
    }

    /**
     * Writes log in PHP error log.
     * @param $msg
     * @return void
     */
    private function writeLog($msg)
    {
        if ( $this->config->do_log && is_string($msg) && !empty($msg)) {
            error_log($msg);
        }
    }
}

Класс CheckBot/CheckBotConfig.php

                                

                                    
                                    Copy link
                                    
                                    
                                    Copy code
                                
                               <?php

class CheckBotConfig
{
    private $obligatory_properties = array('access_key',
        'trust_cleantalk_decision',
    );

    public $custom_checks_properties = array('bot_expectation',
        'ip_frequency_24hour',
        'ip_frequency_1hour',
        'ip_frequency_10min',
    );

    public $access_key = '';
    public $trust_cleantalk_decision = true;
    public $common_block_message = 'Visitor blocked. It seems to be a bot.';
    public $do_log = true;
    public $bot_expectation = 0.5;
    public $ip_frequency_24hour = 50;
    public $ip_frequency_1hour = 15;
    public $ip_frequency_10min = 5;

    public function __construct($params)
    {
        if ( !$this->isObligatoryParamsPresented($params) ) {
            throw new \Exception('CheckBot config: not enough params set.');
        }
        foreach ( $params as $param_name => $param ) {
            if ( property_exists(static::class, $param_name) ) {
                $type = gettype($this->$param_name);
                $this->$param_name = $param;
                settype($this->$param_name, $type);
            }
        }
    }

    public function __get($name)
    {
        return property_exists(static::class, $name) ? $this->$name : null;
    }

    private function isObligatoryParamsPresented($params)
    {
        return empty($this->obligatory_properties) ||
            count(array_intersect($this->obligatory_properties, array_keys($params))) === count(
                $this->obligatory_properties
            );
    }
}

HTML фронтенд

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>Title</title>
    <script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js"></script>
</head>
<body>
<form method="post" action="check_bot.php">
    <label for="search_field">What do you search?</label>
    <input type="text" name="search_field" id="search_field" /> <br />
    <input type="submit" />
</form>
</body>
</html>

Больше информации можно найти на нашем GitHub.