Detection Tag - Event Mitigation Mode

The Event Mitigation mode (previously named Active mode) provides visibility into interactive events on your web application and mitigates any traffic that is automated or invalid. This integration type focuses exclusively on events occurring after the page load (e.g. account creation, authentication, commenting or liking, checking out, etc.) but does not monitor page views.

This integration type requires a backend, server-to-server call to the Mitigation API in order to retrieve a real-time decision that you can use to log or take action on bot interactions.

Static Website

This guide describes how to set up the Detection Tag in Event Mitigation 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 please view Event Mitigation Mode Setup Instructions for Single Page Applications.

Mitigation API

To fully implement Event Mitigation 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 Event Mitigation mode
  • 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

Below is an 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, improving bot detection efficacy.

Tag Size

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

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.