Detection Tag - Active

The Active mode helps you to understand and mitigate the bot traffic that is initiating interactive events on your web properties. This integration type ignores page loads and focuses exclusively on events that occur after the page loads, like logging in, liking posts, playing songs, etc. In addition, this integration type requires a backend, server-to-server call to the Mitigation API, which provides a bot decision in real-time that you can use to log or take action upon bot interactions.

Static Website

This guide describes how to set up the Detection Tag in Active mode for static websites. This means that the web pages are rendered on the server side, and there is no dynamic rendering of pages or navigation between them. The assumption is that every time a user clicks a link to another page of your website or submits a form, it does a full page reload before proceeding to the next page.

If you have a Single Page Application where pages are rendering dynamically on the front-end and navigation between pages does not fully reload the page, then you should go to the Active Setup Instructions for Single Page Applications.

Mitigation API

To fully implement the Active mode, the Mitigation API Integration must also be completed.

Setup

Tag Fields

Required Fields

  • ci: Customer ID
  • dt: Tag ID
  • mo: Tag mode. Value is always 2 for Active
  • pd: Product key, always acc for BotGuard for Applications

Optional Fields

  • ap: App ID
  • ck: Cookie ID
  • dv: Device ID
  • si: Site ID
  • ui: User ID
  • c1 - c10: Custom fields
  • r1 - r10: Reporting fields

Field Index

For detailed information on the full set of Detection Tag fields, refer to the Detection Tag Field Index.

Tag Example

Example JavaScript Detection tag with populated values:


<script src="https://s.update.example.com/ag/123456/clear.js?
  ci=123456
  &dt=1234567890123456789012
  &mo=2
  &pd=acc
  &ap=com.example.Example <!-- in app only -->
  &ck=ddeedb6f4adf80dd2d8b0eb81c69da13
  &dv=c3f927f4-3ef9-4b53-8887-d794c4daea82 <!-- in app only -->
  &si=xyz1234
  &ui=04a1ad8a40e296df0d385e46c3796cd3
  &c1=v123
  &c2=x987
  &r1=y314"></script>

Tag Context

Hidden Field Injection

When the user submits a protected form, the Detection Tag injects the following three hidden input fields into the form:


<input type="hidden" name="OZ_TC" value="..."/>
<input type="hidden" name="OZ_DT" value="..."/>
<input type="hidden" name="OZ_SG" value="..."/>

The hidden input field values need to be forwarded to the Mitigation API according to the following field mapping:


OZ_TC -> session
OZ_DT -> datatoken
OZ_SG -> payload

Tag Placement

It is critical that the JavaScript Detection Tag is placed in the same context as the element being protected (e.g. form, button).

Execution Priority

The script should execute at page load time. If the protected element performs a postback (whether it causes a page reload or not), the script must be loaded before the postback takes place to protect the form submission.

Synchronous Loading

We have purposely omitted the async attribute from the script tags to ensure that the tag loads as early as possible. This enables the tag to capture more signals from the browser environment, which improves bot detection efficacy.

Tag Size

The initial JavaScript payload is 2KB ~ 4KB, followed by the main payload that is ~40KB. Postbacks are made one to a few times, and are generally a few hundred Bytes.

JavaScript Required

For the majority of use cases, JavaScript is required for effective detection, and mitigation. Our solution assumes that visitors to your online properties have JavaScript enabled.