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 any API request with great flexibility in configuring specific API requests.

To integrate with the Signal Headers version of the Detection Tag.

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]/pagespeed.js?ci=[ci]&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 exact match
pathRegexes array[RegExp] An array of regular expressions to match the path of the Request to add specificity to 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/static/5.0.0/pagespeed.js?dt=1234567890123456789012&psv=5.0.0&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 the /login path. You should see that in the network request, you will see the that the OZ_TC, OZ_DT, and OZ_SG params 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.