CreataCaptcha Documentation

Our WordPress plugin is built with extendibility in mind. We are constantly adding more means for developers to utilize built-in features or modify the existing logic in a way that suits their needs.

This page covers both simple and advanced topics and is worth checking out even if you are not an experienced web developer. Most common and user-friendly methods of integrating CreataCaptcha into your project are listed first for convenience.

Last edit: May 14th, 2024

1. Common Integrations

For a quick integration with the built-in WordPress forms and pages, visit the plugin's Integrations page. You can find it in your website's admin dashboard, as part of the sidebar menu.

1.1. Native Forms (login and comments)

On the top of the Integrations page, there are two dropdown settings that each allow the selection of an existing CreataCaptcha Image Group.

1.2. Posts, Pages, and other public URLs

Any public post type can be protected in two steps.

First, make sure to enable the checkbox you need on the Integrations page.

Then, visit the desired entry's edit screen and enable protection using the dropdown.

Result:
https://creatacaptcha.com/sample-page/

1.3. 3rd-party plugins

CreataCaptcha can be used on forms created by popular plugins and themes.
Simply navigate to the form settings and look for the CreataCaptcha Image Group select field.
A list of supported integrations is available below.

  • Contact Form 7

    Look for the dropdown field on each form's edit screen.

    Contact Form 7 Integration

  • Gravity Forms

    Each form's settings screen will show a new dropdown field.



  • WPForms

    The CreataCaptcha dropdown field can be found in each form's Spam Protection and Security tab.

2. Custom integrations

2.1. HTML trigger

Each CreataCaptcha Image Group can be triggered by clicking on an element with a special id attribute format. This method is suitable for various use cases and unique integrations.

For example, if the desired Image Group's id is 486, website visitors can trigger it by clicking on an element with id="cc-triggger-486".

Code:

<a class="wp-element-button" href="#" id="cc-trigger-486">👉 Find the Beer</a>

Result:

👉 Find the Beer

Each Image Group's id can be found by looking at the URL of its edit screen:

By itself, the HTML trigger is abstract and doesn't result in anything. You will likely want to handle the results using the JavaScript events mentioned below.

2.2. JavaScript events

There are currently four front-end events triggered by the CreataCaptcha modal:

creatacaptcha-verified
Fired on successful verification (the visitor has selected the correct images and clicked on the "VERIFY" button).
The "formId" data parameter is passed to the callback function.

creatacaptcha-incorrect
Fired on incorrect submission (the visitor has selected incorrect images and clicked on the "VERIFY" button).
The raw HTML that will replace the modal's footer is passed to the callback function.

creatacaptcha-lockout
Fired on visitor being locked out (after submitting X incorrect answers, as configured in the plugin's settings page).
The raw HTML that will replace the modal's content is passed to the callback function.

creatacaptcha-hidden
Fired on closing the modal (either by clicking outside of it or by the default callback of the creatacaptcha-verified event).
No extra data is available.

2.3. PHP hooks

The current version of CreataCaptcha makes use of the following:

creatacaptcha_get_image_groups
Filters the output of the get_image_groups() function, which is responsible for fetching the list of available Image Group entries shown on various dropdown fields.
Parameters:
$image_groups - array of post objects

creatacaptcha_render_captcha
Filters the output of the render_captcha() function, which is responsible for generating the HTML of the CreataCaptcha modal.
Parameters:
$form_markup - string, HTML to be shown on the front-end
$images - array of arrays, each with data about the displayed images
$question - string, the question as entered in the Image Group
$incorrect_message - string, the incorrect message that should be displayed

creatacaptcha_render_lockout
Filters the output of the render_lockout() function, which is responsible for generating the modal's HTML for locked out visitors.
Parameters:
$lockout_html - string, HTML to be shown on the front-end
$pending - string, human-readable remaining lockout time
$lockout_message - string, the lockout message that should be displayed

creatacaptcha_render_blacklist
Filters the output of the render_blackout() function, which is responsible for generating the modal contents for blacklisted visitors.
Parameters:
$blacklist_html - string, HTML to be shown on the front-end

creatacaptcha_get_blacklisted_ips
Filters the output of the get_blacklisted_ips() function, which is responsible for fetching a list of IP addresses that are blacklisted.
Parameters:
$blacklisted_ips - array, IP addresses

creatacaptcha_get_whitelisted_ips
Filters the output of the get_whitelisted_ips() function, which is responsible for fetching a list of IP addresses that are whitelisted.
Parameters:
$whitelisted_ips - array, IP addresses

creatacaptcha_verification_result
Filters the outcome of each attempt to solve the CreataCaptcha modal.
Parameters:
$is_correct - bool, whether the submission should be treated as correct
$group_id - int, the post_id of the requested Image Group
$correct_choices - array of attachment ids marked as correct
$submitted_choices - array of attachment ids submitted by the visitor

creatacaptcha_print_assets
Action fired after printing the assets on protected posts and pages.
Parameters:
$integration - string, the slug of the script to be loaded