Signal Headers

Signal Headers enables the Detection Tag to protect API requests by injecting the signals into the Request header. By defining a set of rules, the Detection Tag seamlessly protects and provides great flexibility in configuring specific API requests.

To integrate with the Signal Headers version of the Detection Tag perform the following steps.

Warning

When introducing Signal Headers on a page please be sure to review the request rules (simple requests vs preflight request). If the page crosses origin without configuration of Access-Control-Allow-Origin it can break a previously functioning workflow. The page will throw an unexpected CORS error. Please read and be familiar with the following page prior to implementation of Signal Headers.

CORS

Setup

Required Fields

ci: Customer ID.
dt: Tag ID.
mo: Tag mode. Value should be 2.
pd: Product key, always acc for BotGuard for Applications.
spa: Sets SPA version of tag, value always 1.
sh: Enables the Signal Headers, value always 1.

Example Detection Tag

<script src="https://[domain]/2/[ci]/clear.js?ci=[ci]&dt=[dt]&pd=acc&mo=2&spa=1&sh=1"></script>

Interface

When configuring the Detection tag for Signal Headers, the tag exposes a configuration function on window.$$$.setHumanConfig. It is imperative to call this function immediately after you have loaded the Detection <script> tag.

The Configuration Object

The configuration for Signal Headers consists of an array of ProtectedRequestRules. This set of rules determine which Requests should have the signals injected in their headers.

Attributes
apiDomain (string)	The domain of the API endpoint to protect, must be a valid domain name with an exact match.
pathRegexes (array[RegExp])	An array of regular expressions to match the path of the Request and thus identify which paths to protect.

If you have multiple API domains you want to protect, you will need to add additional rules to protectedRequestRules.

Example configuration:

window.$$$.setHumanConfig({
  protectedRequestRules: [
    {
      apiDomain: "auth-domain.com",
      pathRegexes: [/login/, /signup/],
    },
    {
      apiDomain: "api-domain.com",
      pathRegexes: [/\/api\/collection\/\w+\/items/],
    },
  ],
});

This config will match these Request urls

https://auth-domain.com/login
https://auth-domain.com/signup
https://api-domain.com/api/collections/150/items

Examples

Vanilla JS

<html lang="en">
  <head>
    <script src="https://s.example.com/2/845155/clear.js?ci=845155&dt=1234567890123456789012&pd=acc&mo=2&spa=1&sh=1"></script>
    <script>
      if (window.$$$ && window.$$$.setHumanConfig) {
        window.$$$.setHumanConfig({
          protectedRequestRules: [
            {
              apiDomain: "your-domain.com",
              pathRegexes: [/.+/],
            },
          ],
        });
      }
    </script>
    <title>Login</title>
  </head>
  <body>
    <script>
      window.onload = function () {
        const loginForm = document.getElementById("login-form");
        loginForm.onsubmit = function (e) {
          e.preventDefault();
          const data = new URLSearchParams(new FormData(loginForm));
          fetch("https://your-domain.com/login", {
            method: "post",
            body: data,
          });
        };
      };
    </script>
    <h1>Log In</h1>
    <form id="login-form">
      <input id="username" type="text" name="username" />
      <input id="password" type="password" name="password" />
      <button type="submit">Log In</button>
    </form>
  </body>
</html>

In this example, you will notice that when a user submits this form, we make a call to the /login path. This will result in the OZ_TC, OZ_DT, and OZ_SG parameters being injected into the headers.

Note: OZ_DT and OZ_SG are chunked and will be indexed in the headers as OZ_DT0, OZ_DT1... and OZ_SG0, OZ_SG1, OZ_SG2....

If you are not using the NGINX integration. You will need to write a handler to concatenate the strings together.