Document botstopper_utm_referer_enabled setting

docs/hypernode-platform/botstopper/how-to-use-botstopper.md

@@ -1,8 +1,8 @@
 ---
 myst:
   html_meta:
-    description: Learn how to enable Botstopper, choose an AI policy, and write custom
-      Botstopper policies on Hypernode.
+    description: Learn how to enable Botstopper, choose an AI policy, preserve UTM
+      attribution after a challenge, and write custom Botstopper policies on Hypernode.
     title: How to use Botstopper on Hypernode | Hypernode
 ---
 
@@ -72,6 +72,26 @@ Use `aggressive` if you want the strictest AI blocking. Use `moderate` if you wa
 
 Some AI crawlers also require `robots.txt` rules before they respect your opt-out. Botstopper blocks requests at the webserver layer, but `robots.txt` is still useful for crawlers that require policy signals there. See the [Magento 1 robots.txt](../../ecommerce-applications/magento-1/how-to-create-a-robots-txt-for-your-magento-1-shop.md) or [Magento 2 robots.txt](../../ecommerce-applications/magento-2/how-to-create-a-robots-txt-for-magento-2-x.md) articles if you need to configure one.
 
+## Preserve UTM Attribution After a Challenge
+
+When a visitor passes a Botstopper challenge, the browser lands on your shop with the challenge page as the technical referrer. This breaks referrer attribution in client-side analytics tools such as Plausible or GA4. Botstopper restores the original `Referer` header on the request it forwards to your shop, but tools that read `document.referrer` or UTM tags cannot be corrected that way.
+
+To keep attribution working for those tools, Botstopper can append the original external referer host to the post-challenge redirect URL as `utm_source` and `utm_medium` query parameters. For example, a visitor coming from `https://www.google.com/search?q=shoes` lands on `https://example.com/?utm_source=www.google.com&utm_medium=referral` after passing the challenge.
+
+This behavior is enabled by default. Disable it with:
+
+```bash
+hypernode-systemctl settings botstopper_utm_referer_enabled False
+```
+
+Enable it again with:
+
+```bash
+hypernode-systemctl settings botstopper_utm_referer_enabled True
+```
+
+Botstopper only adds these parameters when the original referer is an external domain and the redirect URL does not already contain UTM parameters.
+
 ## How Botstopper Handles Requests
 
 Botstopper evaluates policy rules from top to bottom. A rule can allow, deny, challenge, or weigh a request.

docs/hypernode-platform/tools/how-to-use-the-hypernode-systemctl-cli-tool.md

@@ -27,6 +27,7 @@ To see which values you can set and which values they are allowed to have take a
 | **block_bad_ips_enabled**<br/><sub>Blocks abusive IPs with high AbuseIPDB.com confidence scores</sub>                                                           | True          | True, False                                                                                                                                 |
 | **botstopper_ai_policy**<br/><sub>Choose how strict Botstopper should be for AI crawlers and AI clients</sub>                                                   | aggressive    | aggressive, moderate, permissive                                                                                                            |
 | **botstopper_enabled**<br/><sub>Enable Botstopper bot protection</sub>                                                                                          | False         | True, False                                                                                                                                 |
+| **botstopper_utm_referer_enabled**<br/><sub>Pass on the external referer as<br />utm_source and utm_medium after a challenge</sub>                              | True          | True, False                                                                                                                                 |
 | **composer_version**<br/><sub>Change the Composer version</sub>                                                                                                 | 2.x           | 1.x, 2.2, 2.6, 2.7, 2.8, 2.x                                                                                                                |
 | **disable_optimizer_switch**<br/><sub>Disable the optimizer switch</sub>                                                                                        | False         | True, False                                                                                                                                 |
 | **elasticsearch_enabled**<br/><sub>Enable Elasticsearch</sub>                                                                                                   | False         | True, False                                                                                                                                 |
@@ -119,6 +120,7 @@ If an invalid value is provided you will be notified of this during the setting
 
 - `botstopper_enabled`: Enables Botstopper bot protection.
 - `botstopper_ai_policy`: Configures the Botstopper AI policy. Possible values are `aggressive`, `moderate`, and `permissive`.
+- `botstopper_utm_referer_enabled`: Passes on the original external referer as `utm_source` and `utm_medium` query parameters after a Botstopper challenge. Enabled by default.
 
 See [How to Use Botstopper on Hypernode](../botstopper/how-to-use-botstopper.md) for details about enabling Botstopper, configuring it per vhost, and writing custom policies.