https://github.com/cleantalk/cleantalk-api-docs-check-bot-example
https://github.com/cleantalk/cleantalk-api-docs-check-bot-example
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/cleantalk/cleantalk-api-docs-check-bot-example
- Owner: CleanTalk
- Created: 2024-01-15T05:26:54.000Z (about 2 years ago)
- Default Branch: master
- Last Pushed: 2024-03-28T11:59:04.000Z (almost 2 years ago)
- Last Synced: 2024-11-24T18:08:52.397Z (about 1 year ago)
- Language: PHP
- Size: 48.8 KB
- Stars: 4
- Watchers: 3
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.MD
Awesome Lists containing this project
README
This guideline will help you to use CleanTalk check_bot API method via the special library that can be downloaded from this repo.
## Usage
1. Download the lib and unpack it to your website filesystem. Look at the suggested files structure with unpacked data highlighted:
2. Add the CleanTalk Bot-detector JS library wrapper `https://moderate.cleantalk.org/ct-bot-detector-wrapper.js` as ``tag to the HTML page contains the form you want to protect.
```html
<script src="https://moderate.cleantalk.org/ct-bot-detector-wrapper.js">
```
3. Fill the [config.php](src%2FCleantalk%2Fconfig.php).
```php
src/FCleantalk/config.php
```
Obligatory properties are:
* access_key - your CleanTalk Anti-Spam access key. If you do not have a key, [register the new account](https://cleantalk.org/register?utm_source=github&utm_medium=article&utm_campaign=instructions&utm_content=link&utm_term=create+account) or [access dashboard](https://cleantalk.org/my?utm_source=github&utm_medium=referral&utm_campaign=bot_detector&utm_content=link&utm_term=dashboard) to an existing account to get it.
* trust_cleantalk_decision - set this to true if you do not want to set custom checking settings
4. To start use CheckBot library, include "yourpath/src/autoloader.php" into the top of codepage where you want to perform the check.
```php
require_once 'yourpath/src/autoloader.php';
```
5. Then create a new CleanTalk\CheckBot object, provide $_POST or filtered POST data to the constructor.
```php
$bot_checker = new \Cleantalk\CheckBot($_POST);
```
6. Then perform the check:
```php
$is_bot = $bot_checker->check()->getVerdict();
```
7. Then do the actions depending on the verdict.
```php
if ( $is_bot ) {
die ($bot_checker->getBlockMessage());
}
```
8. How it looks in the suggested files structure:
- `index.html`:
```html
Title
What do you search?
```
- `your_form_handler.php`:
```php
check()->getVerdict();
if ( $is_bot ) {
die ($bot_checker->getBlockMessage());
}
//implement your further search form handlers here replacing echo
echo('You searched for this: ' . $post['search_field']);
}
```
## Config setup explanation
### Default config.php
```php
"",
'trust_cleantalk_decision' => true,
'block_no_js_visitors' => true,
'common_block_message' => 'Visitor blocked. It seems to be a bot.',
'bot_expectation' => 0.5,
'ip_frequency_24hour' => 50,
'ip_frequency_1hour' => 15,
'ip_frequency_10min' => 5,
'do_log' => false
);
```
### Common params
- `access_key (string)`
Your CleanTalk Anti-Spam access key.
- `trust_cleantalk_decision (bool)`
Set this to true if you do not want to set custom checking settings. Applicable in the most cases.
- `block_no_js_visitors (bool)`
Set this to true if you want to block any visitor that could not execute JS script (bot-like behavior). Applicable in the most cases.
- `common_block_message (string)`
A message for blocked visitor.
- `do_log (bool)`
Set to true if you want to see the log in the PHP error log, false otherwise.
### Custom params
Params below affected only if the property "trust_cleantalk_decision is set to false.
- `bot_expectation`
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.
- `ip_frequency_24hour`,`ip_frequency_1hour`,`ip_frequency_10min`
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.
## How to test
1. Disable JavaScript implementation in your web-browser. If the param `trust_cleantalk_decision` is set to `true`, you are blocked when you try to send the form.
2. Install the solution on a dev site with visiting opened. Then set the param `do_log` to `true`. You will see how the CheckBot works in the PHP error log.
## Examples
Examples of the form with CheckBot integrated can be found in the `/examples` folder. Note: the examples does not contain the lib itself.