DocumentationAPIChangelogFree TrialLog in

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

How to install the JS Tag

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 <body> element.

<script>
!function(a,b,c,d,e,f){a.ddjskey=e;a.ddoptions=f||null;var m=b.createElement(c),n=b.getElementsByTagName(c)[0];m.async=1,m.src=d,n.parentNode.insertBefore(m,n)}(window,document,"script","https://js.datadome.co/tags.js","YOUR_DATADOME_JS_KEY", { ajaxListenerPath: true });
</script>

Your document should look like this:

<head>
  ...
</head>
<body>
  <script>
  !function(a,b,c,d,e,f){a.ddjskey=e;a.ddoptions=f||null;var m=b.createElement(c),n=b.getElementsByTagName(c)[0];m.async=1,m.src=d,n.parentNode.insertBefore(m,n)}(window,document,"script","https://js.datadome.co/tags.js","YOUR_DATADOME_JS_KEY", { ajaxListenerPath: true });
  </script>
  ...
</body>

This inline script will add another <script> element in the document that will load the actual JS Tag asynchronously.

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">
!function(a,b,c,d,e,f){a.ddjskey=e;a.ddoptions=f||null;var m=b.createElement(c),n=b.getElementsByTagName(c)[0];m.async=1,m.src=d,n.parentNode.insertBefore(m,n)}(window,document,"script","https://js.datadome.co/tags.js","YOUR_DATADOME_JS_KEY", { ajaxListenerPath: true });
</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

FAQ

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

Yes, this is a possible alternative to configuring 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.

🚧

Keeping the script up-to-date

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

Updated about 2 months ago