Having the right configuration for the JS Tag is essential to allow DataDome to work in optimal conditions depending on your web app.

This page will explain how to use the right options for the JS Tag, providing you with a better understanding and more control over your client-side integration with DataDome:

• The Overview section offers a global view of available options
• The Details section goes over the purpose of each option and instructions on how to use them

❗️

Impacts of a bad configuration

Configuration issues can lead to poor user experience for your users and/or sub-optimal detection on bot threats.

Please feel free to review your JS Tag configuration with the help of our technical support if you have any doubt.

📘

Defining your configuration on window.ddoptions

You must configure the JS Tag by adding properties to the window.ddoptions object as seen on the code snippet displayed here.

Overview

Details

abortAsyncOnChallengeDisplay

📘

Why should I use abortAsyncOnChallengeDisplay?

By default, the JS Tag will abort requests that got blocked.

If your application needs to know when a request was blocked and got a 403 response (e.g. to run an error handler), you might need to disable this behavior.

How to use abortAsyncOnChallengeDisplay to stop aborting blocked requests

• Add abortAsyncOnChallengeDisplay: false to the window.ddoptions configuration object to disable it.

ajaxListenerPath

📘

Why should I use ajaxListenerPath?

The ajaxListenerPath option is the most important parameter for the JS Tag; it is required to intercept XHR and Fetch requests protected by DataDome based on matching URL patterns.

Its main purpose is to properly display challenges (e.g. CAPTCHA and Device Check) when one of these requests has been blocked, but also to apply options such as withCredentials, sessionByHeader and overrideAbortFetch on matching requests.

How to use ajaxListenerPath to enforce challenge display

It is recommended to define this option as an array to make it easier to add parameters.

ℹ️ It is possible to mix String and URLParts parameters in the same array.

window.ddoptions = {
  ajaxListenerPath: [
    // Add your parameters here
  ]
};

Most used: matching URLs with String parameters

Each parameter from the array will be used as a substring to match against the complete URL of a request.

For example, the example below will look for domain.com and /api not only on the host or the path of a URL, but also on the query string and the anchor.

window.ddoptions = {
  ajaxListenerPath: [
    'domain.com',
    '/api'
  ]
};

👍

URLs that will match with the example configuration

• https://domain.com/api
• https://staging.domain.com/cart
• https://partner.example.com/api
• https://partner.example.com/info?referrer=domain.com

Advanced: matching URLs with URLParts parameters

URLParts parameters can be used to target specific parts of a URL instead of its entire value.

The structure of a URLParts parameter can include these properties, with at least one URL property:

🚧

About the strict mode

By default, a URLParts parameter will match a URL if at least one of its properties matched.

If all the properties of a URLParts parameter must match, you must add strict: true to the parameter.

For example, we can convert the previous parameters so that domain.com can only match hosts and /api can only match paths:

window.ddoptions = {
  ajaxListenerPath: [
    { host: 'domain.com' },
    { path: '/api' }
  ]
};

👍

URLs that will match with the example configuration

• https://domain.com/api
• https://staging.domain.com/cart
• https://partner.example.com/api

❗️

URLs that will not match with the example configuration

• https://partner.example.com/info?referrer=domain.com

Using wildcards for dynamic patterns

Wildcards (i.e. * characters) can be used to match with any string of characters in the middle of a pattern.

For example, the configuration below could match with any path that starts with /api and ends with /login:

window.ddoptions = {
  ajaxListenerPath: [
    { path: '/api/*/login' }
  ]
};

👍

URLs that will match with the example configuration

• https://domain.com/api/78a93c7/login
• https://staging.domain.com/api/test/login

Other possible configurations

• Using ajaxListenerPath: true (the default value) will match request URLs with the host of the current document.
• Passing a single String value to ajaxListenerPath is equivalent to having an array with a single value.

ajaxListenerPathExclusion

📘

Why should I use ajaxListenerPathExclusion?

The ajaxListenerPathExclusion option can be used to filter out request URLs that could match with the ajaxListenerPath option.

Matching requests will also be excluded from applying options such as withCredentials, sessionByHeader and overrideAbortFetch.

How to use ajaxListenerPathExclusion to exclude URL patterns from matching with ajaxListenerPath

• Follow the same instructions as for the ajaxListenerPath option.

challengeLanguage

📘

Why should I use challengeLanguage?

By default, challenges will be displayed with the main language seen on the Accept-Language request header, which reflects the user preferences from the browser.

If you prefer to use languages that are defined as user preferences on your application, you can rely on this option to enforce them.

How to use challengeLanguage to force a language when displaying a challenge

• Add challengeLanguage: 'xx' to the window.ddoptions configuration object and replace xx with the identifier of the language to use
  • Refer to the documentation for DataDome CAPTCHA to get a list of supported language identifiers

disableAutoRefreshOnCaptchaPassed

📘

Why should I use disableAutoRefreshOnCaptchaPassed?

By default, the JS Tag will force a page reload after passing a challenge for a blocked request that was made with XMLHttpRequest or Fetch.

If you would rather go back to the page in its current state (e.g. to avoid losing form data after a block), you can use this option to disable that automatic reload behavior.

How to use disableAutoRefreshOnCaptchaPassed to disable the automatic page reload after passing a challenge

• Add disableAutoRefreshOnCaptchaPassed: true to the window.ddoptions configuration object to disable it.

enableServiceWorkerPlugin

📘

Why should I use enableServiceWorkerPlugin?

If your application uses a service worker to proxy some of its requests, the JS Tag will not be able to intercept this traffic in order to display challenges when it is blocked.

This option is required to receive events from the @datadome/service-worker-plugin package in order to display challenges as expected.

The @datadome/service-worker-plugin is a dependency that has to be imported in your service worker.

How to use enableServiceWorkerPlugin to display challenges for requests blocked in service workers

• Add enableServiceWorkerPlugin: true to the window.ddoptions configuration object to enable it.
• Add the @datadome/service-worker-plugin to your service worker following the instructions from its description.

enableTagEvents

📘

Why should I use enableTagEvents?

If you need to execute your own logic following specific events handled by the JS Tag, you can enable this option to let it dispatch global events on which your application can subscribe.

How to use enableTagEvents to dispatch events for specific actions

• Add enableTagEvents: true to the window.ddoptions configuration object to enable it.
• Add event listeners on the global window object to subscribe to the events of your choice.
  • You can find more details about each event below in the next section.

window.addEventListener('dd_response_passed', (event) => {
  // Implement your own logic to be executed after a user passed a challenge
  // (e.g. CAPTCHA or Device Check)
});

🚧

Use the detail property

All events dispatched by this option will be instances of CustomEvent, so all properties documented below will be accessible on the detail property of the event.

Event details

🚧

About events marked with a ⚠️ sign

These events can only be dispatched for requests that were sent using XMLHttpRequest or Fetch.

Blocked navigation requests (i.e. HTTP requests to load a document) cannot be intercepted by the JS Tag, since the document that is supposed to load it would not be rendered.

Property details

endpoint

📘

Why should I use endpoint?

If you are hosting the JS Tag on your own infrastructure, payloads generated by the JS Tag need to be sent to a custom endpoint instead of the default one.

When not defined, the endpoint value is automatically inferred by the JS Tag by using the /js/ route from the same origin.

• If the script loading source is: https://my.customdomain.com/tags.js
• The inferred endpoint will be: https://my.customdomain.com/js/

You should configure the endpoint option if:

• You don't load the JS Tag from the default URL (https://js.datadome.co/tags.js) and don't use our First-Party JS Tag feature
• You don't expose the JS Tag under its original name (tags.js)
• The endpoint URL is different from the one inferred by the JS Tag

Prerequisites for endpoint

• Loading the JS Tag from a custom URL (see this section for more details)

How to use endpoint to send signals to a custom domain

• Add the endpoint option to the window.ddoptions with the URL of the API that will receive payloads from the JS Tag.

For example, let's say you set up the JS Tag to be served from https://dd.example.com/tags.js, but signals should be collected on from a different origin and/or route:

window.ddoptions = {
  endpoint: 'https://collect.example.com/js/'
}

exposeCaptchaFunction

📘

Why should I use exposeCaptchaFunction?

By default, the JS Tag handles the lifecycle of challenges on blocked requests.

If you need more control on that lifecycle, and used the enableTagEvents option, you might need this option to allow your application to trigger the display itself.

How to use exposeCaptchaFunction to handle challenge display

• Add exposeCaptchaFunction: true to the window.ddoptions configuration object to enable it.

This will have two outcomes:

• It will expose the display function used by the JS Tag as window.displayDataDomeResponsePage(url, root). This function takes two parameters which are
  • url: The URL of the challenge to display. This URL can be retrieved by subscribing to the dd_blocked event and reading the event.detail.responseUrl property.
    Note that this event is only dispatched if the enableTagEvents option is set to true.
    For more details, see the section about the enableTagEvents option.
  • root (optional): The DOM element that will serve as the parent for the challenge frame.
    If not provided, the challenge frame will be attached to the document.body element.
• The automatic display performed by the JS Tag will be disabled.

overrideAbortFetch

📘

Why should I use overrideAbortFetch?

By default, the JS Tag prevents AbortSignal tokens from aborting Fetch requests to ensure that challenges are properly displayed on blocked requests.

You might need to disable this behavior if the usage of these AbortSignal tokens is essential for your application.

How to use overrideAbortFetch to disable overrides of Request instances using AbortSignal tokens

• Add overrideAbortFetch: false to the window.ddoptions configuration object to disable it.

🚧

Matching with ajaxListenerPath and ajaxListenerPathExclusion

This option is only applied on requests with a URL that matches with the configuration defined on the ajaxListenerPath and ajaxListenerPathExclusion options.

replayAfterChallenge

📘

Why should I use replayAfterChallenge?

Enable this option if you need requests sent with XMLHttpRequest or fetch to be replayed by the JS Tag after being challenged with a CAPTCHA or a Device Check response.

The replay will run after the end user successfully passed it — for example, to re-submit a login form or a search query.

How to use replayAfterChallenge to enable request replay

• Add replayAfterChallenge: true to the window.ddoptions configuration object to enable it.
• Make sure that the ajaxListenerPath option covers requests that must be replayed.

🚧

Important notes

• Replaying a request sent with XMLHttpRequest asynchronously requires that the event listener(s) (i.e. for the load event) used to read the response remain attached to the request instance. If not, the replay will not yield the expected result to the application.
• Enabling replayAfterChallenge will also activate disableAutoRefreshOnCaptchaPassed to allow replays to take place instead of reloading pages.
• If multiple requests were blocked concurrently, only the first one will be replayed.

sessionByHeader

📘

Why should I use sessionByHeader?

You might need this option in two cases:

• Your application is hosted on a domain (e.g. www.example.com) that cannot match with the domain of third-party APIs (e.g. api.other.com), so the datadome cookie cannot be saved while the SameSite=Lax attribute is used, because it will be attached to that API's domain (e.g. Domain=.other.com).
• You don't want to use the withCredentials option because it sends all cookies that match with the request's domain.

Prerequisites for sessionByHeader

• You must configure your CORS headers with the following rules:
  • Allow the x-datadome-clientid request header by including Access-Control-Allow-Headers: x-datadome-clientid on preflight responses (i.e. for requests using the OPTIONS method):
    • Documentation for Access-Control-Allow-Headers
  • Allow JavaScript to access custom response headers named x-set-cookie and x-dd-b by including Access-Control-Expose-Headers: x-set-cookie, x-dd-b on non-preflight responses:
    • Documentation for Access-Control-Expose-Headers

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Headers: x-datadome-clientid

Access-Control-Expose-Headers: x-set-cookie, x-dd-b

How to use sessionByHeader to work around domain restrictions on cookies

• Add sessionByHeader: true to the window.ddoptions configuration object to enable it.

🚧

Matching with ajaxListenerPath and ajaxListenerPathExclusion

This option is only applied on requests with a URL that matches with the configuration defined on the ajaxListenerPath and ajaxListenerPathExclusion options.

withCredentials

📘

Why should I use withCredentials?

By default, when an application makes cross-origin requests with XMLHttpRequest or Fetch, the request will not include credentials, i.e. cookies and authorization tokens.

Since protected requests must include the datadome cookie to ensure optimal protection, this option might be required for requests that ignore it.

Prerequisites for withCredentials

• You must configure your preflight responses to allow credentials by including Access-Control-Allow-Credentials: true in their headers
  • Documentation for Access-Control-Allow-Credentials

Access-Control-Allow-Origin: https://example.com
Access-Control-Allow-Credentials: true

🚧

Avoid using wildcards on Access-Control-Allow-Origin

Returning Access-Control-Allow-Origin: * is not allowed when using Access-Control-Allow-Credentials: true.

A single origin must be returned, as seen in the previous example.

• Documentation for Access-Control-Allow-Origin

How to use withCredentials to enforce cookies on cross-origin requests

• Add withCredentials: true to the window.ddoptions configuration object to enable it.

It will be equivalent to enabling the withCredentials option on XMLHttpRequest instances, and the credentials option for Fetch calls.

🚧

Matching with ajaxListenerPath and ajaxListenerPathExclusion

This option is only applied on requests with a URL that matches with the configuration defined on the ajaxListenerPath and ajaxListenerPathExclusion options.