DocumentationAPIChangelogTest your siteDashboard
Documentation

Node.js / Express

DataDome Node.js module detects and protects against bot activity.

Suggest Edits

❗️

Deprecated version

This documentation covers versions 1.x.x of the Node.js integration which is deprecated.

For the latest version 2.x.x, please refer to the new documentation.
This guide provides instructions to help you upgrade your Node.js integration.

This module is dedicated to be used inside the Node.js backend web-server.

Before the regular Node.js HTTP process starts, it sends requests to the DataDome server. Depending on the API response, the module either blocks the request or proceeds with the regular process.

The module has been developed to protect the users' experience: if any errors were to occur during the process, or if the timeout is reached, the module will automatically disable its blocking process and allow the regular process to proceed.

The module can be imported using both CommonJS or ES module syntaxes.

How to install and embed the module

The module is distributed as a npm package. You can install it in your process and you will need to slightly modify the code.

The first step is to install it into an application (using npm) with the following command:

npm i @datadome/node-module

The next step is more complex and requires you to update your application to work over the DataDome module.

Below is an example with a simple HTTP server:

const http = require('http');

const hostname = '127.0.0.1';
const port = 3000;

const server = http.createServer((req, res) => {
      res.statusCode = 200;
      res.setHeader('Content-Type', 'text/plain');
      res.end('Hello World\n');
});

server.listen(port, hostname, () => {
    console.log(`Server running at http://${hostname}:${port}/`);
});

import http from 'http';

const hostname = '127.0.0.1';
const port = 3000;

const server = http.createServer((req, res) => {
      res.statusCode = 200;
      res.setHeader('Content-Type', 'text/plain');
      res.end('Hello World\n');
});

server.listen(port, hostname, () => {
    console.log(`Server running at http://${hostname}:${port}/`);
});

To integrate DataDome you need to make the following changes on this application:

const DataDome = require('@datadome/node-module');
const http = require('http');

const hostname = '127.0.0.1';
const port = 3000;

const datadomeClient = new DataDome('Some Key', 'api.datadome.co')
      .on('blocked', function(req) {
          console.log('DataDome blocked this request');
      })
      .on('valid', function(req, res) {
          console.log('DataDome passed this request');
          res.statusCode = 200;
          res.setHeader('Content-Type', 'text/plain');
          res.end('Hello World\n');
      });

const server = http.createServer((req, res) => {
    datadomeClient.auth(req, res);
});

server.listen(port, hostname, () => {
    console.log(`Server running at http://${hostname}:${port}/`);
});

import DataDome from '@datadome/node-module';
import http from 'http';

const hostname = '127.0.0.1';
const port = 3000;

const datadomeClient = new DataDome('Some Key', 'api.datadome.co')
      .on('blocked', function(req) {
          console.log('DataDome blocked this request');
      })
      .on('valid', function(req, res) {
          console.log('DataDome passed this request');
          res.statusCode = 200;
          res.setHeader('Content-Type', 'text/plain');
          res.end('Hello World\n');
      });

const server = http.createServer((req, res) => {
    datadomeClient.auth(req, res);
});

server.listen(port, hostname, () => {
    console.log(`Server running at http://${hostname}:${port}/`);
});

The idea behind the changes above is moving the application logic into a valid event of the module. This module will still generate a blocked event with the original request, but now it will deliver the Captcha page to the user before generating the event.

Express integration

The module also supports integration through callbacks. Refer to the example below for an integration with express:

const DataDome = require('@datadome/node-module');

const express = require('express');
const app = express();

const datadomeClient = new DataDome('Some Key', 'api.datadome.co');

app.use(function(req, resp, next) {
    datadomeClient.authCallback(req, resp, function() {
        // apiserver passed request, move forward
        next();
    }, function() {
        // nothing to do when blocked
    });
});

app.get('/', function (req, res) {
    res.send('Hello World');
});

app.listen(3000);

import DataDome from '@datadome/node-module';

import express from 'express';
const app = express();

const datadomeClient = new DataDome('Some Key', 'api.datadome.co');

app.use(function(req, resp, next) {
    datadomeClient.authCallback(req, resp, function() {
        // apiserver passed request, move forward
        next();
    }, function() {
        // nothing to do when blocked
    });
});

app.get('/', function (req, res) {
    res.send('Hello World');
});

app.listen(3000);

Options and events

This module provides two events:

  • valid: accepts a function with two arguments request and response. Both contain updated headers, based on the APIServer response.
  • blocked: accepts a function with one argument request that contains the request as it was sent to the module.

Events are generated only when you call the auth method. In case you use authCallback, it calls the specified callback and doesn't generate events.

You can also customize the behavior of the module by adding an object as a third argument with parameters:

OptionDefault valueDescription
ssltrueDoes the module use HTTPS
port443The port to connect on the APIServer
path'/validate-request/'The endpoint on the APIServer
timeout150Timeout in ms, after which the request will be passed
uriRegexnullRegex that should be matched to process the request over APIServer. null means accept all requests that don't match uriRegexExclusion.
uriRegexExclusion/\.(js|css|jpg|jpeg|png|ico|gif|tiff|svg|woff|woff2|ttf|eot|mp4|otf)$/Regex that should not be matched to process the request over APIServer. null means accept all requests it tested after uriRegex.

Below is an example of a call with default options:

...
const datadomeClient = new DataDome('Some Key', 'api.datadome.co', {
    ssl: true,
    port: 443,
    path: '/validate-request/',
    timeout: 150,
    uriRegex: null,
    uriRegexExclusion: /\.(js|css|jpg|jpeg|png|ico|gif|tiff|svg|woff|woff2|ttf|eot|mp4|otf)$/
})
...

Updated about 2 months ago