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 IDdt
: Tag IDmo
: Tag mode. Value is always2
for Event Mitigation modepd
: Product key, alwaysacc
for BotGuard for Applicationsspa
: Loads SPA version of tag, value always1
Optional Fields
ap
: App IDck
: Cookie IDdv
: Device IDsi
: Site IDui
: User IDc1 - c10
: Custom fieldsr1 - 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.