Skip to main content

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.

The impid match gate cross-references impression IDs between the bid request and the bid response. Every bid in the response carries an impid field that identifies which impression slot it is competing for. If that impid does not appear in the request’s imp[].id array, the bid references a slot that was never offered — a protocol violation that can trigger DSP penalties and waste auction capacity.

​
Usage

import { createEngine, gates } from "@pecta/core";

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

​
What the gate checks

The gate reads imp[].id from ctx.input (the request) and iterates over every seatbid[].bid[] in ctx.output (the response). For each bid it checks:
  1. Missing impid — the bid.impid field is absent or not a string → fails with "bid missing impid"
  2. Unknown impid — the bid.impid value is not in the set of request impression IDs → fails with "bid impid not present in request"
When the gate fails, it includes the full set of valid impression IDs in details.requestImps so you can diagnose the mismatch: 
{
  "name": "rtb.impid-match",
  "passed": false,
  "reason": "bid impid not present in request",
  "details": {
    "requestImps": ["imp-abc123", "imp-def456"]
  },
  "latency_ms": 1
}

​
Skipping behaviour

The gate skips gracefully — returning passed: true, skipped: true — in two situations:
  • The request has no imp objects (no impression IDs to validate against)
  • The response contains no seatbid[].bid[] entries (no bids to check)
An empty response is not treated as a failure by this gate. Use a separate content gate if you want to enforce that a bidder must always return at least one bid.

​
Example: failing bid

{
  "id": "response-001",
  "seatbid": [
    {
      "bid": [
        {
          "id": "bid-1",
          "impid": "imp-UNKNOWN",
          "price": 1.50,
          "adomain": ["advertiser.com"]
        }
      ]
    }
  ]
}
The request only offered impression imp-abc123. The bid references imp-UNKNOWN, so the gate fails immediately on the first mismatched bid.

​
Options

​
name
string
default:"rtb.impid-match"
Override the gate’s name in evaluation results and telemetry.