To use POWER CAPTCHA, your website does not need to meet any special requirements. The application is compatible with all systems that can communicate with external interfaces. By default, it is a cloud solution, which means that we host the application on our servers. If you integrate POWER CAPTCHA into your website, your website interacts with the AI on our server, and we can protect your website. To install the application, you must first secure a license. With your license, you will automatically receive an API key to access our interfaces. You can then integrate POWER CAPTCHA into your website in several ways: If you use WordPress, simply download our WordPress plugin and follow our installation instructions. You do not need any programming skills. You can also integrate POWER CAPTCHA via JavaScript on your website/application and verify the token on the server e.g. with PHP or Java. You can also use our templates for this.
When you purchase a license, you automatically get a customer account on our website. If you want to configure POWER CAPTCHA for your needs (Professional and Enterprise plans), you can do it in your account settings. Alternatively, you can start with our default settings.
Below you will find our step-by-step instructions for installation with WordPress and JavaScript as well as instructions for token verification with PHP or via the Verifiy interface. You can use them directly and customize them for your needs.
Want to know how exactly your website communicates with our server? Learn more in our free whitepaper!
How to install the WordPress plugin
To install the WordPress plugin, first download the plugin as a ZIP file in our customer area. Then go to the administration area / dashboard of WordPress and click on the menu item Plugins > Install. Click on the button “Upload Plugin” and select the ZIP archive you have downloaded from our website. Then click on “Install now”. After the upload and installation, a page will open where you can activate our POWER CAPTCHA plugin.
After you have activated the plugin, you can configure it. To do this, go to Settings > POWER CAPTCHA in the administration area of WordPress and enter your API and Secret key in the corresponding fields under “General settings”. You can get both keys in the customer area of our website. Under “Integration settings” you can select for which plugin or page area you want to activate POWER CAPTCHA.
The item “Enterprise settings” is only relevant if you use an Enterprise license and operate a local POWER CAPTCHA instance (instead of using the application as a cloud solution (standard)). In this case you have the option to enter the URLs to your locally hosted instance and to your local JavaScript. Then all requests will go to your own instance instead of our server. If you don’t run your own instance, all fields under “Enterpise settings” need to remain empty. When all settings are edited, click on “Save changes”. The selected plugins / areas are now protected with POWER CAPTCHA.
Status: June 2023, subject to change.
POWER CAPTCHA frontend integration with HTML
To integrate POWER CAPTCHA in the frontend with HTML, first include our JavaScript in the <head> element:
<script src="https://cdn.power-captcha.com/v1/power-captcha-1.1.0.min.js" type="text/javascript" defer></script>
Add the attributes data-pc-sitekey=”yourSiteKey” and data-pc-client-uid=”uniqueClientId” to the form you want to protect. The unique client ID can be based on the client’s IP address, for example. It is important that the client can be uniquely identified via the ID and that the same client ID is passed for token verification. Example:
<form method="post" action="submit.php"
data-pc-sitekey="5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs"
data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>">
...
</form>
If you have an Enterprise license, you can add the data-pc-user attribute to the input field with the user name / email address for additional protection. Example:
<input name="username" type="text" data-pc-user />
A login form protected with POWER CAPTCHA might look like this:
<form method="post" action="submit.php"
data-pc-sitekey="5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs"
data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>"
>
<label for="username">Username:</label><br />
<input type="text" id="username" name="username" data-pc-user /><br />
<label for="password">Password:</label><br />
<input type="password" id="password" name="password" />
<input type="submit" value="submit" />
</form>
When submitting the form, the request is checked by our POWER CAPTCHA API and a field with a token is added to the form. Afterwards you have to check/verify the token in the backend.
As a default, a POWER CAPTCHA badge (logo) is displayed on the protected form. There are three different badge types that can be controlled via the data-pc-badge-type attribute. You can assign numbers from 0 to 3 to the attribute. Each number represents a specific badge type:
| Badge type | Description |
|---|---|
|
data-pc-badge-type="0" |
Badge is hidden |
|
data-pc-badge-type="1" |
Small badge |
|
data-pc-badge-type="2" |
Large badge |
|
data-pc-badge-type="3" |
Floating badge on the left side of the window |
The attribute data-pc-badge-target controls the positioning of the badge. It accepts a CSS selector as its value. The badge is inserted before the element that is found by the specified CSS selector. Otherwise, the badge is positioned at the end of the form. Below is an example of how you can integrate the “floating” badge at the height of the submit button:
<form method="post" action="submit.php"
data-pc-sitekey="5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs"
data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>"
data-pc-badge-type="3"
data-pc-badge-target="input[type='submit']"
>
...
<input type="submit" value="submit" />
</form>
If the form is further processed via JavaScript (e.g. using AJAX), a callback function can be specified in the data-pc-callback attribute. Example:
<form id="customForm"
data-pc-sitekey="5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs"
data-pc-client-uid="<?php echo hash('sha256', $_SERVER['REMOTE_ADDR']); ?>"
data-pc-callback="customSubmit">
...
</form>
The callback function must be defined in the JavaScript and is called automatically after the request has been successfully checked by the POWER CAPTCHA API. Here is sample code for a callback function that submits the form via jQuery and AJAX:
const customForm = jQuery("#customForm");
const tokenField = jQuery(customForm).find("input[name='pc-token']");
function customSubmit(token) {
jQuery.ajax({
type: "POST",
url: "ajaxSubmit.php",
data: customForm.serialize()
})
.done((data) => {
// success
console.log({data});
})
.fail((error) {
// error
console.error(error);
})
.always(() => {
// clear the token field in case a new submit should be allowed.
tokenField.val("");
});
}
In the context of the callback example, the token has to be checked / verified in “ajaxSubmit.php” (see below).
How to verify the POWER CAPTCHA token on your server
Before you evaluate or save the content of your form in the backend, you should verify the POWER CAPTCHA token.
To do this, the token from the form ($_POST[“pc-token”]) and your secret key must be passed to our interface https://api.power-captcha.com/pcu/v1/verify as JSON, and in the header your sitekey must be present in the X-API-Key field.
The interface will return a JSON and the “success” field will say if the token was successfully verified. Afterwards you can evaluate your form as usual.
Here is a sample code how you can verify a token with PHP:
<?php
if(isset($_POST['pc-token']) && !empty($_POST['pc-token'])) {
$curl = curl_init('https://api.power-captcha.com/pcu/v1/verify');
curl_setopt($curl, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($curl, CURLOPT_POST, TRUE);
curl_setopt($curl, CURLOPT_HTTPHEADER, array(
'X-API-Key: 5gVoymQWRcyRQyJUxEqSdodfsK9vJJJs', // your api key
'Content-Type: application/json'
));
curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode(array(
'secret' => 'q5jBZojDfaQFzPGyhmAEFgz6C5j3NsjJ', // your secret key
'token' => $_POST['pc-token'],
'clientUid' => hash('sha256', $_SERVER['REMOTE_ADDR']), // unique client id (same value as in the data-client-uid attribute)
'name' => $_POST['username'] // field which was marked by 'data-pc-user' (optional)
)));
$response = json_decode(curl_exec($curl));
curl_close($curl);
if($response->success) {
echo "Token was successfully verified.";
// add your form logic
} else {
echo "Error: Token verfification failed.";
}
} else {
echo "Error: Token was missing in POST request.";
}
?>
API interface for token verification
After you submit your form, the token needs to be verified in your backend. To do this, you pass the token and some additional parameters via JSON to our Verifiy interface so that we can check if the captcha was solved correctly or if the alternative email authentication had a positive result. The Verifiy interface is called via the following URL: https://api.power-captcha.com/pcu/v1/verifiy.
In the header, the X-API-Key value must be set with your API key when called, and in the request body, the token and additional parameters must be POSTed to our interface as JSON.
{
"secret": "{secret-key}",
"token": "{token}",
"clientUid": "{client-uid}",
"name": "{username}"
}
Add your secret key in the parameter “secret”. You can find your secret key in your account. The parameter “token” contains the token which was generated by our JavaScript. The token can be found in the POST/GET field “pc-token”. The “clientUid” parameter must contain the same unique client ID that has been assigned in the form. It is used to check whether the token was originally created for this client ID. If you have marked a field with “data-pc-user” in the frontend, you have to pass the value of this field in the parameter “name” to our verifiy interface to protect a username / email address.
{
"success": true,
"errors": []
}
If the “success” field is set to “true”, then the verification was successful (token is valid) and you can continue with the evaluation of your form. If the “success” field is set to “false”, then the token is either invalid or the request is structured incorrectly. In this case the evaluation of the form should be stopped immediately, because the token could not be verified by POWER CAPTCHA. If the request is structured incorrectly, a list with the following error codes is returned in the “errors” field:
| Error Code | Description |
|---|---|
|
missing_token |
No token or an empty token was provided with the request. |
|
missing_secret |
No secret key was supplied with the request. |
|
invalid_secret |
The secret key is invalid or does not match the API key. |
|
invalid_token |
The token is invalid. |
Test now!
You want to test POWER CAPTCHA live? Start our demo and simulate the application on your website / app.
POWER CAPTCHA
About Us
Contact
© 2024 POWER CAPTCHA by Uniique AG – Alle Rechte vorbehalten | All Rights Reserved
