DocumentationAPIChangelogTest your siteDashboard
Documentation

JavaScript Tag

Suggest Edits

Installing the JavaScript Tag (or JS Tag) is required for two reasons:

  • Guarantee an optimal level of detection, combined with any server-side integration from DataDome.
  • Ensure that response pages are displayed when requests made with XMLHttpRequest or Fetch are blocked.

Signals

The JS Tag will provide our detection engine with more insights on the clients that are executing the script.

It collects behavioral data from the client (i.e. the web browser in most cases) such as mouse movements or key strokes. Generic information is also collected about the OS, the browser itself, the GPU, etc.

Many tests also run to verify the consistency of built-in functions and attributes linked to known bots, which enables DataDome to detect among other things:

  • Headless Chrome
  • Puppeteer
  • Puppeteer Extra Stealth
  • Selenium (even modified)

📘

Privacy concerns

The JS Tag's purpose is focused on bot detection and not tracking: the script doesn't collect information that may be considered as invasive of user privacy such as canvas fingerprinting. Therefore, the collected fingerprint doesn’t have a high entropy or uniqueness to it.

Installation

Prerequisites

Code

  1. Copy the code snippet below.
  2. Paste it at the start of the <head> element.
  3. Replace YOUR_DATADOME_JS_KEY in the snippet with your actual client-side key.
<script>
  window.ddjskey = 'YOUR_DATADOME_JS_KEY';
  window.ddoptions = {
  	// Add your configuration here
  };
</script>
<script src="https://js.datadome.co/tags.js" async></script>

Your document should look like this:

<head>
  <script>
    window.ddjskey = 'YOUR_DATADOME_JS_KEY';
    window.ddoptions = {
    	// Add your configuration here
    };
  </script>
  <script src="https://js.datadome.co/tags.js" async></script>
  <!-- Other head elements go here -->
</head>
<body>
  <!-- Your website content goes here -->
</body>

🚧

On the importance of loading the JS Tag early

It is highly recommended to load the JS Tag first or as early as possible to ensure the following:

  • Intercept protected requests (using XMLHttpRequest or Fetch) and guarantee the display of challenges
  • Preserve session continuity when using the sessionByHeader option
  • Maintain valid referrer data for your client-side analytics after passing a challenge

⚠️ We don't recommend to set it up from a Tag Manager (like Google Tag Manager) as it introduces delay to load it

Configuration

📘

Configuration guide

ℹ️ Find more details on how to configure the JS Tag on this page.

First-party setup

We recommend using a first-party setup to help ensure the JS Tag runs on your protected pages if:

  • The JS Tag is blocked by browsers or ad blockers for many of your end users
  • It makes it easier to integrate with existing CSP configurations
  • The server-side integration is based on AWS CloudFront (due to limitations on response cookies)

📘

First-party setup guide

Find step-by-step instructions on this page.

Content Security Policy (CSP)

In order to integrate the JS Tag on a website that uses Content Security Policy (CSP), you will need to include the additional directives in your website's policy.

script-src

Two script-src directives are required for the initial inline script and the <script> element that is added subsequently.

  • script-src nonce-2726c7f26c to allow a nonce-source instead of using the unsafe-inline directive
    • 2726c7f26c here is an example, do not use it as is: this part should be generated dynamically for each request to load a page with a CSP
  • script-src js.datadome.co ct.captcha-delivery.com
    • js.datadome.co will allow the <script> element to load the JS Tag from this domain
    • ct.captcha-delivery.com will allow the scripts of our response pages to be loaded from this domain after a request has been blocked

Documentation about using a nonce-source for the inline script can be found on this page from MDN.

In practice, the nonce value should then be applied on the <script> element that contains our inline script described above and other inline scripts as well.

For example:

<script nonce="2726c7f26c">
    window.ddjskey = 'YOUR_DATADOME_JS_KEY';
    window.ddoptions = {
    	// Add your configuration here
    };
</script>
<script src="https://js.datadome.co/tags.js" async></script>

connect-src

  • connect-src api-js.datadome.co to allow the JS Tag to send the fingerprint back to our API

❗️

About First-Party JS Tag

If you are using a First-Party JS Tag setup, you might need to replace api-js.datadome.co with the first-party domain that you are using, unless this domain is already covered by an existing connect-src directive

frame-src

  • frame-src *.captcha-delivery.com to allow our response pages to be loaded from an <iframe> element after a request has been blocked

worker-src

  • worker-src blob:to allow loading our web worker to load from Blob URLs. This ensures the collection of specific fingerprints by the worker, helping to offload tasks from the main thread.

FAQ

Can I host the JS Tag on my own CDN or infrastructure?

Yes, this is a possible alternative to a First-Party setup.

For performance reasons (avoid an extra DNS lookup and TCP connection), you can pull our JavaScript Tag from our origin on https://js.datadome.co/tags.js and distribute it from your own CDN or infrastructure.

Note: This will not have any negative impact in terms of detection.

🚧

Keeping the script up-to-date

We recommend that you synchronize with the origin every hour to keep it up-to-date.

📘

Ensuring fingerprints are collected

We recommend setting up a POST endpoint on a /js/ route to forward fingerprints to https://api-js.datadome.co/js/ (e.g., https://dd.example.com/js/). This ensures that signals are collected without additional changes.

To get more details about endpoint configuration in the JS Tag, refer to the endpoint documentation.

Updated about 1 month ago

What’s Next