Resources

Plugins

C# ASP.NET
VB ASP.NET
PHP
ASP
WordPress Plugin
Joomla Plugin
Drupal Plugin
phpBB Plugin
Java
Python
Perl
DotNetNuke Plugin

AdsCaptcha API Overview

Welcome to our resources page! Here you'll find documentation and examples of how to embed an AdsCaptcha in your websites.
This documentation is designed for people who are familiar with HTML and server-side processing.

API keys

In order to add AdsCaptcha to your website, you'll need to get unique API keys.
Using the API keys, we identify your website on each CAPTCHA request/validation.
Sign up now for your API keys. It's FREE!

Getting started

Once you've got your API keys, all you have to do are simply two steps:
1. Display the AdsCaptcha on your form (client-side).
2. Validate the user's answer when form is being processed (server-side).

We offer a variety of plugins and code examples for different programming languages and platforms.
We recommend you check out our plugins before doing it yourself.

How the AdsCaptcha API works

The user loads your website form with the AdsCaptcha widget (JavaScript code).
The JavaScript code requests an AdsCaptcha challenge. The user is exposed to the AdsCaptcha.
The user fills out your website form (includes AdsCaptcha answer) and clicks submit.
Your server sends the user's answer to AdsCaptcha's servers, which checks the user's answer and sends back a response.
If correct, proceed with your process. If incorrect, display an error to the users and generate a new AdsCaptcha challenge.

Important connection issue

Make sure your server can establish a connection to AdsCaptcha's servers.
Some application servers define outbound firewall restriction which could cause connectivity faults.

Interesting CAPTCHA
CAPTCHA news

We offer a variety of plugins and code examples for different programming languages and platforms.
We recommend you check out our plugins before doing it yourself.

Display the CAPTCHA

Displaying AdsCaptcha on your website is extremely simple!
All you have to do is add this code in your <form> where you want it to be displayed.
Replace your_captcha_id and your_public_key with your API codes.
Replace random_dummy with a random number (generated in each load of your page).

<script type='text/javascript'
    src='http://api.adscaptcha.com/Get.aspx?CaptchaId=your_captcha_id&PublicKey=your_public_key&Dummy=random_dummy'></script>
<noscript>
    <iframe src='http://api.adscaptcha.com/NoScript.aspx?CaptchaId=your_captcha_id&PublicKey=your_public_key&Dummy=random_dummy'
        width='300' height='100' frameborder='0'></iframe>
    <table>
    <tr><td>Type challenge here:</td><td><input type='text' name='adscaptcha_response_field' value='' /></td></tr>
    <tr><td>Paste code here:</td><td><input type='text' name='adscaptcha_challenge_field' value='' /></td></tr>
    </table>
</noscript>

Error codes

Most likely, an error occurred when the API keys weren't set correctly.
Please check that you copied the exact key.
Make sure you didn't get confused between your public key and your private key.

Anyway, this is the full list of error codes:

Code	Description
captchaid-not-set	You didn't set your Captcha ID. Please set it.
captchaid-invalid	Your Captcha ID is invalid. Please check it again.
publickey-not-set	You didn't set your public key. Please set it.
publickey-invalid	Your public key is invalid. Please check it again.
publickey-not-exists	We couldn't verify your public key. Please check it again.
publickey-not-match-captchaid	Your Captcha ID and public key don't match. Please check them again.
unexpected-error	An unexpected error occured.

We offer a variety of plugins and code examples for different programming languages and platforms.
We recommend you check out our plugins before doing it yourself.

Validate the CAPTCHA

Validate your AdsCaptcha on your server-side processing by doing a POST request to our servers.

Send API request

URL: http://api.adscaptcha.com/Validate.aspx

Parameter	Description
CaptchaId	Your Captcha ID.
PrivateKey	Your private key.
ChallengeCode	Challenge code. The value of "adscaptcha_challenge_field" (form variable).
UserResponse	User's response. The value of "adscaptcha_response_field" (form variable).
RemoteAddress	User's IP address. Used for security reasons.

Get API response

The validation response is a string: "true" for correct answer and "false" for wrong answer.
Otherwise, most likely the request parameters didn't set correctly. Please check them out.

Anyway, this is list of response strings:

Return Value	Description
true	User's answer was correct.
false	User's answer was incorrect.
already-checked	CAPTCHA challenge already checked before.
captchaid-not-set	You didn't set your Captcha ID. Please set it.
captchaid-invalid	Your Captcha ID is invalid. Please check it again.
privatekey-not-set	You didn't set your private key. Please set it.
privatekey-invalid	Your private key is invalid. Please check it again.
challenge-not-set	You didn't send or we couldn't get the challenge code (POST field). Please set it.
challenge-invalid	Challenge code (POST field) is invalid.
response-not-set	You didn't send or we couldn't get user's response (POST field). Please set it.
response-invalid	User's response (POST field) is invalid.
remoteaddress-not-set	You didn't set the remote address. Remote address is needed for security reasons. Please set it.
remoteaddress-invalid	Remote address is invalid. Please check it. Required format: 0.0.0.0.
privatekey-not-exists	We couldn't verify your private key. Please check it again.
privatekey-not-match-captchaid	Your Captcha ID and private key don't match. Please check them again.
unexpected-error	An unexpected error occured.

Your API Keys

AdsCaptcha for C#/ASP.NET

AdsCaptcha C#/ASP.NET class

To use AdsCaptcha with C#/ASP.NET, download AdsCaptcha C#/ASP.NET class, just to make things easier for you.
Extract and save AdsCaptchaAPI.cs on your website directory.

In order to use the C#/ASP.NET class, you'll need to add the class in your project/solution.

Display your CAPTCHA

Now you're ready to display your CAPTCHA.
On your form page (.aspx), place a label where the AdsCaptcha will be displayed:

                                    <asp:Label ID="AdsCaptchaHolder" runat="server"></asp:Label>

On the server side (.aspx.cs), set your API keys and display the CAPTCHA:

int    CaptchaId  = your captcha id;    // Set your captcha id
string PublicKey  = "your public key";  // Set your public key
AdsCaptchaHolder.Text = AdsCaptchaAPI.CAPTCHA.GetCaptcha(CaptchaId, PublicKey);

Validate your CAPTCHA

On your validation process, place this code:

int    CaptchaId  = your captcha id;    // Set your captcha id
string PrivateKey = "your private key"; // Set your private key
string ChallengeCode = Request.Form["adscaptcha_challenge_field"].ToString();
string UserResponse = Request.Form["adscaptcha_response_field"].ToString();
string RemoteAddress = Request.ServerVariables["REMOTE_ADDR"];

string result = AdsCaptchaAPI.CAPTCHA.ValidateCaptcha(CaptchaId, PrivateKey, ChallengeCode, UserResponse, RemoteAddress);

if (result == "true")
{
    // Corrent answer, continue with your submission process
}
else
{
    // Wrong answer, you may display a new AdsCaptcha and add an error message 
}

Download C#/ASP.NET Class Download Example

AdsCaptcha for VB.NET

AdsCaptcha VB.NET class

To use AdsCaptcha with VB.NET, download AdsCaptcha VB.NET class, just to make things easier for you.
Extract and save AdsCaptchaAPI.vb on your website directory.

In order to use the VB.NET class, you'll need to add the class in your project/solution.

Display your CAPTCHA

Now you're ready to display your CAPTCHA.
On your form page (.aspx), place a label where the AdsCaptcha will be displayed:

<asp:Label ID="AdsCaptchaHolder" runat="server"></asp:Label>

On the server side (.aspx.vb), set your API keys and display the CAPTCHA:

Dim CaptchaId As Integer = your captcha id    ' Set your captcha id
Dim PublicKey As String  = "your public key"  ' Set your public key
AdsCaptchaHolder.Text = AdsCaptchaAPI.GetCaptcha(CaptchaId, PublicKey)

Validate your CAPTCHA

On your validation process, place this code:

Dim CaptchaId As Integer = your captcha id     ' Set your captcha id
Dim PrivateKey As String = "your private key"  ' Set your private key
Dim ChallengeCode As String = Request.Form("adscaptcha_challenge_field").ToString()
Dim UserResponse As String  = Request.Form("adscaptcha_response_field").ToString()
Dim RemoteAddress As String = Request.ServerVariables("REMOTE_ADDR")

Dim result As String = AdsCaptchaAPI.ValidateCaptcha(CaptchaId, PrivateKey, ChallengeCode, UserResponse, RemoteAddress)

If (result = "true") Then
    ' Corrent answer, continue with your submission process
Else
    ' Wrong answer, you may display a new AdsCaptcha and add an error message 
End If

Download VB.NET Class Download Example

AdsCaptcha for PHP

AdsCaptcha PHP library

To use AdsCaptcha with PHP, download AdsCaptcha PHP library, just to make things easier for you.
Extract and save adscaptchalib.php on your website directory.

In order to use the PHP library, you'll need to include the library in the page/s which use it:

<?php
require_once('adscaptchalib.php');
?>

Client Side - Display your CAPTCHA

Now you're ready to display your CAPTCHA.
Place this code inside your <form> where the AdsCaptcha will be placed:

$captchaId  = '';   // Set your captcha id here
$publicKey  = '';   // Set your public key here
echo GetCaptcha($captchaId, $publicKey);

Don't forget to set your Captcha ID and public key values.

Server Side - Validate your CAPTCHA

On your validation process, place this code:

$captchaId  = '';   // Set your captcha id here
$privateKey = '';   // Set your private key here
$challengeValue = $_POST['adscaptcha_challenge_field'];
$responseValue  = $_POST['adscaptcha_response_field'];
$remoteAddress  = $_SERVER["REMOTE_ADDR"];

if ("true" == ValidateCaptcha($captchaId, $privateKey, $challengeValue, $responseValue, $remoteAddress))
{
    // Corrent answer, continue with your submission process
} else {
    // Wrong answer, you may display a new AdsCaptcha and add an error message 
}

Troubleshooting

Q: Fatal error: require_once() [function.require]: Failed opening required 'adscaptchalib.php'
A: Make sure you set the currect path to the AdsCaptcha's library file.

Q: Fatal error: Call to undefined function mb_detect_encoding()
A: Make sure Multibyte String is installed and enabled in your PHP server.

Download PHP Library Download Example

AdsCaptcha for JAVA

AdsCaptcha JAVA library

To use AdsCaptcha with Java, download AdsCaptcha Java library, just to make things easier for you.
Unzip and put the adscaptcha.jar in the classpath of your web application. For example, if you are using Tomcat to run JSP, you may copy the jar file to the WEB-INF/lib/ directory.

In order to use the Java library, you'll need to import the AdsCaptcha classes. In JSP, add this line in the page where the AdsCaptcha will be displayed:

<@ page import="net.adscaptcha.AdsCaptchaAPI">

Client Side - Display your CAPTCHA

Now you're ready to display your AdsCaptcha.
Place this code inside your <form> where the AdsCaptcha will be placed:

final String captchaId  = "your_captcha_id";
final String publicKey  = "your_public_key";

AdsCaptchaAPI adscaptcha = new AdsCaptchaAPI();

out.print(adscaptcha.getCaptcha(captchaId, publicKey));

Don't forget to set your Captcha ID and Public Key values.

Server Side - Validate your CAPTCHA

On your validation process, place this code:

final String captchaId  = "your_captcha_id";
final String privateKey = "your_private_key";
final String challengeValue = request.getParameter("adscaptcha_challenge_field");
final String responseValue = request.getParameter("adscaptcha_response_field");		
final String remoteAddress = request.getRemoteAddr();

AdsCaptchaAPI adscaptcha = new AdsCaptchaAPI();

String result = adscaptcha.validateCaptcha(captchaId, privateKey, challengeValue, responseValue, remoteAddress);

if (result.equalsIgnoreCase("true")) 
{
	// Corrent answer, continue with your submission process
} 
else 
{
	// Wrong answer, you may display a new AdsCaptcha and add an error message
}

Don't forget to set your Captcha ID and Private Key values.

Download Java Library Download Example

AdsCaptcha for ASP

AdsCaptcha ASP library

To use AdsCaptcha with ASP, download AdsCaptcha ASP library, just to make things easier for you.
Extract and save adscaptchalib.asp on your website directory.

In order to use the ASP library, you'll need to include the library in the page/s which use it:

<!-- #include virtual="/your_path/adscaptchalib.asp" -->

Important: set the path according to your server path.

Client Side - Display your CAPTCHA

Now you're ready to display your CAPTCHA.
Place this code inside your <form> where the AdsCaptcha will be placed:

captchaId = "your captcha id"  ' Set your captcha id
publicKey = "your public key"  ' Set your private key
Response.Write GetCaptcha(captchaId, publicKey)

Don't forget to set your Captcha ID and public key values.

Server Side - Validate your CAPTCHA

On your validation process, place this code:

captchaId     = "your captcha id"   ' Set your captcha id, same value as before
privateKey    = "your private key"  ' Set your private key
challengeCode = Request("adscaptcha_challenge_field")
userResponse  = Request("adscaptcha_response_field")
remoteAddress = Request.ServerVariables("REMOTE_ADDR")
IsCaptchaValid = ValidateCaptcha(captchaId, privateKey, challengeCode, userResponse, remoteAddress)

If IsCaptchaValid = "true" Then
    ' Corrent answer, continue with your submission process
Else
    ' Wrong answer, you may display a new AdsCaptcha and add an error message
End If

Don't forget to set your Captcha ID and Private Key values.

Download ASP Library Download Example

AdsCaptcha for WordPress

Install Plugin

Download our WordPress plugin.
If you already have an installed AdsCaptcha plugin, please deactivate & delete it first.
On the administration panel, open Appearance > Plugins menu and click on Add New.
Click on the Upload tab. Use the browse button to select the plugin zip file, then click Install Now.
Activate the plugin.

Configure Plugin

Open Settings > AdsCaptcha to configure your CAPTCHA:

Keys - Unique identifiers (Captcha ID, Public Key and Private Key).
After you enter your keys, test your CAPTCHA.
You can choose whether to display an ADSCAPTCHA on the registration form and/or the comments form.
If you want to use different CAPTCHAs on the registration form and/or the comments, you may enter a different Captcha ID.
You can hide the CAPTCHA for registered users (by their permission level).
Error messages - You can modify the error messages text according to your own language.

That’s it!

The ADSCAPTCHA is now set and displayed in your blog... Congratulations!

Requirements

WordPress 2.6+
PHP 4.3+
Your theme must have a <?php do_action('comment_form', $post->ID); ?> tag inside your comments.php form. Most themes do.
If not, in your comments.php file, put <?php do_action('comment_form', $post->ID); ?> before <input name="submit"..>.
Multibyte String functions installed and enabled in your PHP server.
For multilanguage support, use UTF-8 encoding.

Troubleshooting

Q: I can't see the CAPTCHA
A: By default, the CAPTCHA is hidden for registered users (like you, as Administrator). Make sure to uncheck the "Hide CAPTCHA for registered users" or logout before checking your CAPTCHA again.

Q: The CAPTCHA displays AFTER or ABOVE the submit button on the comment form
A: You can try to check the "Rearrange CAPTCHA's position on the comment form automatically" option and javascript will attempt to rearrange it for you. If it's not fixing the problem, edit your current theme comments.php file and locate the line: <?php do_action('comment_form', $post->ID); ?>. Move this line to BEFORE the comment textarea, uncheck the rearrange option and the problem should be fixed.

Learn more about our captcha plugin for WordPress.

Download WordPress Plugin

AdsCaptcha for Joomla

Install Plugin

Download our Joomla plugin.
On the administration panel, from the Extensions menu select Install/Uninstall.
Under Upload Package File, click on Choose File and selected the downloaded plugin file. Than, click on Upload File & Install.
From the Extensions menu select Plugin Manager.
Click on System - AdsCaptcha plugin (you can use the filter to find it quicker).
Enter your captcha id, public and private keys.
Click on Save.
Check System - AdsCaptcha plugin and click on Enable.

That's it!

The ADSCAPTCHA is now set and displayed in your Joomla website... Congratulations!

Requirements

Joomla! 1.5.x
PHP 4.3+
Multibyte String functions installed and enabled in your PHP server.

Download Joomla Plugin

AdsCaptcha for Drupal

Install Plugin

Download our Drupal plugin (5.x or 6.x).
Upload the plugin to your Drupal server. Extract the files to your modules folder.
Verify that the CAPTCHA module is installed
On your Drupal administration page go to Site Building > Modules.
Under the Spam Control group, enable the CAPTCHA module and the AdsCaptcha module.

Configure Plugin

Goto User Management > CAPTCHA > AdsCaptcha tab and set your AdsCaptcha keys.
Goto User Management > CAPTCHA. Here you can choose the forms you want to use AdsCaptcha by selecting AdsCaptcha as the challenge type for each form you'd like to use AdsCaptcha (e.g., select AdsCaptcha for comment_form to enable AdsCaptcha on comments).

That's it!

The ADSCAPTCHA is now set and displayed in your Drupal website... Congratulations!

Requirements

Drupal 5.x / 6.x
CAPTCHA module
PHP 4.3+
Multibyte String functions installed and enabled in your PHP server.

Troubleshooting

Q: I can't see the CAPTCHA.
A: By default, the CAPTCHA is hidden for administrators. You can change it in your CAPTCHA options.

Q: The CAPTCHA's answer is not checked.
A: The CAPTCHA ignores administrators. Please re-check it with a "simple" user.

Q: How can I check my CAPTCHA?
A: On your Drupal administration page, go to User Management > CAPTCHA and click on the Examples tab.
It should display examples of all your enabled CAPTCHAs. Check if you see the AdsCaptcha example.
If an error message appears instead, please re-check your settings.

Download Drupal 6.x Plugin Download Drupal 5.x Plugin

AdsCaptcha for phpBB 3.x

Install Plugin

Download our phpBB3 plugin.
Unzip the adscaptcha_phpbb3.zip file, and upload the sub-directories into your root forum directory.
On the administration control panel (ACP), under the General tab, select Spambot countermeasures.
On the available plugins, select the AdsCaptcha plugin, then click Configure.
Enter your Captcha ID, Public and Private keys.
Click on Submit.

That’s it!

The ADSCAPTCHA is now set and displayed in your phpBB forum... Congratulations!

Requirements

phpBB 3.x
Styles: prosilver or subsilver2
PHP 4.3+
Multibyte String functions installed and enabled in your PHP server.

Download phpBB 3.x Plugin

AdsCaptcha for Python

Coming soon...

AdsCaptcha for Perl

Coming soon...

AdsCaptcha for DotNetNuke

Coming soon...

AdsCaptcha API Overview

API keys

Getting started

How the AdsCaptcha API works

Important connection issue

Related posts

Display the CAPTCHA

Error codes

Validate the CAPTCHA

Send API request

Get API response

Your API Keys

AdsCaptcha for C#/ASP.NET

AdsCaptcha C#/ASP.NET class

Display your CAPTCHA

Validate your CAPTCHA

AdsCaptcha for VB.NET

AdsCaptcha VB.NET class

Display your CAPTCHA

Validate your CAPTCHA

AdsCaptcha for PHP

AdsCaptcha PHP library

Client Side - Display your CAPTCHA

Server Side - Validate your CAPTCHA

Troubleshooting

AdsCaptcha for JAVA

AdsCaptcha JAVA library

Client Side - Display your CAPTCHA

Server Side - Validate your CAPTCHA

AdsCaptcha for ASP

AdsCaptcha ASP library

Client Side - Display your CAPTCHA

Server Side - Validate your CAPTCHA

AdsCaptcha for WordPress

Install Plugin

Configure Plugin

That’s it!

Requirements

Troubleshooting

AdsCaptcha for Joomla

Install Plugin

That's it!

Requirements

AdsCaptcha for Drupal

Install Plugin

Configure Plugin

That's it!

Requirements

Troubleshooting

AdsCaptcha for phpBB 3.x

Install Plugin

That’s it!

Requirements

AdsCaptcha for Python

AdsCaptcha for Perl

AdsCaptcha for DotNetNuke