# Bot Detection and Filtering

> Filter bot traffic in Ours Privacy using user-agent detection or Advanced Bot Detection, an algorithm-driven behavioral scoring system you can apply at the source, globally, or per destination.

Source: https://docs.oursprivacy.com/docs/bot-detection

Ours Privacy provides two tiers of bot detection: basic **user-agent filtering** and **Advanced Bot Detection**, an opt-in, algorithm-driven scoring system that assigns every event a `bot_score` (0–100) based on behavioral signals. Because the score is stored as an event property, you can filter bots at the source level, globally across destinations, or selectively per destination.

***

## Bot Filtering Methods

Choose a **Bot Filtering Method** in **Sources > \[Your Source] > Settings**.

![The Bot Filtering Method setting on a Web SDK source with Threshold selected, a Bot Score Threshold of 70, and a summary of the Allow, Block, and Threshold modes](https://docs.oursprivacy.com/img/bot-detection/bot-detection-img-1.jpg)

### Allow (Default)

All traffic passes through. Bot events are still flagged and scored, but nothing is filtered. Use this when you want to analyze bot traffic patterns or handle filtering downstream.

### Block

Known bots identified by user-agent string (`is_bot: true`) are filtered out. These events don't appear in Recent Events, aren't dispatched to destinations, and don't count toward your MTUs.

No SDK changes required. Use Block for simple, zero-configuration bot filtering.

### Threshold (Advanced Bot Detection)

Events are scored using Ours Privacy's behavioral scoring algorithm. Any event with a `bot_score` at or above your configured threshold is filtered out, with the same effect as Block.

* **Default threshold: 70:** conservative, prefers fewer false positives over aggressive filtering
* Threshold is configurable per source (0–100)
* Lower thresholds filter more aggressively; higher thresholds are more lenient

To get the most accurate scores, enable [Advanced Bot Detection](#enabling-advanced-bot-detection) in your SDK. Without SDK signals, scoring falls back to user-agent analysis only.

***

## Advanced Bot Detection

Advanced Bot Detection is an opt-in feature that uses a behavioral scoring algorithm to evaluate each event on a 0–100 scale. The algorithm combines user-agent analysis with passive behavioral signals collected by the SDK, including mouse, scroll, click, keyboard, and timing patterns, to distinguish human visitors from automated traffic.

The algorithm evaluates multiple behavioral dimensions independently and in combination. Behavioral signals alone can identify bots that disguise their user-agent string, so no UA detection is required.

Signals are processed server-side. Raw signal data is stripped after scoring and never persisted.

### Enabling Advanced Bot Detection

**Via SDK:** pass `bot_detection: true` in your init options:

```javascript
// Copy-paste snippet
ours('init', 'YOUR_TOKEN', { bot_detection: true });
```

```javascript
// NPM SDK
import ours from '@oursprivacy/cdp-sdk';

ours.init('YOUR_TOKEN', { bot_detection: true });
```

**Via Ours Privacy Tag Manager or GTM:** enable the **Advanced Bot Detection** checkbox in your Init tag settings. No code changes required.

All signal collection is passive and throttled. When disabled (the default), no signal code runs and no additional data is sent.

***

## Filtering at Multiple Layers

Because `bot_score` is an event property, you're not limited to filtering at the source. You can stop bots at whichever layer makes sense for your use case:

1. **Block at the source.** Set Bot Filtering Method to Block or Threshold. Bots are dropped before reaching any destination.
2. **Block globally with Data Governance.** Leave Bot Filtering Method as Allow and create a [Global Data Governance](https://docs.oursprivacy.com/docs/global-data-governance) rule that stops dispatch when `event.bot_score >= 70`. This keeps the raw data in your warehouse while preventing bots from reaching ad and analytics platforms.
3. **Block at individual destinations.** Add a stop condition to a destination's mapper: `event.bot_score >= 70`. Each destination can have its own threshold.

***

## Event Properties

Every event receives the following bot detection properties:

| Property           | Location            | Type             | Description                                                   |
| ------------------ | ------------------- | ---------------- | ------------------------------------------------------------- |
| `is_bot`           | `defaultProperties` | `boolean`        | `true` if user-agent matches a known bot                      |
| `bot_score`        | `eventProperties`   | `number` (0–100) | Algorithm-driven bot likelihood score                         |
| `bot_category`     | `eventProperties`   | `string`         | `human`, `likely_human`, `suspicious`, `likely_bot`, or `bot` |
| `bot_signals_used` | `eventProperties`   | `string[]`       | Which signal categories contributed to the score              |

| Score Range | Category       | Description                          |
| ----------- | -------------- | ------------------------------------ |
| 0–10        | `human`        | Confident the traffic is human       |
| 11–30       | `likely_human` | Probably human, minor anomalies      |
| 31–50       | `suspicious`   | Some bot-like characteristics        |
| 51–75       | `likely_bot`   | Strong indicators of automation      |
| 76–100      | `bot`          | Very likely automated or a known bot |

***

## Best Practices

* Start with **Allow** to observe your bot traffic before filtering
* Enable **Advanced Bot Detection** in your SDK for the most accurate scoring
* Use **Threshold mode** (default: 70) for balanced filtering
* Use **Global Data Governance rules** to block bots from ad platforms while preserving data in your warehouse
