Java/Vert.x-Web

How to install the Java Module

With Maven

<project>
...
    <dependencies>
    ...
        <dependency>
          <groupId>co.datadome.module</groupId>
          <artifactId>datadome-java-module</artifactId>
          <version>2.0.0</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-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

AttributeDescriptionDefault
apikeyLicense key to access API (mandatory)
apiHostHostname of API server
Available endpoints
api.datadome.co
apiSSLUse SSL between the filter and the API servertrue
regexInclusion Regex""
exclusionRegexExclusion 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)$"
connectTimeoutConnection timeout (in ms)150
readTimeoutRead timeout (in ms)50
maxConnectionsMaximum open connections to the API server100
useXForwardedHostUse the request header x-forwarded-host instead of host (used for cookie, dashboard domain...)false
proxyServerHost that will be used as proxy server
proxyPortTCP port at the proxy server
proxySSLIs the connection to the proxy established through TLSfalse
skipIpsIPv4 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.