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.

Single Page Application

This guide describes how to set up the Detection Tag in Active mode for Single Page Applications (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 Active Setup Instructions for Static Applications.

Mitigation API

To fully implement the Active 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 Active
  • pd: Product key, always acc for Application Integrity
  • 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

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, 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.