Detection Tag - Event Mitigation Mode for Single Page Applications

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.

Single Page Application

This guide describes how to set up the Detection Tag in Event Mitigation mode for a Single Page Application (SPA). This means that the web pages are rendering on the front-end dynamically and navigation between pages does not require a full reload of the website by the server.

If you have a static website where every page load requires a full reload from the server, then you should go to the Event Mitigation Mode Setup Instructions for Static Applications.

Mitigation API

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

Setup

When configuring the Detection tag for a Single Page Application, the tag exposes a global API on window.$$$ that allows you to protect any event that your application handles.

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
  • spa: Loads SPA version of tag, value always 1

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>window.$$$={start:function(){return{report:function(){return{then:function(fn){fn({})}}},stop:function(){}}}};</script>
<script src="https://s.update.example.com/ag/123456/clear.js?
  ci=123456
  &dt=1234567890123456789012
  &mo=2
  &pd=acc
  &spa=1
  &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

Inline "Stub" Tag

We recommend loading an inline script tag with a stubbed API directly before loading the Detection Tag. The purpose of the stub is to prevent any functionality from breaking if our tag fails to load for any reason. In that case, the stub API acts as a harmless pass-through, doing nothing.

Usage

For Multi-Event usage information, refer to Multi-Event Single Page Application Usage Instructions.

Deprecated: For Single-Event usage information, refer to Single Page Application Usage Instructions.

Tag Placement

We recommend loading the tag directly after loading the stub API. The tag must fully load before accessing the window.$$$.start function.

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 in size.

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.