> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pecta.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# RTB adomain gate: reject placeholder advertiser domains

> Detects placeholder, test, and malformed advertiser domains in bid responses, ensuring every bid carries a legitimate and properly formatted adomain.

The adomain verify gate inspects the `adomain` array on every bid in the response. Advertisers are required by OpenRTB to declare which domains their creatives represent. Bidding agents that submit placeholder values like `example.com` or `advertiserdomain.com` — or that omit the field entirely — produce unusable signals for brand safety and supply chain auditing.

## Usage

```typescript theme={null}
import { createEngine, gates } from "@pecta/core";

const engine = createEngine({
  gates: [
    gates.rtb.tmaxGuard({ bufferMs: 15 }),
    gates.rtb.adomainVerify(),
    // ...
  ],
  timeout: 15,
});
```

## What the gate checks

For every bid in `seatbid[].bid[]`, the gate validates each entry in `bid.adomain`:

1. **Missing adomain** — the `bid.adomain` array is empty and `requireAdomain` is `true` → fails with `"bid has no adomain"`
2. **Placeholder domain** — the domain matches a known test/placeholder value (case-insensitive) → fails with `"placeholder adomain: <domain>"`
3. **Invalid format** — the domain does not match a valid hostname pattern → fails with `"invalid adomain format"`

## Built-in placeholder list

The following domains are always rejected:

```
advertiserdomain.com
example.com
example.org
example.net
test.com
placeholder.com
localhost
foo.com
bar.com
```

All comparisons are lowercased and trimmed before matching.

## Options

<ParamField path="requireAdomain" type="boolean" default="true">
  When `true`, any bid with an empty `adomain` array fails the gate. Set to `false` if your pipeline legitimately allows bids without declared advertiser domains.
</ParamField>

<ParamField path="extraPlaceholders" type="string[]">
  Additional domain strings to treat as placeholders. Values are lowercased before comparison, so `"TestDomain.COM"` and `"testdomain.com"` are equivalent.
</ParamField>

<ParamField path="name" type="string" default="rtb.adomain-verify">
  Override the gate's name in evaluation results and telemetry.
</ParamField>

## Example: failing bid

A bid agent under test that has not populated real advertiser data:

```json theme={null}
{
  "seatbid": [
    {
      "bid": [
        {
          "id": "bid-1",
          "impid": "imp-001",
          "price": 2.00,
          "adomain": ["advertiserdomain.com"]
        }
      ]
    }
  ]
}
```

The gate matches `advertiserdomain.com` against the built-in placeholder set and returns:

```json theme={null}
{
  "name": "rtb.adomain-verify",
  "passed": false,
  "reason": "placeholder adomain: advertiserdomain.com",
  "latency_ms": 1
}
```

## Adding your own placeholders

If your pipeline has internal test domains you want to block in production:

```typescript theme={null}
gates.rtb.adomainVerify({
  extraPlaceholders: ["internal-test.example", "staging.myco.com"],
})
```

<Warning>
  Setting `requireAdomain: false` disables the check for bids with an empty `adomain` array. Only do this if your downstream demand sources have confirmed they do not provide domain declarations.
</Warning>