Java/Vert.x-Web

How to install the Java Module

With Maven

<project>
...
    <repositories>
    ...
        <repository>
          <id>jitpack.io</id>
          <url>https://jitpack.io</url>
        </repository>
    ...
    </repositories>
    <dependencies>
    ...
        <dependency>
          <groupId>com.github.datadome</groupId>
          <artifactId>datadome-java-module</artifactId>
          <version>1.13</version>
        </dependency>
    ...
    </dependencies>
...
</project>

Manual Installation

  1. Download the archive from the link below:
https://package.datadome.co/linux/DataDome-Java-latest.tgz
  1. 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-3.7.1. If your installation is dependant on vertx-web-3.5.4, you need to build it manually with a different profile:

mvn install
mvn -P vertx-web-3.5.4 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("YourClientDataDomeApiKey").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

".(js|css|jpg|jpeg|png|ico|gif|tiff|svg|woff|woff2|ttf|eot|mp4|otf)$"

connectTimeout

Connection timeout (in ms)

150

readTimeout

Read timeout (in ms)

50

maxConnections

Maximum open connections to the API server

100

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 the DataDome API be called via 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.