jsd docs refresh

patriciasantaana · patriciasantaana · commit 0114e1165b88 · 2025-07-09T11:13:05.000-07:00
diff --git a/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx b/src/content/docs/cloudflare-challenges/challenge-types/javascript-detections.mdx
@@ -2,7 +2,7 @@
 ---
 type: overview
 pcx_content_type: reference
-title: JavaScript detections
+title: JavaScript Detections
 sidebar:
   order: 3
 ---
@@ -11,35 +11,78 @@ import { Render, Tabs, TabItem } from "~/components"
 
 <Render file="javascript-detections-definition" />
 
-## Enable JavaScript detections
+<Render file="javascript-detections-process" />
 
-For Bot Fight Mode customers, JavaScript detections are automatically enabled and cannot be disabled.
+Refer to the steps below to enable and enforce JavaScript Detections.
 
-For Super Bot Fight Mode and Bot Management for Enterprise customers, JavaScript detections are optional.
+## 1. Enable JavaScript Detections
+
+For Bot Fight Mode customers, JavaScript Detections are automatically enabled and cannot be disabled.
+
+For Super Bot Fight Mode and Bot Management for Enterprise customers, JavaScript Detections are optional.
 
 <Render file="javascript-detections-enable" />
 
 For more details on how to set up bot protection, refer to the [Bots documentation](/bots/get-started/).
 
-## Enforcing execution of JavaScript detections
+## 2. Enforce execution of JavaScript Detections
 
 <Render file="javascript-detections-implementation" />
 
-<Render file="cf-clearance-cookie" />
+Refer to the [WAF documentation](/waf/custom-rules/create-dashboard/) for more information on creating a custom rule.
+
+## API
+
+Use JavaScript Detections API for more granular control over when and where JavaScript Detections are injected on your website, as well as an option for callback handling (for logging or other additional actions).
+
+You can explicitly add a script reference to `jsd/api.js` and your own code calling `window.cloudflare.jsd.executeOnce` on specific HTML pages of your website.
+
+:::warning
+It is not recommended to combine both approaches (zone-wide toggle and the manual injection). If you want to selectively deploy JavaScript Detections only on certain pages, disable JavaScript Detections via the Cloudflare dashboard and use the JSD API exclusively.
+:::
+
+The following script must be added to every page that you wish to have JavaScript Detections enabled:
+
+```js wrap
+<script>
+ 
+function jsdOnload(){
+  window.cloudflare.jsd.executeOnce(
+    {
+      callback: function(result){
+        console.log('jsd outcome', result);
+    }
+  );
+}
+</script>
+<script src="/cdn-cgi/challenge-platform/scripts/jsd/api.js?onload=jsdOnload" async>
+```
+
+## Considerations
+
+- While JavaScript Detections further refine the [bot score](/bots/concepts/bot-score/), it is not a very significant effect. 
+- If the JavaScript Detections injection or execution fails and `cf.bot_management.js_detection.passed` = `false`, a separate Bot Management heuristic can still yield a 1 or higher bot score, independent of JavaScript Detections.
+- Even if JavaScript Detections pass, the final bot score may still be 1 due to other detection heuristics (for example, known malicious IP, signature detection, and more), resulting in `js_detection.passed` = `true`, but `score` = 1.
 
 ## Limitations
 
 ### If you enabled Bot Management before June 2020
 
-Customers who enabled Enterprise Bot Management before June 2020 do not have JavaScript detections enabled by default (unless specifically requested). These customers can still enable the feature in the Cloudflare dashboard.
+Customers who enabled Enterprise Bot Management before June 2020 do not have JavaScript Detections enabled by default (unless specifically requested). These customers can still enable the feature in the Cloudflare dashboard.
+
+### If it is the first request to your website
+
+The first request from a new client to your website or application will generally not have JSD data (`cf.bot_management.js_detection.passed` = `false`). This is because Cloudflare needs at least one HTML request before injecting JavaScript detection and issuing the `cf-clearance` cookie. 
+
+Subsequent requests can include a `cf-clearance` cookie if JavaScript ran successfully.
 
 ### If you have a Content Security Policy (CSP)
 
 <Render file="javascript-detections-csp" />
 
 :::caution[Warning]
 
-JavaScript detections are not supported with `nonce` set via `<meta>` tags. 
+JavaScript Detections are not supported with `nonce` set via `<meta>` tags. 
 :::
 
 ### If you have ETags
diff --git a/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx b/src/content/docs/cloudflare-challenges/concepts/how-challenges-work.mdx
@@ -11,15 +11,15 @@ Challenges can be issued in three primary ways depending on which Cloudflare pro
 | Product | Challenge type(s) |
 | --- | --- |
 | [WAF](/waf/) ([custom rules](/waf/custom-rules/), [rate limiting rules](/waf/rate-limiting-rules/), [IP access rules](/waf/tools/ip-access-rules/)) | [Interstitial Challenge Page](/cloudflare-challenges/challenge-types/challenge-pages/) |
-| [Bot Management](/bots/get-started/bot-management/) | [JavaScript detection](/bots/additional-configurations/javascript-detections/) |
+| [Bot Management](/bots/get-started/bot-management/) | [JavaScript Detection](/bots/additional-configurations/javascript-detections/) |
 | [Bot Fight Mode](/bots/get-started/bot-fight-mode/), [Super Bot Fight Mode](/bots/get-started/super-bot-fight-mode/) | [Interstitial Challenge Page](/cloudflare-challenges/challenge-types/challenge-pages/) |
 | [Turnstile](/turnstile/) | Embedded widget |
 | [HTTP DDoS attack protection](/ddos-protection/managed-rulesets/http/) | Any Challenge |
 | [Under Attack Mode](/fundamentals/reference/under-attack-mode/) | [Managed Challenge](/cloudflare-challenges/challenge-types/challenge-pages/#managed-challenge-recommended) |
 
 Challenge Pages and Turnstile rely on the same underlying mechanism to issue Challenges to your website or application's visitors.
 
-JavaScript detections support Cloudflare's Enterprise Bot Management. While it still relies on client-side detections, JavaScript detections function using a more performant challenge logic than Challenge Pages or Turnstile.
+JavaScript Detections support Cloudflare's Enterprise Bot Management. While it still relies on client-side detections, JavaScript Detections function using a more performant challenge logic than Challenge Pages or Turnstile.
 
 ---
 
@@ -29,7 +29,7 @@ Refer to the following pages for more information on the different challenge typ
 
 - [Interstitial Challenge Pages](/cloudflare-challenges/challenge-types/challenge-pages/)
 - [Turnstile](/cloudflare-challenges/challenge-types/turnstile/)
-- [JavaScript detections](/cloudflare-challenges/challenge-types/javascript-detections/)
+- [JavaScript Detections](/cloudflare-challenges/challenge-types/javascript-detections/)
 
 ---
 
diff --git a/src/content/partials/cloudflare-challenges/javascript-detections-csp.mdx b/src/content/partials/cloudflare-challenges/javascript-detections-csp.mdx
@@ -5,8 +5,11 @@
 
 import { GlossaryTooltip } from "~/components"
 
-If you have a <GlossaryTooltip term="content security policy (CSP)">Content Security Policy (CSP)</GlossaryTooltip>, you need to take additional steps to implement JavaScript detections:
+If you have a <GlossaryTooltip term="content security policy (CSP)">Content Security Policy (CSP)</GlossaryTooltip>, you need to take additional steps to implement JavaScript Detections:
 
-* Ensure that anything under `/cdn-cgi/challenge-platform/` is allowed. Your CSP should allow scripts served from your origin domain (`script-src self`).
-* If your CSP uses a `nonce` for script tags, Cloudflare will add these nonces to the scripts it injects by parsing your CSP response header.
-* If your CSP does not use `nonce` for script tags and **JavaScript Detection** is enabled, you may see a console error such as `Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self'". Either the 'unsafe-inline' keyword, a hash ('sha256-b123b8a70+4jEj+d6gWI9U6IilUJIrlnRJbRR/uQl2Jc='), or a nonce ('nonce-...') is required to enable inline execution.` We highly discourage the use of `unsafe-inline` and instead recommend the use CSP `nonces` in script tags which we parse and support in our CDN.
+- Ensure that anything under `/cdn-cgi/challenge-platform/` is allowed. Your CSP should allow scripts served from your origin domain (`script-src self`).
+- For `nonce` script tags:
+
+    - If your CSP uses a `nonce` for script tags, Cloudflare will add these nonces to the scripts it injects by parsing your CSP response header.
+
+    - If your CSP does not use `nonce` for script tags and **JavaScript Detections** are enabled, you may see a console error such as `Refused to execute inline script because it violates the following Content Security Policy directive: "script-src 'self'". Either the 'unsafe-inline' keyword, a hash ('sha256-b123b8a70+4jEj+d6gWI9U6IilUJIrlnRJbRR/uQl2Jc='), or a nonce ('nonce-...') is required to enable inline execution.` We highly discourage the use of `unsafe-inline` and instead recommend the use CSP `nonces` in script tags which we parse and support in our CDN.
diff --git a/src/content/partials/cloudflare-challenges/javascript-detections-definition.mdx b/src/content/partials/cloudflare-challenges/javascript-detections-definition.mdx
@@ -4,12 +4,6 @@
 
 import { Markdown } from "~/components"
 
-JavaScript detections are another method that help Cloudflare identify bot requests.
+JavaScript Detections is a type of Challenge separate from Cloudflare’s Challenge Pages or Turnstile. Javascript Detections help Cloudflare’s [bot solutions](/bots/) identify automated requests. 
 
-These detections are implemented via a lightweight, invisible JavaScript code snippet that follows Cloudflare’s [privacy standards](https://www.cloudflare.com/privacypolicy/). JavaScript is injected only in response to requests for HTML pages or page views, excluding AJAX calls. API and mobile app traffic is unaffected. JavaScript detections have a lifespan of 15 minutes. However, the code is injected again before the session expires. After page load, the script is deferred and utilizes a separate thread (where available) to ensure that performance impact is minimal.
-
-The snippets of JavaScript will contain a source pointing to the challenge platform, with paths that start with `/cdn-cgi/challenge-platform/...`
-
-:::note
-The information in JavaScript detections which populates `js_detection.passed` is stored in the `cf_clearance` cookie.
-:::
+While Challenge Pages and Turnstile rely on client-side signals to determine the authenticity of a request, Bot Management’s JavaScript Detections rely on network-side signals and run on every single request made to your website. 
diff --git a/src/content/partials/cloudflare-challenges/javascript-detections-implementation.mdx b/src/content/partials/cloudflare-challenges/javascript-detections-implementation.mdx
@@ -3,32 +3,25 @@
 
 ---
 
-Once you enable JavaScript detections, you can use the `cf.bot_management.js_detection.passed` field in [WAF custom rules](/waf/custom-rules/) (or the `request.cf.botManagement.jsDetection.passed` variable in [Workers](/workers/)).
+Once you enable JavaScript detections, you must use the `cf.bot_management.js_detection.passed` field to create [WAF custom rules](/waf/custom-rules/) (or the `request.cf.botManagement.jsDetection.passed` variable in [Workers](/workers/)).
 
-When adding this field to WAF custom rules, use it:
-
-* On endpoints expecting browser traffic (avoiding native mobile applications or websocket endpoints).
-* After a user's first request to your application (Cloudflare needs at least one HTML request before injecting JavaScript detection).
-* With the [Managed Challenge action](/cloudflare-challenges/challenge-types/challenge-pages/#managed-challenge-recommended), because there are legitimate reasons a user might not have passed a JavaScript detection challenge (network issues, ad blockers, disabled JavaScript in browser, native mobile apps).
+When adding this field to WAF custom rules, it is used on endpoints expecting browser traffic (avoiding native mobile applications or websocket endpoints), after a user's first request to your application (Cloudflare needs at least one HTML request before injecting JavaScript detection), and with the Managed Challenge action, because there are legitimate reasons a user might not have passed a JavaScript Detection challenge (network issues, ad blockers, disabled JavaScript in browser, native mobile applications).
 
 ### Prerequisites
 
-* You must have JavaScript detections enabled on your zone.
-* You must have [updated your Content Security Policy headers](/cloudflare-challenges/challenge-types/javascript-detections/#if-you-have-a-content-security-policy-csp) for JavaScript detections.
-* You must not run this field on websocket endpoints.
-* You must use the field in a custom rules expression that expects only browser traffic.
-* The action should always be a managed challenge in case a legitimate user has not received the challenge for network or browser reasons.
-* The path specified in the rule builder should never be the first HTML page a user visits when browsing your site.
-
-`cf.bot_management.js_detection.passed` is used to indicate that a request has a Bot Management cookie present with a JavaScript detection value indicating it submitted the JavaScript detection test, and received a likely human scoring result.
+- You must have JavaScript detections enabled on your zone.
+- You must have [updated your Content Security Policy headers](/cloudflare-challenges/challenge-types/javascript-detections/#if-you-have-a-content-security-policy-csp) for JavaScript detections.
+- You must not run this field on websocket endpoints.
+- You must use the field in a custom rules expression that expects only browser traffic.
+- The action should always be a managed challenge in case a legitimate user has not received the challenge for network or browser reasons.
+- The path specified in the rule builder should never be the first HTML page a user visits when browsing your site.
 
 The `cf.bot_management.js_detection.passed` field should never be used in a WAF custom rule that matches a visitor's first request to a site. It is necessary to have at least one HTML request before Cloudflare can inject JavaScript detection.
 
-```js title="Example with Workers"
+```js title="Example"
 "botManagement": {
-"jsDetection":
-
-{ "passed": false }
-,
-},
-```
+  "jsDetection": {
+    "passed": false
+  }
+}
+```
diff --git a/src/content/partials/cloudflare-challenges/javascript-detections-process.mdx b/src/content/partials/cloudflare-challenges/javascript-detections-process.mdx
@@ -0,0 +1,30 @@
+---
+{}
+---
+
+import { Markdown } from "~/components";
+
+## Process 
+
+JavaScript Detections are implemented on your website via a lightweight, invisible JavaScript code snippet that follows Cloudflare's [privacy standards](https://www.cloudflare.com/privacypolicy/). 
+
+JavaScript is injected only in response to requests for HTML pages or page views, excluding AJAX calls. API and mobile application traffic is unaffected. 
+
+JavaScript Detections have a lifespan of 15 minutes. However, the code is injected again before the session expires. After page load, the script is deferred and utilizes a separate thread (where available) to ensure that performance impact is minimal. The snippets of JavaScript will contain a source pointing to the Challenge Platform, with paths that start with `/cdn-cgi/challenge-platform/…`
+
+Once the JavaScript Detection is injected on the HTML page, the visitor's browser will run the JavaScript code snippet and a `cf-clearance` cookie is issued to the visitor. The information in JavaScript Detections is stored in the `cf-clearance` cookie and is used to populate `js_detection.passed`.
+
+- If the visitor is verified and a cf-clearance cookie is issued, it will contain the outcome: `cf.bot_management.js.detection.passed` = `true`
+- If the verification fails, the cookie with contain the outcome: `cf.bot_management.js.detection.passed` = `false` 
+
+:::note
+The `cf-clearance` cookie cannot exceed the maximum size of 4096 bytes.
+:::
+
+:::warning
+Enforcement against bots do **not** occur even if the cookie is flagged false. 
+
+You must enable JavaScript Detections and then create a custom WAF rule using the `cf.bot_management.js.detection.passed` field to block or challenge a failed request.
+:::
+
+When the visitor encounters a WAF custom rule on your website, the rule will check the outcome of the `cf-clearance` cookie. The outcome of the `cf-clearance` cookie determines whether the request passes, or is blocked or challenged.
