Java/Vert.x-Web Integration for Bot Protection

How to install the Java Module

With Maven

<project>
...
    <dependencies>
    ...
        <dependency>
          <groupId>co.datadome.module</groupId>
          <artifactId>datadome-java-module</artifactId>
          <version>2.0.2</version>
        </dependency>
    ...
    </dependencies>
...
</project>

Manual Installation

Download the archive from the link below:

https://package.datadome.co/linux/DataDome-Java-latest.tgz

The downloaded zip file includes sources, so you can directly install it in your local Maven repository.

By default it is built with vertx-web-4.4.3. If your installation is dependant on vertx-web-4.0, you need to build it manually with a different profile:

mvn install

mvn -P vertx-web-4.0 install

Usage

DataDome is providing a custom route handler for HTTP request: DataDomeRouteHandler. This handler needs to process the HTTP request prior to any other handlers.
The handler forwards the HTTP request's information to the DataDome server, and depending on whether or not it is a request from a bot, it pushes the HTTP request to the other handlers (routingContext.next()) or processes the request by responding with an HTTP body along with a Captcha challenge.
The handler needs to decode the cookie for detecting the bot. Make sure to provide the handler with the routing information.

We suggest using the mountSubRouter routine to enable the DataDomeRouteHandler to catch all HTTP requests first.
Below is an example of code integration:

final DataDomeRouteHandler dataDomeRouteHandler =
  new DataDomeRouteHandler(
  	new DataDomeRouteHandlerConfig.DataDomeRouteHandlerConfigBuilder("YOUR_DATADOME_SERVER_SIDE_KEY").build());

Router dataDomeRouter = Router.router(vertx());
Route dataDomeRoute = dataDomeRouter.route();
dataDomeRoute
  .handler(CookieHandler.create())
  .handler(dataDomeRouteHandler::handleRequest);

/* add a subrouter to your current router */
dataDomeRouter.mountSubRouter("/", YourCurrentRouter);

/* have the datadome router process http request first */
server.requestHandler(dataDomeRouter::accept).listen(80);

List of possible parameters:

You can tune the behavior of DataDomeRouteHandler with DataDomeRouteHandlerConfigBuilder

Attribute	Description	Default
apikey	License key to access API (mandatory)
apiHost	Hostname of API server Available endpoints	api.datadome.co
apiSSL	Use SSL between the filter and the API server	true
regex	Inclusion Regex	""
exclusionRegex	Exclusion Regex	"(?i).(avi\|flv\|mka\|mkv\|mov\|mp4\|mpeg\|mpg\|mp3\|flac\|ogg\|ogm\|opus\|wav\|webm\|webp\|bmp\|gif\|ico\|jpeg\|jpg\|png\|svg\|svgz\|swf\|eot\|otf\|ttf\|woff\|woff2\|css\|less\|js)$"
connectTimeout	Connection timeout (in ms)	150
readTimeout	Read timeout (in ms)	50
maxConnections	Maximum open connections to the API server	100
useXForwardedHost	Use the request header `x-forwarded-host` instead of `host` (used for cookie, dashboard domain...)	false
proxyServer	Host that will be used as proxy server
proxyPort	TCP port at the proxy server
proxySSL	Is the connection to the proxy established through TLS	false
skipIps	IPv4 or IPv6 subnetwork list on which DataDome validation is not executed

FAQ

How can I get the time spent calling the DataDome API?

DataDomeRouteHandler writes a log info "DataDome request/response time in milliseconds: [...]".

Can DataDome API be called via an outbound proxy?

The DataDome module can be used with an outbound proxy. Two options are available for proxy configuration:

Use system settings like -Dhttp.proxyHost=1.2.3.4 -Dhttp.proxyPort=8080 -Dhttps.proxyHost=1.2.3.4 -Dhttps.proxyPort=8443 when running your java application
Use optional DataDomeRouteHandlerConfigBuilder parameters proxyServer, proxyPort, proxySsl

Note: Using the DataDome module with an outbound proxy can slow down total time spent calling DataDome API and increase timeouts. Please adjust timeout settings accordingly.