BotDetect JSP CAPTCHA Integration Quickstart

Unlike Recaptcha the Stalker -- BotDetect CAPTCHA works in China! Licensable source-code; self-hosted -- doesn't stalk -- nor does it slurp your form-data! Think: GDPR & LGPD!

1. Add BotDetect Java CAPTCHA Library Dependency

Manual
Maven
Gradle
Ant+Ivy
Ant

Install BotDetect Java CAPTCHA dependencies

Download and unpack the BotDetect Java CAPTCHA library archive.

The folder where you unpacked the BotDetect archive will be referred as the <BDC-DIR> in this guide. It contains the BotDetect jars.

Copy the .jar files listed below to /your-app-backend-folder/WEB-INF/lib folder:

<BDC-DIR>/botdetect-4.0.beta3.7.jar
<BDC-DIR>/botdetect-servlet-4.0.beta3.7.jar
<BDC-DIR>/botdetect-jsp20-4.0.beta3.7.jar

Install BotDetect Java CAPTCHA dependencies

The free version Maven artifacts are available from our public repository; while the enterprise version jars are available in the root folder of the enterprise version's archive.

To reference the BotDetect dependency from our public repository, the repository itself has to be declared first -- add the highlighted lines to your app's pom.xml file:

<repository>
  <id>captcha</id>
  <name>BotDetect Captcha Repository</name>
  <url>https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/</url>
</repository>

Then, in the same file, declare the BotDetect dependency, too:

<dependency>
  <groupId>com.captcha</groupId>
  <artifactId>botdetect-jsp20</artifactId>
  <version>4.0.beta3.7</version>
</dependency>

Install BotDetect Java CAPTCHA dependencies

The free version Maven artifacts are available from our public repository; while the enterprise version jars are available in the root folder of the enterprise version's archive.

To reference the BotDetect dependency from our public repository, the repository itself has to be declared first -- add the highlighted line to your app's build.gradle file:

repositories {
  maven {
    url "https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/"
  }
  ...    
}

Then, in the same file, declare the BotDetect dependency, too:

dependencies {
  ...
  compile 'com.captcha:botdetect-jsp20:4.0.beta3.7'
  ...
}

Install BotDetect Java CAPTCHA dependencies

The free version Maven artifacts are available from our public repository; while the enterprise version jars are available in the root folder of the enterprise version's archive.

To reference the BotDetect dependency from our public repository, the repository itself has to be declared first -- add the highlighted line to your app's ivy-settings.xml file:

<ivysettings>
  <properties file="build.properties" />
  <settings defaultResolver="default-chain"/>
  <resolvers>
    <chain name="default-chain">
      <ibiblio name="botdetect" 
               root="https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:" 
               m2compatible="true"/>
      ...
    </chain>
  </resolvers>
</ivysettings>

Then, declare the BotDetect dependency in your app's ivy.xml file:

<ivy-module version="2.0">
  <info organisation="org.apache" module="WebProject" />

  <!-- Classpath management, thanks Maven -->
  <configurations>
    <conf name="compile" description="compile dependencies"/>
    <conf name="runtime" description="runtime dependencies" extends="compile"/>
    <conf name="test"    description="test dependencies" extends="runtime"/>
  </configurations>

  <dependencies>
    <dependency org="com.captcha" 
	        name="botdetect-jsp20" 
	        rev="4.0.beta3.7" 
	        conf="compile->default"/>
    ...
  </dependencies>
</ivy-module>

And then, ensure that your app's build.xml file has a build target with the ivy:retrieve task:

<target name="resolve" description="retrieve dependencies with ivy">
  <echo message="Getting dependencies..." />
  <ivy:retrieve />
  <ivy:cachepath pathid="compile.path" conf="compile" />
  <ivy:cachepath pathid="runtime.path" conf="runtime" />
  <ivy:cachepath pathid="test.path" conf="test" />
</target>

Install BotDetect Java CAPTCHA dependencies

The free version BotDetect jars are available from our public repository; while the enterprise version jars are available in the root folder of the enterprise version's archive.

To declare the BotDetect dependencies from our public repository, an additional target has to be added to your app's build.xml file.

The target name will be the botdetect-dependencies-target, and it should consist of the following lines:

<target name="botdetect-dependencies" description="BotDetect Java CAPTCHA library">
    <echo message="Getting BotDetect..." />
    <mkdir dir="lib" />
    <get src="https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/com/captcha/botdetect/4.0.beta3.7/botdetect-4.0.beta3.7.jar" dest="lib/botdetect-4.0.beta3.7.jar" usetimestamp="true" />
    <get src="https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/com/captcha/botdetect-servlet/4.0.beta3.7/botdetect-servlet-4.0.beta3.7.jar" dest="lib/botdetect-servlet-4.0.beta3.7.jar" usetimestamp="true" />
    <get src="https://git.captcha.com/botdetect-java-captcha.git/blob_plain/HEAD:/com/captcha/botdetect-jsp20/4.0.beta3.7/botdetect-jsp20-4.0.beta3.7.jar" dest="lib/botdetect-jsp20-4.0.beta3.7.jar" usetimestamp="true" />
</target>

To retrieve BotDetect dependencies during the build, reference the botdetect-dependencies-target inside the depends attribute of your compile target, by adding the lines listed below into the same file:

<target name="compile" depends="botdetect-dependencies">
  <copydir src="${web.dir}" dest="${build.dir}" />
  <mkdir dir="${web.classes.dir}" />
  <javac destdir="${web.classes.dir}" source="${jdk.version}" target="${jdk.version}"
    debug="true" includeantruntime="false" classpathref="compile.path">
    <src path="${src.dir}" />
  </javac>
</target>

2. Show a CAPTCHA Challenge on the Form

On the very top of the source file for the web form you want to protect against bots, add:

<%@page import="com.captcha.botdetect.web.servlet.Captcha"%>

On the web form you want to protect against bots, add:

<%
  // Adding BotDetect Captcha to the page
  Captcha captcha = Captcha.load(request, "exampleCaptcha");
  captcha.setUserInputID("captchaCode");

  String captchaHtml = captcha.getHtml();
  out.write(captchaHtml);
%>

<input id="captchaCode" type="text" name="captchaCode" />

3. Check User Input During Form Submission

When the form is submitted, the Captcha validation result must be checked:

<%
  if ("POST".equalsIgnoreCase(request.getMethod())) {
     // validate the Captcha to check we're not dealing with a bot
     boolean isHuman = captcha.validate(request.getParameter("captchaCode"));
     if (isHuman) {
      // TODO: Captcha validation passed, perform protected action
     } else {
      // TODO: Captcha validation failed, show error message
     }
  }
%>

4. Configure your Application

Update your application configuration (web.xml) file.

<servlet>
  <servlet-name>BotDetect Captcha</servlet-name>
  <servlet-class>com.captcha.botdetect.web.servlet.CaptchaServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>BotDetect Captcha</servlet-name>
  <url-pattern>/botdetectcaptcha</url-pattern>
</servlet-mapping>

In-Depth JSP CAPTCHA Instructions and Explanations

Detailed JSP Captcha instructions and explanations can be found in the JSP Captcha integration how to guide.

Please Note

BotDetect Java Captcha Library v4.0.Beta3.7 is an in-progress port of BotDetect 4 Captcha, and we need you to guide our efforts towards a polished product. Please let us know if you encounter any bugs, implementation issues, or a usage scenario you would like to discuss.