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

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 people's privacy such as canvas fingerprinting. Therefore, the collected fingerprint doesn’t have a high entropy or uniqueness to it.

Installation

Prerequisite

You will need the client-side key from your dashboard. You can find it in the Management page and under the Integrations tab.

Code

Copy the code snippet below, replace the YOUR_DATADOME_JS_KEY string with your actual client-side key and paste it at the start of the <head> element.

<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>

🚧

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 inside a Tag Manager (like Google Tag Manager) as it introduces delay to load it

Configuration

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

Single-Page Application

In case you are developing a Single-Page Application (SPA), please follow our documentation for SPA.

Content Security Policy

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>

📘

About CSP hashes

We don't recommend using hashes with the script-src directive for inline scripts as the CSP would break without warning as soon as the JS Tag would get updated.

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 geo.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