# Trillboards

> 757,000+ screens reachable through Trillboards and 29,000+ screens registered on our own network. Agencies, brands and their AI agents find, book and measure digital out-of-home campaigns here, with signed proof of play for every delivered ad and audience data measured at the screen.

## What Trillboards sells, and to whom

- Advertisers, agencies and buyer agents book screens: with one MCP call (AdCP `create_media_buy`), through programmatic deals over OpenRTB, or in the campaign planner with Stripe checkout.
- Measurement buyers get signed proof of play, attribution and attention metrics for the campaigns they run.
- Data buyers license audience and movement datasets through the Data API.
- Screen owners connect their screens with the Partner API and SDK and earn a revenue share on every paid play.

## Try it with no key

Call these on `https://api.trillboards.com/mcp` with no Authorization header:

- `get_products`: send a brief in plain language ("coffee drinkers near gyms in Austin, $5,000") and read back real screens, formats and prices, with the hours people are in front of each screen and the dwell and gaze measured there.
- `get_pricing`, `get_adcp_capabilities`, `list_creative_formats`: what we charge, what a buy can do, and the creative sizes the screens play.
- `list_endpoints`, `describe_endpoint`, `validate_request`, `list_error_codes`, `query_changelog`: the HTTP API, described by the server that runs it.
- Network reads such as `get_signals` (the audience signals the network senses) answer with no key while the server lists them as open: `authentication.openTools` in https://api.trillboards.com/mcp/server-card is the current list. A keyed tool's 401 carries `error.data.next_steps`: `register_partner`, REST registration, and the advertiser server for a person who will pay.

Plain HTTP answers the same questions: `GET https://api.trillboards.com/api/discover` lists every operation with its credential and agent affordances, and `https://api.trillboards.com/openapi.json` is the OpenAPI index.

## Get a sandbox key in one call

Call `register_partner` on `https://api.trillboards.com/mcp` with `company_name` and `email`: it always returns a sandbox key (send no `sandbox` argument; the tool takes none). Or `POST https://api.trillboards.com/v1/partner/agent/register` with `{"agent_type": "dsp_agent", "name": "...", "email": "...", "company": "...", "sandbox": true}`. The key comes back once. Every keyed tool answers with it: media buys validate end to end and return `sandbox: true`, and nothing serves, bills or pays a venue. When you are ready to buy, register at that endpoint with an email the sandbox account does not hold and leave out `"sandbox"`.

## Connect

Claude Code:
```
claude mcp add --transport http trillboards https://api.trillboards.com/mcp
claude mcp add --transport http trillboards https://api.trillboards.com/mcp --header "Authorization: Bearer $TRILLBOARDS_API_KEY"
```

Cursor (one click, or add the same `url` to `~/.cursor/mcp.json`):
```
cursor://anysphere.cursor-deeplink/mcp/install?name=trillboards&config=eyJ1cmwiOiJodHRwczovL2FwaS50cmlsbGJvYXJkcy5jb20vbWNwIn0=
```

VS Code:
```
code --add-mcp '{"name":"trillboards","type":"http","url":"https://api.trillboards.com/mcp"}'
```

Campaign planner (`https://api.trillboards.com/mcp/advertiser`): `search_ad_inventory` and `preview_campaign_plan` answer with no account; saving, booking and Stripe checkout sign in through OAuth (a client ID metadata document or dynamic client registration). Claude Code:
```
claude mcp add --transport http trillboards-planner https://api.trillboards.com/mcp/advertiser
```

## Discovery files

- MCP server card: https://api.trillboards.com/mcp/server-card (also /.well-known/mcp/server-card.json and /.well-known/mcp.json)
- AI catalog: https://api.trillboards.com/.well-known/ai-catalog.json
- OpenAPI index: https://api.trillboards.com/openapi.json
- API reference: https://api.trillboards.com/docs (guides: https://api.trillboards.com/docs/guides)
- Every reference and guide in one file: https://api.trillboards.com/llms-full.txt
- AdCP: https://api.trillboards.com/.well-known/adagents.json and https://api.trillboards.com/.well-known/brand.json

## Open data and RL environments

- Screen attention by city, venue and hour (CC BY 4.0): camera-measured attention, dwell and gaze in front of Trillboards screens by UTC hour, country, state, city and venue type, every row with its screens and camera windows. 475,282 rows, June 1 to October 11, 2026. Hugging Face: https://huggingface.co/datasets/snehdhruv/screen-attention-by-city-venue-hour · Kaggle: https://www.kaggle.com/datasets/snehdhruv/screen-attention-by-city-venue-hour
- The same data as files, one per city, with no key: `GET https://api.trillboards.com/v1/public/attention/TX/houston` returns every hourly row of Houston with all its counts (state and city as the registry names them or as slugs; `?country=` for a city outside the US), and `GET https://api.trillboards.com/v1/public/attention` is the index of every city with its rows and first and last hour. Each weekly vintage carries the same files as `json/attention/<country>/<state>/<city>.json` on both hubs.
- Recorded creative-feedback RL suite, its public evaluation run with every trace: https://hud.ai/jobs/a5c98ef7-7d39-4920-bd65-a0c521ef10f6
- Scored RL environment trials: https://api.trillboards.com/docs/guides/integrations/rl-environments.md

---

# Endpoint catalogue
# Every operation the four API references at /docs publish, one line each, the
# same set GET /api/discover serves (docs/openapi/bundled/*.json). This section
# is GENERATED: edit the specs and rebuild, never hand-edit between the
# markers. Regenerate with `cd trillboard-api && npm run build:openapi`.

# BEGIN-GENERATED endpoint-catalog
# AUTO-GENERATED FROM docs/openapi/bundled/*.json — DO NOT EDIT BY HAND. Run: cd trillboard-api && npm run build:openapi
#
# 432 operations across 4 surfaces. Each line: METHOD path — summary.
# Agent affordances (shown where the operation declares them): agent_safe (side-effect-free), idempotent (safe to retry), cost_tier (free | metered | paid).

## Trillboards Data API (data)
- GET /v1/data/aggregate — Aggregate audience analytics for a time window. (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/data/lookalike — Find screens with similar audience profiles. (agent_safe=true, idempotent=true, cost_tier=metered)
- POST /v1/data/query — Composable query DSL over approved datasets. (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/data/screens — List screens visible to the caller. (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/data/screens/{screenId}/audience — Real-time audience snapshot for a screen. (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/data/screens/{screenId}/history — Historical audience_metrics rows for a screen. (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/data/semantic-search — Similarity search over scene embeddings. (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/data/stats — Platform-wide counters. (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/data/stream — Server-Sent Events stream of live audience/observation events. (agent_safe=true, idempotent=false, cost_tier=metered)
- GET /v1/data/usage — API usage for the authenticated key (billing dashboard). (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/example/healthcheck — Example healthcheck (Phase 3 pipeline proof) (agent_safe=true, idempotent=true, cost_tier=free)

## Trillboards Demand API (demand)
- GET /openrtb — OpenRTB service root — endpoint catalogue (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/bidder/{connectionAlias}/bid — Bid on partner exchange inventory (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/bidder/{connectionAlias}/imp — Record billable partner exchange impression (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/bidder/{connectionAlias}/loss — Record partner exchange loss notice (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/bidder/{connectionAlias}/spec — Get partner exchange OpenRTB connection spec (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/bidder/{connectionAlias}/win — Record partner exchange win notice (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/health — OpenRTB service liveness probe (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/adpod/{token} — Resolve an ad-pod fulfilment token (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/analytics/events — Get event analytics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/analytics/impressions — Get impression analytics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/analytics/interactions — Get interaction analytics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/analytics/qr-scans — Get QR scan analytics (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v1/bandwidth-metric — Track bandwidth telemetry (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/bandwidth/analytics — Get aggregated bandwidth analytics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/bandwidth/screen-usage — Get per-screen bandwidth usage (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v1/bid — Process OpenRTB bid request (agent_safe=false, idempotent=false, cost_tier=free)
- POST /openrtb/v1/command-ack — Acknowledge a remote command issued to a screen (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/complete — Track completion event (agent_safe=false, idempotent=true, cost_tier=free)
- GET /openrtb/v1/creative-blocklist — Get creative blocklist (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/creative-history/{screenId} — Get creative history for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/creative-intelligence/experiments — List creative experiments (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v1/creative-intelligence/experiments — Create creative experiment (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/creative-intelligence/experiments/{id} — Get creative experiment (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /openrtb/v1/creative-intelligence/experiments/{id} — Pause, resume, or conclude creative experiment (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/creative-intelligence/experiments/{id}/analyze — Run statistical analysis for experiment (agent_safe=false, idempotent=true, cost_tier=free)
- GET /openrtb/v1/creative-intelligence/insights/{creativeId} — Get creative insights (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/creative-intelligence/performance/{creativeId} — Get creative performance metrics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/creative-intelligence/top — Get top-performing creatives (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/creative-review — List creative reviews (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/creative-review/stats — Get creative review statistics (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v1/creative-review/{creativeId}/block — Block creative (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/creative-review/{creativeId}/confirm — Confirm or override AI classification (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/creative-review/{creativeId}/unblock — Unblock creative (agent_safe=false, idempotent=true, cost_tier=free)
- GET /openrtb/v1/event — Track event via GET (pixel) (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/event — Track event via POST (JSON) (agent_safe=false, idempotent=true, cost_tier=free)
- DELETE /openrtb/v1/events/cleanup — Delete old events (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/heartbeat — Track registered-screen heartbeat and targeting identities (agent_safe=false, idempotent=true, cost_tier=free)
- GET /openrtb/v1/ima-player/{screenId} — HTML5 IMA SDK player harness for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v1/impression — Record impression (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/impressions/batch — Batch update impressions (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/inline/{token} — Resolve an inline-ad fulfilment token (agent_safe=false, idempotent=false, cost_tier=free)
- POST /openrtb/v1/interaction — Track ad interaction (agent_safe=false, idempotent=false, cost_tier=free)
- POST /openrtb/v1/interaction-summary — Submit interaction summary (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/omsdk/event — Record OMSDK event (GET image-beacon variant) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /openrtb/v1/omsdk/event — Record OMSDK event (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/omsdk/report/{campaignId} — Get OMSDK verification report (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v1/omsdk/session — Create OMSDK session (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/omsdk/session/{sessionId} — DEPRECATED — returns 410 Gone (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/omsdk/verification.js — Get OMSDK verification script (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v1/owned-direct/play-token/{screenId} — Mint signed lifecycle URLs for one Schedule direct play (agent_safe=false, idempotent=false, cost_tier=free)
- POST /openrtb/v1/performance — Track performance telemetry (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/pixel — Track impression via pixel (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/proof-of-play — Record MRC DOOH proof-of-play (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/vast — Generate a VAST document for an ad (agent_safe=false, idempotent=false, cost_tier=free)
- POST /openrtb/v1/vast-cache-metric — Track VAST cache metric (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/vast-cache/resolve/{creativeId} — Resolve a cached VAST creative by ID (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v1/vast-request — Track VAST request outcome (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/vast-request/analytics — Get VAST request analytics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/vast-test/{screenId} — Generate a test VAST response for a screen (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/vast-wrap/{provider}/{screenId} — Generate a partner-wrapped VAST response (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/vast/direct/{screenId}/{adid} — Serve a fixed first-party VAST tag for one booked ad and screen (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v1/vast/{partnerKey}/{screenId} — Generate VAST response on a partner-variant alias (agent_safe=false, idempotent=false, cost_tier=free)
- OPTIONS /openrtb/v1/vast/{partnerKey}/{screenId} — CORS preflight for the partner-variant VAST endpoint (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v1/vast/{partnerKey}/{screenId}/debug — Debug view of VAST waterfall for a partner-variant alias (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v1/viewability — Record viewability telemetry (agent_safe=false, idempotent=true, cost_tier=free)
- GET /openrtb/v1/win — Handle win notification (agent_safe=false, idempotent=true, cost_tier=free)
- GET /openrtb/v1/win-notice/{token} — Relay a demand partner's win notice at ad start (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v2/account — Get DSP account profile (commercial terms + deals) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/adslots — Browse available inventory with FEIN signals (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/analytics/funnel — VAST event funnel (requests → renders → completions) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/audience/lookalike/{screenId} — Find lookalike screens (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/audience/predict/{screenId} — Predict audience for a screen and time window (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/audience/rank-creatives — Rank creatives for an audience context (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/audience/semantic-search — Semantic search across audience scene descriptions (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/audience/semantic-stats — Get embedding statistics for semantic search (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/bid — Submit OpenRTB 2.6 bid response (agent_safe=false, idempotent=false, cost_tier=paid)
- POST /openrtb/v2/campaigns — Create a campaign with targeting (agent_safe=false, idempotent=false, cost_tier=paid)
- POST /openrtb/v2/campaigns/assign — Place creative on specific screens (agent_safe=false, idempotent=false, cost_tier=paid)
- GET /openrtb/v2/creatives — List your creatives (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/creatives — Upload a creative for AI moderation (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v2/creatives/{id} — Get creative details with full moderation results (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/creatives/{id}/confirm — Confirm presigned upload and trigger moderation (agent_safe=false, idempotent=true, cost_tier=free)
- GET /openrtb/v2/deals — List active deals for your DSP (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/deals/propose — Propose a new deal (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v2/deals/{dealId} — Get deal details (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/discover — Semantic inventory search (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/domedia/availability — Quote mapped DOmedia inventory availability (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/audience-segments — Get FEIN audience segments (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/content-audience-correlation — Content category x audience demographic breakdown (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/content-performance/{videoId} — Get content performance by video ID (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/content-recommendations — Get best-performing content for a venue context (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/fein/content-semantic-search — Semantic similarity search over content library (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/creative-venue-performance — Get creative x venue performance matrix (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/fill-rate-by-venue — Get fill rate by venue (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/inference-history — Get FEIN inference history (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/model-status — Get FEIN model status (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/readiness — Get FEIN readiness report (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/screen-intelligence/{screenId} — Get screen intelligence (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/stream — Stream FEIN events over SSE (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/fein/webhooks — List FEIN webhooks (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/fein/webhooks — Register FEIN webhook (agent_safe=false, idempotent=false, cost_tier=free)
- DELETE /openrtb/v2/fein/webhooks/{id} — Delete FEIN webhook (agent_safe=false, idempotent=true, cost_tier=free)
- POST /openrtb/v2/forecast — Estimate campaign delivery and spend (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/market/cpm-benchmarks — CPM percentile benchmarks by venue and geography (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/market/demand-analysis — Top categories, daypart curves, segment premiums (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/onboard — Register a new DSP (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v2/openapi.json — Machine-readable OpenAPI 3 spec for the OpenRTB v2 surface (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/proof-of-play — Verified ad play records with tier breakdown (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/reports/creatives — Per-creative rollup for the authenticated DSP seat (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/reports/screens — Per-screen performance breakdown (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/reports/summary — Aggregated performance summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/reports/timeseries — Time-series performance data (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/screens/audience — Bulk audience profiles for up to 50 screens (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/screens/availability — Bulk capacity and booking query (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/screens/{id} — Comprehensive screen profile (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/stats — Get 24-hour performance stats (agent_safe=true, idempotent=true, cost_tier=free)
- GET /openrtb/v2/webhooks — List webhook subscriptions for this DSP seat (agent_safe=true, idempotent=true, cost_tier=free)
- POST /openrtb/v2/webhooks — Register a webhook subscription (agent_safe=false, idempotent=false, cost_tier=free)
- GET /openrtb/v2/webhooks/deliveries — Self-serve webhook delivery log (agent_safe=true, idempotent=true, cost_tier=free)
- DELETE /openrtb/v2/webhooks/{id} — Remove a webhook subscription (agent_safe=false, idempotent=true, cost_tier=free)

## Trillboards Measurement API (measurement)
- GET /v1/advertiser/attribution/campaign/{campaignId} — Campaign attribution summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/attention — Attention metrics summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/attention/creative — Per-creative attention comparison (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/attention/timeseries — Attention metrics over time (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/audience-overindex — Demographic over-index (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/audience-profile — DSP-consensus audience profile (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/causal-lift — Per-segment causal lift (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/channel-roas — Per-channel ROAS (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/advertiser/attribution/campaign/{campaignId}/cohort/export — Export cohort to DSP (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/advertiser/attribution/campaign/{campaignId}/cohort/refresh — Force cohort re-sync to a DSP (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/creative-attribution — Creative-level attribution performance (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/creative-attribution/{creativeId}/timeseries — Creative attribution over time (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/cross-channel-journey — Cross-channel journey (Sankey flow) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/downtime-experiments — Screen-downtime natural experiments (not measured) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/heatmap — Geospatial exposure heatmap (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/incrementality — Incrementality results (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/journey — Attribution journey funnel (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/methodology — Attribution methodology explanation (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/multi-touch — Multi-touch attribution summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/optimizations — Attribution-driven optimization weights (agent_safe=true, idempotent=true, cost_tier=free)
- PUT /v1/advertiser/attribution/campaign/{campaignId}/optimizations/auto — Toggle auto-optimization (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/roas — ROAS breakdown by channel and creative (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/signal-quality — Signal quality and coverage (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/timeseries — Daily attribution timeseries (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/transactions — Transaction attribution & ROAS summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/transactions/timeseries — Daily ROAS timeseries (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/venue-loyalty — Venue loyalty breakdown (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/campaign/{campaignId}/weather-incrementality — Weather-based incrementality (not measured) (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/advertiser/attribution/experiment — Create incrementality experiment (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/advertiser/attribution/experiment/{experimentId} — Experiment status and results (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/attribution/experiment/{experimentId}/power — Power analysis (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/advertiser/conversion-source — Connect a measurement source (agent_safe=false, idempotent=false, cost_tier=free)
- DELETE /v1/advertiser/conversion-source/{sourceId} — Disconnect a measurement source (soft delete) (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/advertiser/conversion-source/{sourceId} — Fetch one measurement source (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /v1/advertiser/conversion-source/{sourceId} — Update a measurement source (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/advertiser/conversion-source/{sourceId}/capability-url — Get the capability ingest URL for a provider that cannot send a header (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/conversion-source/{sourceId}/deliveries — What this source's provider pushed, and what we answered (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/advertiser/conversion-source/{sourceId}/roll-secret — Roll a source's signing secret (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/advertiser/conversion-sources — List this advertiser's measurement sources (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/proof/.well-known/public-key — Get public key for signature verification (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/proof/campaigns/{campaignId}/audience-proof — Get audience-enhanced proofs (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/advertiser/proof/campaigns/{campaignId}/export-proof — Export proofs in batch format (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/proof/campaigns/{campaignId}/proof — Get proofs for a campaign (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/proof/screens/{screenId}/proof — Get proofs for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/advertiser/proof/signature-info — Get signature format documentation (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/advertiser/proof/verify-proof — Verify a proof signature (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/attribution/event/mobile — DSP mobile postback (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/attribution/event/transaction/{sourceId} — Transaction data ingestion (source-scoped, signed) (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/attribution/event/web — Report a web conversion (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/attribution/pixel.js — Web conversion pixel script (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/attribution/pixel/{advertiserId}/{campaignId} — Conversion tracking pixel (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/attribution/postback/adjust — Adjust MMP postback (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/attribution/postback/appsflyer — AppsFlyer MMP postback (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/attribution/postback/kochava — Kochava MMP postback (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/attribution/postback/{provider}/c/{token} — Per-source MMP postback over GET, for providers that default to it (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/attribution/postback/{provider}/c/{token} — Per-source MMP postback authenticated by a capability URL (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/attribution/postback/{provider}/{sourceId} — Per-source signed MMP postback (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/attribution/provider-impression — Provider impression callback (GET) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/attribution/provider-impression — Provider impression callback (POST) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/attribution/qr-signal — Report QR scan device signals (agent_safe=false, idempotent=false, cost_tier=free)

## Trillboards Partner API (partner)
- GET /v1/changelog — Query API changelog (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/errors — List all error codes (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/errors/{code} — Look up a single error code (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/federated/gradients — Upload sparsified gradients for multi-slice federated aggregation. (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/federated/models/{modelType} — Fetch aggregated weights for the device-specific slice. (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/federated/models/{modelType}/latest — Fetch the latest aggregated model descriptor (download URL + sha256 + version). (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/federated/performance — Report on-device model performance metrics. (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/federated/taste — Upload a screen-taste embedding for content personalization aggregation. (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/ads/self-promo — List self-promo ads (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/ads/self-promo — Create self-promo ad (URL-based) (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/ads/self-promo/placements — List self-promo placements by screen (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/ads/self-promo/schedule — Schedule existing self-promo ad to screens (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/ads/self-promo/upload — Create self-promo ad (upload) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/ads/self-promo/{ad_id}/disable — Disable a self-promo ad (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/agent/register — Register an AI agent (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/analytics — Get partner analytics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/audience-continuity — Visitor-flow continuity graph across the partner's screens (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/audience-profile — Audience composition for the partner's screens (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/ble-summary — BLE device discovery summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/content-performance — Content performance — ad lineage and measured audience reactions (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/creative-catalog — Free-text search across the partner's creative catalogue (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/creative-scenes — Scene-level observations for a played creative (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/cross-screen-flow — Per-pair flow directionality + transition heatmap (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/dashboard — Unified portfolio dashboard (earnings, ads, audience, screens, insights) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/device-suite-signature — Device-type / OS / browser-class distribution among repeat visitors (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/export — CSV export of partner-scope analytics (summary / daily / per-screen) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/export/ads-by-day — Per-ad daily breakdown for the partner fleet (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/fleet-hourly — 24-hour distribution across the partner's fleet (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/halo-funnel — 4-stage discovery → awareness → engagement → conversion funnel (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/loyalty-clock — 24-hour returning-vs-first-timer audience clock (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/network-summary — Fleet-wide audience summary for the partner's screens (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/network-trend — Daily/hourly fleet-wide audience timeseries (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/proximity-summary — Cross-screen proximity-graph summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/revenue-attention-correlation — Per-creative scatter of avg-attention vs revenue-per-impression (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/scene-feed — Paginated chronological feed of scene observations (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/analytics/scene-intelligence — Latest scene description per screen (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/api-key/rotate — Rotate API key (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/audience-analytics — Get partner-wide audience analytics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/audience-export — Export audience data (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/audience/heatmap — Get audience heatmap data (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/audience/live/{screenId} — Get live audience data for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/audience/lookalikes/{screenId} — Find lookalike screens (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/partner/audience/predict/{screenId} — Predict screen audience (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/partner/audience/resolved-household-reach/{campaignId} — Resolved household reach for a campaign (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/audience/segments — List audience segments (agent_safe=true, idempotent=true, cost_tier=metered)
- POST /v1/partner/audience/segments — Create audience segment (agent_safe=false, idempotent=false, cost_tier=metered)
- DELETE /v1/partner/audience/segments/{segmentId} — Delete audience segment (agent_safe=false, idempotent=true, cost_tier=metered)
- GET /v1/partner/audience/segments/{segmentId} — Get audience segment (agent_safe=true, idempotent=true, cost_tier=metered)
- PATCH /v1/partner/audience/segments/{segmentId} — Update audience segment (agent_safe=false, idempotent=true, cost_tier=metered)
- POST /v1/partner/audience/segments/{segmentId}/match — Match screens to segment (agent_safe=false, idempotent=true, cost_tier=metered)
- POST /v1/partner/audience/segments/{segmentId}/reach — Estimate segment reach (agent_safe=true, idempotent=true, cost_tier=metered)
- POST /v1/partner/audience/segments/{segmentId}/vast-tag — Generate VAST tag for segment (agent_safe=false, idempotent=true, cost_tier=metered)
- GET /v1/partner/audience/stats — Get audience data statistics (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/billing/cancel — Cancel the partner's subscription at period end (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/billing/credits — Purchase committed-use credits (agent_safe=false, idempotent=false, cost_tier=paid)
- POST /v1/partner/billing/credits/checkout — Create Stripe Checkout session for credits (agent_safe=false, idempotent=false, cost_tier=paid)
- GET /v1/partner/billing/plans — List available partner billing plans (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/billing/setup — Set up usage-based billing (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/billing/subscribe — Subscribe the partner to a billing plan (agent_safe=false, idempotent=false, cost_tier=paid)
- GET /v1/partner/billing/subscription — Get the partner's current subscription (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/billing/usage — Get the partner's current-period usage (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/billing/usage-summary — Get current billing period usage (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/billing/webhook — Stripe webhook callback (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/connect/dashboard — Get partner dashboard overview (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/connect/earnings — Get earnings chart data (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/connect/health — Get screen health status (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/content-presets — List content presets (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/content-presets/{presetId} — Get content preset (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/creative-experiments — Create an experiment on a funded native media-buy placement (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/creative-experiments/{experiment_id} — Read your native experiment, policy and latest 500 owned creative recovery records (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/creative-experiments/{experiment_id}/brand — Configure your native brand profile and enable its booked reactive campaign (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/creative-experiments/{experiment_id}/creatives/generate — Generate a native brand creative for explicit review and moderation (agent_safe=false, idempotent=true, cost_tier=metered)
- POST /v1/partner/creative-experiments/{experiment_id}/creatives/import — Import an AI model’s image through native bytes, moderation and brand review (agent_safe=false, idempotent=true, cost_tier=metered)
- POST /v1/partner/creative-experiments/{experiment_id}/creatives/review — Approve or reject your generated creative using native brand review (agent_safe=false, idempotent=false, cost_tier=free)
- PUT /v1/partner/creative-experiments/{experiment_id}/policy — Replace native creative weights at the expected policy version (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/creative-experiments/{experiment_id}/rewards — Read a metered page of latest measured native play states (agent_safe=true, idempotent=true, cost_tier=metered)
- POST /v1/partner/creative-experiments/{experiment_id}/stop — Stop the native experiment at the expected policy version (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/creative-experiments/{experiment_id}/variants — Register approved native generated creative variants (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/creatives — Submit a creative for classification (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/creatives/{ref} — Get a creative classification (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/dashboard — Get dashboard overview (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/data-export/proximity-graph-edges — Export the cross-screen proximity graph edge list (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/data-export/summary — List available datasets and per-dataset record counts (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/data-export/{dataset} — Export a partner-scoped dataset (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/data/geohash-audience-panel — Geographic audience panel (data-licensing) (agent_safe=true, idempotent=true, cost_tier=metered)
- GET /v1/partner/data/outcome-attribution — Outcome-attribution export (data-licensing) (agent_safe=true, idempotent=true, cost_tier=metered)
- POST /v1/partner/device — Register a device (agent_safe=false, idempotent=false, cost_tier=free)
- DELETE /v1/partner/device/{deviceId} — Delete a device (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/device/{deviceId} — Get device info (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /v1/partner/device/{deviceId} — Update device metadata (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/device/{deviceId}/ads — Get ads for device (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/device/{deviceId}/commands/{commandId}/ack — Acknowledge a device command (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/device/{deviceId}/heartbeat — Read live device heartbeat state (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/device/{deviceId}/heartbeat — Device heartbeat (agent_safe=false, idempotent=true, cost_tier=free)
- PATCH /v1/partner/device/{deviceId}/impression-multiplier — Update a device's publisher impression multiplier (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/device/{deviceId}/interactions — Report a rider interaction from the partner SDK (reportInteraction) (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/device/{deviceId}/plays — Report a play from the partner SDK (reportPlay) (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/device/{deviceId}/programmatic-event — Record programmatic ad event (Server-side Analytics) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/device/{deviceId}/trips — Report a taxi-meter state change from the partner SDK (setTripState) (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/devices — List all devices (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/devices — Register a device (V2 single-call onboarding) (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/devices/batch — Bulk register devices (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/devices/batch/orientation — Batch update screen orientation (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/devices/reconcile — Reconcile device fleet (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/docs — Browsable HTML documentation index (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/earnings — Get earnings summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/earnings/breakdown — Get detailed earnings breakdown (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/earnings/payout — Request a payout (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/earnings/transactions — Get transaction history (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/events/connections — List active SSE connections (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/events/stream — Subscribe to real-time events (SSE) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/fleet-commands/{id} — Poll a fleet-command job (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/fleet/analytics — Get fleet analytics (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/fleet/command — Push command to fleet (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/fleet/overview — Get fleet overview (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/fleet/settings — Update fleet-wide settings (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/impression — Record impression (pixel) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/impression — Record impression (POST) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/impressions/batch — Batch record impressions (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/info — Get partner info (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/intent/categories — List intent categories (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/intent/categories/{categoryId} — Get intent category details (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/intent/pricing/{screenId} — Get intent-based pricing for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/measurement-methodology — Trillboards measurement methodology disclosure (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/measurement-methodology.json — Measurement methodology disclosure (JSON, no negotiation) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/network-config — Get network configuration (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /v1/partner/network-config — Partial update network configuration (agent_safe=false, idempotent=true, cost_tier=free)
- PUT /v1/partner/network-config — Update network configuration (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/network/trends — Network-wide audience and inventory trends (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/ping — Unauthenticated liveness probe (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/ping/auth — Authenticated liveness probe (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/plays — Record a log-level play (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/plays/batch — Record a batch of log-level plays (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/pricing — Get machine-readable pricing (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/programmatic-event — Record programmatic ad event (legacy SDK alias) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/quick-start — Quick start — register partner and first device in one call (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/register — Register a new partner (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/sandbox/event — Generate a test event (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/sandbox/reset — Reset sandbox data (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/sandbox/screen — Create a sandbox screen (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/sandbox/status — Get sandbox status (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screen-groups — List screen groups (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screen-groups — Create a screen group (agent_safe=false, idempotent=false, cost_tier=free)
- DELETE /v1/partner/screen-groups/{groupId} — Delete (archive) a screen group (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screen-groups/{groupId} — Retrieve a screen group (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screen-groups/{groupId} — Update a screen group (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screen-groups/{groupId}/analytics — Get analytics for a screen group (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screen-groups/{groupId}/commands — Run a fleet command against a screen group (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/screen-groups/{groupId}/content-policy — Get a screen group's content policy (agent_safe=true, idempotent=true, cost_tier=free)
- PUT /v1/partner/screen-groups/{groupId}/content-policy — Set a screen group's content policy (agent_safe=false, idempotent=true, cost_tier=free)
- DELETE /v1/partner/screen-groups/{groupId}/members — Remove members from a screen group (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screen-groups/{groupId}/members — List a screen group's members (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screen-groups/{groupId}/members — Add members to a screen group (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screen-groups/{groupId}/sensing-config — Get a screen group's sensing config (agent_safe=true, idempotent=true, cost_tier=free)
- PUT /v1/partner/screen-groups/{groupId}/sensing-config — Set a screen group's sensing config (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screen/{external_code}/audience-segments — OpenRTB SDA payload for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screens/batch/content-preferences — Batch update content preferences (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/screens/batch/display-settings — Batch update display settings (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/screens/batch/programmatic-settings — Batch update programmatic settings (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/resolve — Resolve screen ID by device identifier (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/analytics — Get per-screen analytics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/analytics/atmosphere — Current atmosphere (mood, noise, crowd density) (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/analytics/intelligence — Time-bucketed venue intelligence with Lincoln-Petersen dedup (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/analytics/taste-profile — Per-screen taste profile + top-5 creative categories (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/analytics/traffic — Hourly foot-traffic patterns for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/analytics/vas — Verified Attention Seconds + CPM tier for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screens/{screenId}/apply-preset — Apply content preset to screen (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/audience-metrics — Get real-time audience metrics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/content-preferences — Get screen content preferences (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /v1/partner/screens/{screenId}/content-preferences — Update content preferences (partial) (agent_safe=false, idempotent=true, cost_tier=free)
- PUT /v1/partner/screens/{screenId}/content-preferences — Update content preferences (full) (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/default-streams — List default streams for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screens/{screenId}/default-streams — Create a default stream (URL-based) (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/partner/screens/{screenId}/default-streams/images — Upload image carousel default stream (agent_safe=false, idempotent=false, cost_tier=free)
- PUT /v1/partner/screens/{screenId}/default-streams/order — Reorder default streams (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/screens/{screenId}/default-streams/upload — Upload a video default stream (agent_safe=false, idempotent=false, cost_tier=free)
- DELETE /v1/partner/screens/{screenId}/default-streams/{streamId} — Delete a default stream (agent_safe=false, idempotent=true, cost_tier=free)
- PUT /v1/partner/screens/{screenId}/default-streams/{streamId} — Update a default stream (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/demographics — Get screen demographics (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/display-settings — Get display settings (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /v1/partner/screens/{screenId}/display-settings — Update display settings (partial) (agent_safe=false, idempotent=true, cost_tier=free)
- PUT /v1/partner/screens/{screenId}/display-settings — Update display settings (full) (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/l-bar — Get L-Bar settings (agent_safe=true, idempotent=true, cost_tier=free)
- PUT /v1/partner/screens/{screenId}/l-bar — Update L-Bar settings (agent_safe=false, idempotent=true, cost_tier=free)
- PUT /v1/partner/screens/{screenId}/l-bar/live-updates — Update L-Bar live updates (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/programmatic-settings — Get programmatic settings (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /v1/partner/screens/{screenId}/programmatic-settings — Update programmatic settings (partial) (agent_safe=false, idempotent=true, cost_tier=free)
- PUT /v1/partner/screens/{screenId}/programmatic-settings — Update programmatic settings (full) (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/resolved-content-policy — Resolve the effective content policy for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/resolved-sensing-config — Resolve the effective sensing config for a screen (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/sensing/chips — Read the custom sensing chips a screen is producing (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screens/{screenId}/sensing/interpret-intent — Generate a custom sensing profile from a natural-language intent (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/screens/{screenId}/sensing/profile — Deploy a custom sensing profile to a screen (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/screens/{screenId}/sensing/settings — Read a screen's AI sensing performance settings (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /v1/partner/screens/{screenId}/sensing/settings — Update a screen's AI sensing performance mode (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/sensing/routes — List your Sense Anything Routes (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/sensing/routes — Create a Sense Anything Route (threshold or scheduled-digest alert) (agent_safe=false, idempotent=false, cost_tier=free)
- DELETE /v1/partner/sensing/routes/{routeId} — Delete (soft) a Sense Anything Route (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/sensing/routes/{routeId} — Get one Sense Anything Route (agent_safe=true, idempotent=true, cost_tier=free)
- PATCH /v1/partner/sensing/routes/{routeId} — Update a Sense Anything Route (partial, non-clobbering) (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/stripe/connect — Create Stripe Connect account (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/stripe/login-link — Get Stripe dashboard login link (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/stripe/onboarding-link — Get Stripe onboarding link (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/stripe/payout — Request a payout (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/stripe/payouts — Get payout history (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/stripe/status — Get Stripe account status (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/stripe/webhook — Stripe webhook receiver (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/team — List team members (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/team/accept — Accept team invitation (agent_safe=false, idempotent=true, cost_tier=free)
- POST /v1/partner/team/invite — Invite a team member (agent_safe=false, idempotent=false, cost_tier=free)
- GET /v1/partner/team/invite/{token} — Get invitation details (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/team/{membershipId}/resend — Resend invitation (agent_safe=false, idempotent=false, cost_tier=free)
- DELETE /v1/partner/team/{userId} — Remove a team member (agent_safe=false, idempotent=true, cost_tier=free)
- PATCH /v1/partner/team/{userId}/role — Change team member role (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/tracking/.well-known/public-key — Get public key for proof verification (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/tracking/batch — Record batch impressions with proof generation (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/usage — Get API usage summary (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/usage/dashboard — Get real-time usage dashboard (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/usage/rate-limit — Get rate limit status (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/vast/config — Get VAST configuration for direct Google integration (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/venues/nearby — List nearby Trillboards venues (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/venues/{screenId}/atmosphere — Real-world atmosphere signals for a venue (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/venues/{screenId}/traffic — Foot-traffic profile for a venue (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/venues/{venueId}/intelligence — Get venue intelligence report (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/partner/webhooks — List webhooks (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/webhooks — Create webhook subscription (agent_safe=false, idempotent=false, cost_tier=free)
- DELETE /v1/partner/webhooks/{webhookId} — Delete webhook (agent_safe=false, idempotent=true, cost_tier=free)
- PATCH /v1/partner/webhooks/{webhookId} — Update webhook (agent_safe=false, idempotent=true, cost_tier=free)
- GET /v1/partner/webhooks/{webhookId}/deliveries — Get delivery history (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v1/partner/webhooks/{webhookId}/test — Test webhook (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v1/playground/{operation_id} — Dry-run validate a request body against an operation schema (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v1/requests/{request_id} — Look up metadata for a recent API request (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v2/csi/venue/{screenId}/history — Historical venue occupancy in 10-minute CSI buckets. (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v2/csi/venue/{screenId}/occupancy — Real-time venue occupancy from WiFi CSI sensing. (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v2/device/ota/manifest — Signed OTA manifest for managed-device update clients. (agent_safe=true, idempotent=true, cost_tier=free)
- GET /v2/earner/cameras/sensing-profile — Active sensing profile for the calling connector's bound screen. (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v2/sdk/enrich — Census + demographic enrichment from the request IP. (agent_safe=true, idempotent=true, cost_tier=free)
- POST /v2/sdk/impression — Ingest an enriched CTV/DOOH impression. (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v2/sdk/qr/beacon — Process beacon signals associated with a prior QR scan. (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v2/sdk/qr/scan — Record a QR-code scan for physical-to-digital attribution. (agent_safe=false, idempotent=false, cost_tier=free)
- POST /v2/sensing/paired-training-samples — Upload a batch of paired camera/CSI training samples. (agent_safe=false, idempotent=true, cost_tier=free)
# END-GENERATED endpoint-catalog

---

# Trillboards Partner API reference

## Overview
Trillboards is a programmatic digital out-of-home (DOOH) advertising platform.
Partners integrate our SDK into screens (vending machines, kiosks, digital signage)
to display ads and earn competitive revenue share on all impressions.

## API Base URL
Production: https://api.trillboards.com/v1/partner
Sandbox: same base URL, different ACCOUNT. There is no separate sandbox host —
register with {"sandbox": true} (below) and the key you get back is a sandbox
account: its media buys validate end to end and return responses marked
sandbox:true, but write no advertisements and no placements, so nothing serves,
delivers, bills, or pays a venue. Declared as account.sandbox in
get_adcp_capabilities.

## Authentication
One centralized platform API key authenticates Partner, MCP, reporting, inventory,
deals, and OpenRTB control-plane requests. Capabilities decide access; prefixes do not.
Self-mint at https://trillboards.com/earner/settings?tab=api (Partner API) and send:
```
Authorization: Bearer <platform_api_key>
```

For an existing Earner account, the owner/admin can mint the same key
programmatically without opening the portal. The login returns a short-lived
user JWT; the create response returns `data.rawKey` once:
```bash
export EARNER_EMAIL='owner@example.com'
export EARNER_PASSWORD='use-your-secret-manager'

LOGIN_JSON=$(jq -n \
  --arg email "$EARNER_EMAIL" \
  --arg password "$EARNER_PASSWORD" \
  '{email:$email,password:$password,deviceType:"web"}' | \
  curl -sS -X POST https://api.trillboards.com/v1/user/login \
    -H 'Content-Type: application/json' --data-binary @-)
EARNER_JWT=$(printf '%s' "$LOGIN_JSON" | jq -r '.token')

KEY_JSON=$(curl -sS -X POST https://api.trillboards.com/v2/earner/api-keys \
  -H "Authorization: Bearer ${EARNER_JWT}" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Vistars agent integration"}')
API_KEY=$(printf '%s' "$KEY_JSON" | jq -r '.data.rawKey')
```
Do not call a registration endpoint for an existing organization: that would
create a second account. Store the key in a secrets manager and discard the
password/JWT variables after minting.

For a brand-new organization only, a headless agent can create the account and
same centralized platform key without using the Earner portal:
```
POST https://api.trillboards.com/v1/partner/agent/register
Content-Type: application/json

{
  "agent_type": "dsp_agent",
  "name": "Example Buyer Agent",
  "email": "programmatic@example.com",
  "company": "Example Buyer",
  "sandbox": false
}
```
Set `"sandbox": true` for a TEST account (AdCP `account.sandbox`). The `201`
response echoes it back as `account.sandbox`, and every media-buy tool response
made with that key is marked `sandbox: true`.
The `201` response returns `api_key` once plus
`mcp_endpoint: https://api.trillboards.com/mcp`. Store the key in a secrets
manager. To enable global buyer inventory, reporting, deals, stats, and bidding
capabilities, POST /openrtb/v2/onboard with Authorization: Bearer <same_key>.
Onboarding links capabilities to that key; it does not mint another credential.

Copy-paste buyer onboarding:
```
API_KEY='<api_key returned once by /v1/partner/agent/register>'

curl -sS -X POST https://api.trillboards.com/openrtb/v2/onboard \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "Example Buyer",
    "seat_id": "example_buyer",
    "contact_email": "programmatic@example.com"
  }'

curl -sS https://api.trillboards.com/mcp \
  -H "Authorization: Bearer ${API_KEY}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'
```

For a white-label agent experience, use an already-provisioned tenant/custom
domain that routes the API and configure the agent with `https://<custom-host>/mcp`.
That host receives neutral MCP tool descriptions and resources while using the
same key and services. OpenRTB seat, sellers.json, schain, callback, and settlement
identity stay truthful and are not presentation aliases.

Existing tb_prt_*, trb_partner_*, tb_dsp_*, x-api-key, and
X-Trillboards-API-Key integrations remain backwards compatible.

Unauthenticated endpoints:
- GET /device/{id}/ads
- GET/POST /impression
- POST /impressions/batch
- POST /device/{id}/heartbeat

## OpenAPI Specification
Interactive docs (Scalar UI): https://api.trillboards.com/docs#partner
Public API index: https://api.trillboards.com/docs/openapi.yaml
Partner OpenAPI spec: https://api.trillboards.com/docs/openapi/partner-api.yaml
Proof-of-Play OpenAPI spec: https://api.trillboards.com/docs/openapi/proof-of-play.yaml
Attribution OpenAPI spec: https://api.trillboards.com/docs/openapi/attribution-api.yaml
Programmatic & FEIN OpenAPI spec: https://api.trillboards.com/docs/openapi/programmatic-api.yaml
OpenRTB Extensions schema spec: https://api.trillboards.com/docs/openapi/openrtb-extensions.yaml
Attribution data model spec: https://api.trillboards.com/docs/openapi/attribution-data-models.yaml
Partner webhook events spec: https://api.trillboards.com/docs/openapi/partner-webhooks.yaml
Webhook signature verification guide: https://api.trillboards.com/docs/integrations/webhook-signature-verification.md
Partner integration guide: https://api.trillboards.com/docs/integrations/partner-native-bridge.md

### API Discovery
# AI-agent self-navigation endpoints (Phase 6). Unauthenticated, read-only.
# Every registered operation is listed with agent_safe / idempotent / cost_tier
# flags and example requests, so an agent can enumerate the entire API in a
# single call and fuzzy-search across operations + error codes.
API discovery index (JSON): https://api.trillboards.com/api/discover
API discovery search: https://api.trillboards.com/api/discover/search?q=<term>
Agent-facing OpenAPI extensions on each operation:
  - x-trillboards-agent-safe: true when the endpoint is side-effect-free
  - x-trillboards-idempotent: true when retries do not double-process
  - x-trillboards-cost-tier: free | metered | paid
  - x-trillboards-llm-example: prose "when to call me" hint
Canonical error reference (HTML): https://api.trillboards.com/docs/errors
Error reference (markdown): https://api.trillboards.com/docs/errors.md
OpenAPI index (JSON): https://api.trillboards.com/openapi.json (also https://api.trillboards.com/docs/openapi.json)
MCP server (stdio + HTTP): https://api.trillboards.com/mcp
  Discovery MCP tools: list_endpoints, describe_endpoint, validate_request
AdCP agents manifest: https://api.trillboards.com/.well-known/adagents.json

# Every canonical error envelope carries `help.try_next` pointing at
# /api/discover when the caller supplies an ID that isn't in their scope.
# Follow that URL to get ranked suggestions and recover without reading docs.

## Key Concepts

### Partner
- Company or developer integrating our ad platform
- Receives API key on registration
- Manages multiple devices
- Earns competitive revenue share on impressions

### Device
- Physical screen displaying ads
- Identified by fingerprint (e.g., "P_abc123") or external device ID
- Can be vending_machine, kiosk, tablet, display, or other
- Reports heartbeat for online status

### Impression
- Single ad view on a device
- Tracked automatically by SDK or via API
- Supports batch sync for offline scenarios
- Idempotent on `impid + adid` (duplicate submissions are ignored)
- Optional signature for verification: send `X-Trillboards-API-Key`, `X-Trillboards-Timestamp`, `X-Trillboards-Signature` where payload is `{ts}.{adid}.{impid}.{did}.{sid}.{aid}`
- Optional display context: `display_mode`, `display_area_ratio`, `lbar_size`, `lbar_position`, `lbar_slot_index`, `lbar_slot_count`
- Batch impressions can include per-impression `sig` and `sig_ts` fields using the same payload format

## Quick Start Flow

1. Register partner (POST /register)
   - Returns API key (store securely!)
   - Partners are auto-activated for instant onboarding
   - If the partner owner has no password yet, the response includes portal_access with claim endpoints

2. Claim portal account (if required)
   - POST /claim/request with { email, partner_id } to request a one-time claim link
   - POST /claim/verify with { token } to verify claim token
   - POST /claim/complete with { token, password } to set a password and activate access
   - Email verification can run in parallel; do not block claim flow on verification

2. Register device (POST /device)
   - Provide device_id, name, location
   - Returns fingerprint, screen_id, and embed_url

3. Display ads
   - Load embed_url in WebView/iframe
   - SDK handles ad rotation automatically
   - Or fetch ads via GET /device/{id}/ads

4. Track impressions
   - SDK does this automatically
   - Or POST /impression for custom tracking
   - Batch offline impressions via POST /impressions/batch

6. Check analytics (GET /analytics)
   - View impressions, revenue, device stats

## Endpoints Summary

### Partner Management
- POST /register - Register new partner, get API key
- GET /info - Get partner details and stats
 - POST /claim/request - Request account-claim token for portal access
 - POST /claim/verify - Verify account-claim token
 - POST /claim/complete - Set password and finalize account claim

### Device Management
- POST /device - Register/update a device
- GET /devices - List all devices (paginated)
- POST /devices/batch - Bulk register up to 100 devices
- POST /devices/reconcile - Read-only fleet diff (matched/missing/orphan/malformed/duplicate) vs your external_ids
- GET /device/{id} - Get device by ID/fingerprint
- DELETE /device/{id} - Soft-delete device

### CMS (Screen Content)
- GET /screens/resolve?device_id=... - Resolve screen_id from device identifiers
- GET /screens/{screenId}/default-streams - List background streams
- POST /screens/{screenId}/default-streams - Create background stream (URL-based)
- POST /screens/{screenId}/default-streams/upload - Upload video stream (multipart)
- POST /screens/{screenId}/default-streams/images - Upload image carousel (multipart)
- PUT /screens/{screenId}/default-streams/{streamId} - Update stream
- DELETE /screens/{screenId}/default-streams/{streamId} - Delete stream
- PUT /screens/{screenId}/default-streams/order - Reorder streams
- GET /screens/{screenId}/l-bar - Get L-bar settings/content
- PUT /screens/{screenId}/l-bar - Update L-bar settings/content
- PUT /screens/{screenId}/l-bar/live-updates - Update L-bar live updates
- GET /ads/self-promo - List self-promo ads for full embed
- POST /ads/self-promo - Create self-promo ad (URL-based)
- POST /ads/self-promo/upload - Upload self-promo ad media
- POST /ads/self-promo/schedule - Schedule self-promo ad to screens
- POST /ads/self-promo/{adId}/disable - Disable self-promo placements
- GET /ads/self-promo/placements - List self-promo placements by screen

### Ad Serving (No Auth Required)
- GET /device/{id}/ads - Get ads for SDK (supports ETag caching, id = fingerprint or external device ID)
  - Optional player-truth query params: slot_w, slot_h, orientation, muted, autoplay
  - Returns header_bidding_settings with a VAST waterfall (Adipolo, VidVerto, IncrementX, GAM, etc.)
  - Each source has: name, vast_url (points to our vast-wrap endpoint), timeout_ms, priority, cpm, request_id

### Native IMA SDK Integration (Definitive Guide)
Full guide: https://api.trillboards.com/docs/integrations/partner-native-ima-sdk.md

Production-verified path for native Android IMA SDK players (Rockchip digital signage, Media3 + ImaAdsLoader).
Take 10 Media reference integration: 61% Adipolo fill rate, 79% completion rate, ~48% effective.

**Five-endpoint flow:**
1. `POST /v1/partner/device/{deviceId}/heartbeat` every 60s — send full device identity
2. `GET /v1/partner/device/{deviceId}/ads` — get waterfall with VAST sources
3. `GET {source.vast_url}` (our vast-wrap endpoint) — fetch resolved VAST XML
4. Pass full XML unmodified to IMA SDK via `setAdsResponse` or Media3 `data:text/xml` URI
5. `POST /v1/partner/device/{deviceId}/programmatic-event` for ad_started / ad_ended / no_fill / error

**Critical requirements (every one of these was a discovered-the-hard-way bug):**
- Heartbeat `device.ua` must be the real WebView UA with Build fingerprint, unique per device — read via `WebView(context).settings.userAgentString` or `WebSettings.getDefaultUserAgent(context)`. Same UA across your fleet = DSP IVT flags you as bot traffic.
- Heartbeat `device.make` = `Rockchip` (title case). Lowercase = unknown vendor to DSPs.
- Heartbeat `device.model` = real chipset from `Build.BOARD` (e.g. `rk3568_r`), NOT your internal SKU.
- Heartbeat `device.osv` = API level as string (`30` for Android 11, `34` for Android 14), NOT version name (`9`).
- **Do NOT set `ImaAdsLoader.setAdMediaMimeTypes("video/mp4")`** — this blocks VPAID and non-mp4 creatives. Leave unset. This was the single biggest blocker for Take 10.
- **Do NOT parse, strip, or modify the VAST XML before handing it to IMA SDK.** Our tracking pixels are embedded at the wrapper level. Stripping wrappers = no impression attribution = no revenue. Pass the full response body literally.
- `programmatic-event` requests must include both `request_id` and `variant_name` — events without these are dropped.
- You only need to report `programmatic-event` for the first source that actually played, not for sources skipped by the waterfall.

**What the server does for you:**
- `vast-wrap` fetches upstream VAST with your device's IP via `X-Forwarded-For` (correct geo targeting)
- Resolves wrapper chains server-side up to 5 hops (Adipolo wrapper → GAM → inline creative) so your device gets playable VAST without chain-following
- Injects tracking pixels with `&provider={source_name}` baked in at injection time — no post-hoc attribution needed
- Automatic impression counting via pixel fires — on top of `programmatic-event`, deduplicated by `request_id + impression_id`

### Impression Tracking
- GET /impression?adid=x&impid=y - Record single impression
- POST /impression - Record single impression
- POST /impressions/batch - Record up to 100 impressions

### VAST Integration (Direct Google Integration)
For enterprise partners who want to fetch ads directly from Google Ad Manager:
- GET /vast/config - Get VAST tag URL template (cache for 1 hour)
  - Returns template URL, targeting params, timeouts, and tracking endpoints
  - Partner builds VAST URL, fetches from Google directly
  - Trillboards NOT in critical ad path

### Batch Tracking (High-Volume Impressions)
For partners with 10,000+ screens:
- POST /tracking/batch - Record up to 100 impressions with Ed25519 proofs
- GET /tracking/.well-known/public-key - Get public key for proof verification (no auth)

### Device Health
- POST /device/{id}/heartbeat - Report device online status (id = fingerprint or external device ID)

### Analytics
- GET /analytics - Partner-level analytics with date filtering

### Creative Moderation
- POST /creatives - Submit a public/CDN creative URL; returns structured classification (moderation, age rating, IAB categories, subjects, keywords, OCR, brand). Async: 202 + `id` of form `sha256:<hex>`; poll until terminal. Returns 200 immediately if the same bytes were already classified.
- GET /creatives/{ref} - Read the classification for a creative you submitted (ref = `sha256:<hex>` or bare hex). Entitlement-gated to content you submitted. Use `id`/`content_sha256` as `creative_ref` when posting log-level plays so plays join to this classification.

### Measurement Plays
- POST /plays - Record a log-level play for an ad you serve yourself. Body: {screen_id, creative_ref (=content_sha256 from /creatives), play_id, completed_at, duration_seconds?, ad_id?}. Non-billing; lands in partner_measurement_plays and joins to classification + audience moments. Idempotent on play_id; screen_id must be one of your registered screens. 202 {status: accepted|duplicate}.
- POST /plays/batch - Up to 500 plays in one request (same shape). Per-play validation; response reports rejected plays.

### Dashboard
- GET /dashboard - Get partner dashboard overview with stats, earnings, top screens
- GET /screens/{screenId}/analytics - Get screen-level analytics (period: 7d, 30d, 90d)

### Team Management
Team management endpoints require dual authentication:
- Centralized platform API key in Authorization header: `Bearer <platform_api_key>`
- User JWT in X-User-Token header for write operations

**Read Endpoints (API key only):**
- GET /team - List all team members with roles and permissions
- GET /team/invite/{token} - Get invitation details (public, for invite acceptance)

**Write Endpoints (API key + User JWT + Owner role):**
- POST /team/invite - Invite a team member (body: { email, role, name? })
- POST /team/{membershipId}/resend - Resend invitation email
- PATCH /team/{userId}/role - Change member role (body: { role })
- DELETE /team/{userId} - Remove team member

Team Roles:
- **owner**: Full access (view all, manage team, request payouts, rotate API keys)
- **admin**: View screens/analytics, edit screens, configure webhooks
- **viewer**: View screens only

### Earnings
- GET /earnings - Get earnings summary (lifetime, this month, available for payout)
- GET /earnings/transactions - Get transaction history (paginated)
- GET /earnings/breakdown - Get earnings breakdown by day/week/screen
- POST /earnings/payout - Request payout (requires Stripe Connect)

### Quick Start
- POST /quick-start - Register partner + first device in one call (no auth, rate limited)
  - Returns API key, device credentials, SDK snippets, and configuration
  - Single-call alternative to POST /register + POST /device

### API Key Management
- POST /api-key/rotate - Generate new API key with 24h grace period for old key

### Stripe Connect (Partner Payouts)
- POST /stripe/connect - Create Stripe Connect Express account
- GET /stripe/onboarding-link - Get Stripe onboarding URL for identity/bank setup
- GET /stripe/login-link - Get temporary Stripe Express dashboard link
- GET /stripe/status - Get account status, payout readiness, and requirements
- POST /stripe/payout - Request payout (min $5.00, requires active Stripe account)
- GET /stripe/payouts - Get payout history (paginated)

### Connect Dashboard (SDK Partner Dashboard)
Pre-aggregated data for embedding in partner dashboards:
- GET /connect/dashboard - Full dashboard: screens, impressions, earnings, charts, top screens
- GET /connect/earnings - Daily/weekly earnings chart data
- GET /connect/health - Screen health status (online/offline/never_connected)

### Fleet Management
For partners with large screen networks:
- GET /fleet/overview - Fleet device counts, venue types, country breakdown
- GET /fleet/analytics - 24h fleet-wide impressions, fill rate, CPM, attention
- POST /fleet/command - Push command to fleet (reload, restart, screenshot, etc.)
  - Commands: reload, update_settings, restart, screenshot, clear_cache, update_content, refresh_ads, update_config, get_state, show_ad, play_ad
  - Supports filter by screenIds, venueType, country (max 500 devices/batch)
- POST /fleet/settings - Update fleet-wide settings (header_bidding, content_preferences, display)

### Venue Intelligence
Real-world venue data from CTV audience sensing:
- GET /venues/{venueId}/intelligence - Aggregated venue report with timeseries + dedup
  - Query params: from, to (ISO dates, max 30 days), interval (5min/15min/1h/1d)
- GET /venues/{screenId}/traffic - Hourly foot traffic patterns + busy score (0-10)
- GET /venues/{screenId}/atmosphere - Current mood, noise, crowd density, music detection
- GET /venues/nearby - Find nearby venues with live traffic (query: lat, lng, radiusKm)
- GET /network/trends - Network-wide audience trends (period: 24h/7d/30d)

### SSE Events (Real-Time Streaming)
Server-Sent Events for live event streaming:
- GET /events/stream - Open SSE connection (max 5 per partner)
  - Query param: events (comma-separated filter, empty = all)
  - Supports Last-Event-ID for reconnection + missed event replay
  - 30s heartbeat to keep connection alive
- GET /events/connections - List active SSE connections

### API Usage & Rate Limits
- GET /usage - API usage summary (query: start_date, end_date, default 30d, max 90d)
- GET /usage/dashboard - Real-time usage dashboard (today + 7-day history)
- GET /usage/rate-limit - Current rate limit status per tier (basic/developer/enterprise)

### Network Configuration (White-Label)
- GET /network-config - Get network config + parent partner ID
- PUT /network-config - Full update (default_content_preferences, default_waterfall, branding)
- PATCH /network-config - Partial update of specific nested fields

### Device Commands
- POST /device/{deviceId}/commands/{commandId}/ack - Acknowledge command execution

### Sandbox (Beta — Integration Testing)
Testing tools with synthetic data (24h TTL):
- POST /sandbox/screen - Create sandbox screen (max 10 per partner)
- POST /sandbox/event - Generate test event (17 event types supported)
  - Events also delivered via SSE if connection is active
- POST /sandbox/reset - Clear all sandbox data
- GET /sandbox/status - Get sandbox screens, events, recent activity

### Audience Intelligence (Beta)
Advanced audience analytics:
- GET /audience/live/{screenId} - Real-time audience data (all tiers)
- GET /audience/heatmap - Geospatial audience heatmap (all tiers)
- GET /audience/stats - Data availability statistics (all tiers)
- GET /audience/lookalikes/{screenId} - Find similar audience screens (Developer+ tier)
- GET /audience/predict/{screenId} - Predict audience by hour/day (Developer+ tier)

### Audience Segments (Beta — Enterprise Tier)
Custom audience targeting:
- POST /audience/segments - Create segment with rules
- GET /audience/segments - List all segments
- GET /audience/segments/{segmentId} - Get segment details
- PATCH /audience/segments/{segmentId} - Update segment
- DELETE /audience/segments/{segmentId} - Delete segment
- POST /audience/segments/{segmentId}/match - Find matching screens
- POST /audience/segments/{segmentId}/reach - Estimate reach + revenue
- POST /audience/segments/{segmentId}/vast-tag - Generate targeted VAST tag

### Data API (Third-Party Access)
Authenticated REST API for data partners (Place Exchange, OpenAI, Anthropic, etc.)
to access audience intelligence, screen data, and semantic search.

Base URL: https://api.trillboards.com/v1/data
Authentication: X-API-Key header (not Bearer token)

Scopes:
- read:live — Real-time screen and audience data
- read:historical — Historical audience metrics and aggregates
- read:semantic — Scene embedding semantic search

Endpoints:
- GET /screens - List active screens (query: limit, offset, venue_type, country)
- GET /screens/{screenId}/audience - Real-time audience snapshot from Redis
- GET /screens/{screenId}/history - Historical audience_metrics (query: since, until, limit)
- GET /semantic-search - Scene embedding similarity search (query: q, limit, since, min_similarity)
- GET /lookalike - Find screens with similar audience profiles (query: screen_id, limit, min_similarity)
- GET /aggregate - Aggregate analytics by group_by (venue_type|daypart|day_of_week|income_estimated_level|primary_mood) and metric (avg_face_count|avg_attention|income_confidence|max_face_count)
- GET /stats - Data API stats (embedding counts, active screens, metrics volume)

### Intent Catalog (Beta — Intent-Based Pricing)
Purchase intent detection and pricing:
- GET /intent/categories - List intent categories with CPM multipliers
- GET /intent/categories/{categoryId} - Get category details + triggers
- GET /intent/pricing/{screenId} - Real-time intent pricing for a screen

## Data Access Tiers

| Tier | Rate Limit | Access |
|------|-----------|--------|
| Basic | 200/min | Own screens, standard analytics |
| Developer | 1,000/min | + Venue intelligence, lookalikes, predictions |
| Enterprise | 5,000/min | + Audience segments, raw exports, SLA |

## Rate Limits

| Endpoint Type | Limit | Window |
|--------------|-------|--------|
| Registration | 5 | 1 hour |
| Authenticated API | 1000 | 1 minute |
| Ad serving | 100 | 1 minute |
| Impressions | 500 | 1 minute |
| Batch impressions | 100 | 1 minute |
| Heartbeat | 60 | 1 minute |
| Venue intelligence | 100 | 1 minute |
| Audience intelligence | 100 | 1 minute |
| Data API | 60 | 1 minute |
| Bulk device operations | 20 | 1 minute |

Rate limit headers returned on all responses:
- X-RateLimit-Limit
- X-RateLimit-Remaining
- X-RateLimit-Reset

## Error Responses

All errors follow a consistent format with helpful guidance:
```json
{
  "success": false,
  "error": {
    "type": "invalid_request_error",
    "code": "authentication_required",
    "message": "Authentication required. Provide your Partner API key in the Authorization header.",
    "param": "Authorization",
      "doc_url": "https://api.trillboards.com/docs/integrations/partner-native-bridge.md#errors",
    "help": {
      "summary": "Send your Partner API key in the Authorization header.",
      "example": "Authorization: Bearer trb_partner_xxxxx",
      "docs": "https://api.trillboards.com/docs/integrations/partner-native-bridge.md",
      "portal_url": "https://trillboards.com/earner"
    }
  },
  "request_id": "req_123"
}
```

HTTP Status Codes:
- 400: Bad request (validation error)
- 401: Unauthorized (invalid/missing API key)
- 404: Resource not found
- 429: Rate limit exceeded
- 500: Server error

## Example: Register Device

Request:
```bash
curl -X POST https://api.trillboards.com/v1/partner/device \
  -H "Authorization: Bearer trb_partner_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "vending-001-nyc",
    "name": "NYC Office Lobby Vending",
    "device_type": "vending_machine",
    "location": {
      "lat": 40.7128,
      "lng": -74.0060,
      "venue_type": "office",
      "city": "New York",
      "state": "NY",
      "country": "US"
    }
  }'
```

Response:
```json
{
  "success": true,
  "message": "Device registered",
  "data": {
    "device_id": "6507a1b2c3d4e5f6g7h8i9j0",
    "external_device_id": "vending-001-nyc",
    "fingerprint": "P_a1b2c3d4e5f6g7h8",
    "screen_id": "6507a1b2c3d4e5f6g7h8aa11",
    "status": "active",
    "embed_url": "https://screen.trillboards.com?fp=P_a1b2c3d4e5f6g7h8",
    "enrichment_status": "pending"
  }
}
```

## Example: Get Partner Dashboard

Request:
```bash
curl https://api.trillboards.com/v1/partner/dashboard \
  -H "Authorization: Bearer trb_partner_xxxxx"
```

Response:
```json
{
  "success": true,
  "data": {
    "partner": { "name": "Acme Vending Co", "slug": "acmevending", "status": "active" },
    "stats": {
      "total_screens": 150,
      "active_screens": 142,
      "offline_screens": 8,
      "total_impressions_today": 45000,
      "total_impressions_week": 315000,
      "total_impressions_month": 1350000
    },
    "earnings": {
      "revenue_share_percent": 70,
      "total_earned_cents": 4500000,
      "available_payout_cents": 125000,
      "pending_payout_cents": 0
    },
    "top_screens": [...],
    "recent_activity": [...],
    "stripe_status": { "account_status": "active" }
  }
}
```

## Example: Invite Team Member

Request:
```bash
curl -X POST https://api.trillboards.com/v1/partner/team/invite \
  -H "Authorization: Bearer trb_partner_xxxxx" \
  -H "X-User-Token: <owner_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "teammate@company.com",
    "role": "admin",
    "name": "Jane Doe"
  }'
```

Response:
```json
{
  "success": true,
  "message": "Invitation sent successfully",
  "data": {
    "membership_id": "6507a1b2c3d4e5f6g7h8i9j0",
    "email": "teammate@company.com",
    "role": "admin",
    "status": "pending",
    "expires_at": "2026-02-02T12:00:00.000Z"
  }
}
```

## Example: Data API Semantic Search

Request:
```bash
curl "https://api.trillboards.com/v1/data/semantic-search?q=sports%20bar%20crowd&limit=10&since=24h" \
  -H "X-API-Key: trb_data_xxxxx"
```

Response:
```json
{
  "query": "sports bar crowd",
  "results_count": 3,
  "time_window": "24h",
  "results": [
    {
      "screen_id": "6507a1b2c3d4e5f6g7h8i9j0",
      "scene_description": "Lively sports bar with crowd watching game on multiple screens, high energy",
      "similarity": 0.89,
      "window_end": "2026-02-28T02:30:00.000Z"
    }
  ]
}
```

## Example: Data API Aggregate Analytics

Request:
```bash
curl "https://api.trillboards.com/v1/data/aggregate?group_by=daypart&metric=avg_attention&since=7d" \
  -H "X-API-Key: trb_data_xxxxx"
```

Response:
```json
{
  "group_by": "daypart",
  "metric": "avg_attention",
  "time_window": "7d",
  "aggregations": [
    { "group_key": "evening", "sample_count": 1250, "avg_value": 0.72, "min_value": 0.15, "max_value": 0.98 },
    { "group_key": "afternoon", "sample_count": 980, "avg_value": 0.65, "min_value": 0.10, "max_value": 0.95 }
  ]
}
```

## SDK Integration

For web-based displays, load the embed_url in an iframe or WebView:
```html
<iframe src="https://screen.trillboards.com?fp=P_abc123"
        style="width:100%;height:100%;border:none;">
</iframe>
```

The SDK automatically:
- Fetches and rotates ads
- Caches ads for offline playback
- Tracks impressions
- Reports heartbeat status

For programmatic-only usage (default for the Lite SDK), trigger ads via:
```
window.TrillboardsLite.show()
```
Direct ad fallback is opt-in via the Lite SDK `waterfall` options
(`programmatic_then_direct` or `direct_only`).

---

## CTV Measurement SDK

Audience-measurement SDK for Connected TV. Two runtimes, one wire format. The
canonical quickstart is rendered at <https://trillboards.com/partners/quickstart>
and the raw markdown lives at
<https://api.trillboards.com/docs/integrations/ctv-measurement-quickstart.md>.

### Coordinates

- npm: `@trillboards/ctv-measurement` (CTV web, smart-TV web apps, ATSC 3.0
  Broadcaster Applications, HbbTV receivers, React Native)
- Gradle / Maven: `com.trillboards:ctv-measurement:1.3.2`
  (Android TV / Fire TV / native tablet apps; built on the same
  `agent-core-lite` proximity stack the Trillboards in-house fleet runs in
  production today)

### Get an API key (self-serve)

Web form: <https://trillboards.com/partners/get-started>

API: `POST https://api.trillboards.com/v1/partner/register` with body
`{ "name": "...", "slug": "...", "contact_email": "...",
"api_agreement_accepted": true }`. The response contains a one-time `api_key`
of the form `trb_partner_xxxxx` (also issued as `tb_prt_xxxxx`) — your
Trillboards Partner API key. It carries the `sdk:*` scope by default, so the
same key authenticates ad-serving AND this measurement SDK — no separate CTV
key, no email round-trip, no sales call. Manage / rotate / revoke the key in
the earner portal at
<https://trillboards.com/earner/settings?tab=api> under **Partner API**.

### Endpoints

The SDKs call these endpoints automatically. All accept the same Trillboards
Partner API key (`trb_partner_*` / `tb_prt_*`) via the
`Authorization: Bearer <key>` header.

| Method | Path                                         | Purpose                                              |
|--------|----------------------------------------------|------------------------------------------------------|
| POST   | `/v1/partner/register`                       | Self-serve Partner API key minting (one-time)        |
| POST   | `/v1/partner/device/{deviceId}/heartbeat`    | Audience-measurement heartbeat (every 30 s)          |
| POST   | `/v1/partner/api-key/rotate`                 | Rotate your Partner API key without downtime         |
| GET    | `/v1/partner/info`                           | Read the partner record (slug, scoped regions, etc.) |

### npm install (CTV web / smart-TV / ATSC 3.0 / HbbTV / React Native)

```bash
npm install @trillboards/ctv-measurement
```

```ts
import { CtvMeasurement } from '@trillboards/ctv-measurement';

const sdk = new CtvMeasurement({
  apiKey: 'trb_partner_YOUR_KEY',
  deviceId: 'your-device-id',
});
sdk.setConsentStatus(true); // consent gate — measurement is inert until this
await sdk.measure();         // composes payload, POSTs heartbeat, returns result
```

### Gradle / Maven install (Android native — Android TV / Fire TV / tablet)

`settings.gradle.kts`:

```kotlin
dependencyResolutionManagement {
  repositories { maven { url = uri("https://maven.trillboards.com") } }
}
```

`app/build.gradle.kts`:

```kotlin
dependencies {
  implementation("com.trillboards:ctv-measurement:1.3.2")
}
```

`MainActivity.kt` (or `Application.onCreate`):

```kotlin
import com.trillboards.measurement.TrillboardsMeasurement

TrillboardsMeasurement.initialize(
  context = this,
  apiKey = "trb_partner_YOUR_KEY",
  deviceId = "your-device-id",
)
TrillboardsMeasurement.setConsentStatus(true)
TrillboardsMeasurement.startScheduledScans()
```

`startScheduledScans()` runs the BLE / WiFi / mDNS / SSDP / HTTP-probe
scanners on a 30-second cadence and POSTs each snapshot as a heartbeat.

### Consent gate (GDPR / CCPA)

Both SDKs are inert until `setConsentStatus(true)` is called. No network
traffic, no scanning, no fingerprinting. Revoke with `setConsentStatus(false)`;
in-flight requests complete but no new measurements are emitted.

### Platform target matrix

| Runtime                                  | Universal core | Broadcast metadata           | Path        |
|------------------------------------------|----------------|------------------------------|-------------|
| ATSC 3.0 Broadcaster Application         | yes            | yes (A/344 `localhost:` WS)  | npm SDK     |
| HbbTV 2.0+ receiver                      | yes            | yes (`oipfObjectFactory`)    | npm SDK     |
| Samsung Tizen TV web app                 | yes            | no (privileged only)         | npm SDK     |
| LG webOS TV web app                      | yes            | no (privileged only)         | npm SDK     |
| Vizio SmartCast web app                  | yes            | no                           | npm SDK     |
| Fire TV / Google TV / Android TV WebView | yes            | no (bridge to native)        | npm SDK     |
| Android TV / Fire TV native app          | yes            | n/a                          | Android AAR |
| Android tablet / phone                   | yes            | n/a                          | Android AAR |
| Roku BrightScript / SceneGraph           | n/a            | n/a                          | unsupported |
| Apple tvOS (TVMLKit / JSC)               | partial        | n/a                          | unsupported |

### Verification SQL

After the first heartbeat lands, confirm rows are arriving for your device:

```sql
SELECT source, count() AS rows
FROM trillboards.signal_observations
WHERE screen_mongo_id = 'your-device-id'
  AND observed_at > now() - INTERVAL 5 MINUTE
GROUP BY source
ORDER BY rows DESC;
```

You should see rows for `fingerprint` (every runtime) plus any of
`ble` / `wifi` / `mdns` / `ssdp` / `http_probe` / `broadcast` your platform
supports.

### Further reading

- Quickstart (web): <https://trillboards.com/partners/quickstart>
- Partner pitch: <https://trillboards.com/partners>
- Self-serve key form: <https://trillboards.com/partners/get-started>
- Quickstart (markdown): <https://api.trillboards.com/docs/integrations/ctv-measurement-quickstart.md>
- Native-bridge protocol: <https://api.trillboards.com/docs/integrations/partner-native-bridge.md>
- Partner integration cookbook: <https://api.trillboards.com/docs/integrations/ctv-measurement-partner-integration.md>
- Partner API OpenAPI: <https://api.trillboards.com/docs/openapi/partner-api.yaml>

---

# Trillboards DSP API
# Programmatic buying for DOOH inventory

## Overview
The DSP API lets demand-side platforms, agencies, and advertisers
programmatically discover, buy, and serve ads on Trillboards screens.

## Base URL
https://api.trillboards.com/openrtb/v2

## Authentication
Use the same self-minted platform key as MCP/reporting:
Authorization: Bearer <platform_api_key>

POST /openrtb/v2/onboard with that header links the same key to a DSP seat and
grants DSP capabilities. Prefixes do not authorize. Anonymous onboarding still
mints tb_dsp_* only for backwards compatibility.

## OpenAPI Specification
YAML: https://api.trillboards.com/docs/openapi/dsp-api.yaml
JSON (machine-readable, canonical for agents): https://api.trillboards.com/openrtb/v2/openapi.json
Discovery: https://api.trillboards.com/api/discover?surface=demand

## Quick Start
1. Mint one key in Earner Settings → Partner API, or headlessly via POST /v1/partner/agent/register
2. POST /openrtb/v2/onboard with Authorization: Bearer <same_key>
3. GET /openrtb/v2/adslots — browse screens with FEIN signals
4. POST /openrtb/v2/creatives — upload creative (URL or S3 presigned)
5. POST /openrtb/v2/creatives/:id/confirm — trigger AI moderation (upload mode)
6. GET /openrtb/v2/creatives/:id — check moderation status + IAB classification
7. POST /openrtb/v2/campaigns — create campaign with approved creative
8. POST /openrtb/v2/campaigns/assign — place on screens (30-60s delivery)

## Endpoints

### Onboarding
POST /openrtb/v2/onboard — Link the supplied platform key to a sandbox DSP seat.
  Body: { company_name, seat_id, contact_email }
  Auth: Authorization: Bearer <platform_api_key> (recommended, reuses key)
  Legacy: no auth mints a tb_dsp_* key once

### Inventory Discovery
GET /openrtb/v2/adslots — Browse screens with live FEIN signals (face count, attention, emotion, VAS).
  Query: ?venue_type=retail&country=US&min_vas=5.0&min_attention=60
POST /openrtb/v2/forecast — Estimate impressions for budget + targeting.
  Body: { budget_usd, targeting: { country, venue_type }, start_date, end_date }
POST /openrtb/v2/discover — Semantic search ("busy coffee shops in NYC").
  Body: { query: "...", limit: 20 }

### Real-Time Bidding
POST /openrtb/v2/bid — Submit OpenRTB 2.6 bid response. Validated against floors + blocklists. Bids enter live waterfall auction.
  Auth: Authorization: Bearer <platform_api_key> + bid:write (sandbox bids don't enter live auction)
GET /openrtb/v2/stats — 24h performance metrics: bids, wins, CPM, latency.

### Bilateral Exchange Bidstream
POST /openrtb/bidder/{connection_alias}/bid — Configured supply-side OpenRTB request endpoint.
  Auth: exchange connection alias/config, optional IP allowlist/mTLS/signature; no platform key per request.
GET callback URLs /win, /imp, /loss — use the self-authenticating URLs returned in each bid.

### Creatives (AI Moderation Pipeline)
POST /openrtb/v2/creatives — Upload creative. Two modes:
  URL mode: { name, content_type, creative_url } — moderation starts immediately
  Upload mode: { name, content_type, filename } — returns presigned S3 URL
POST /openrtb/v2/creatives/:id/confirm — After presigned upload, triggers Gemini AI moderation.
GET /openrtb/v2/creatives — List creatives. ?status=approved&limit=50
GET /openrtb/v2/creatives/:id — Full creative detail:
  - AI moderation status (pending/approved/rejected)
  - Content classification (alcohol, tobacco, gambling, violence, profanity)
  - Age rating (G/PG/PG-13/R/NC-17)
  - IAB categories (IAB1-IAB25)
  - Brand recognition

### Campaigns
POST /openrtb/v2/campaigns — Create campaign with approved creative + targeting. Returns matching screens.
  Body: { creative_id, name, targeting: { country, venue_type, city } }
POST /openrtb/v2/campaigns/assign — Place creative on specific screens.
  Body: { creative_id, screen_ids: [...], start_date, end_date, start_time, end_time }
  Screens pick up within 30-60 seconds.

### Deals
GET /openrtb/v2/deals — List available PMP/preferred/guaranteed deals.
GET /openrtb/v2/deals/:dealId — Deal details (floor, caps, dates).
POST /openrtb/v2/deals/propose — Propose a PMP deal (admin approval required).
  Body: { deal_id, floor_cpm, impression_cap, start_date, end_date }

### Reporting
GET /openrtb/v2/reports/summary — Impressions, CPM, fill rate, unique screens. ?days=7
GET /openrtb/v2/reports/screens — Per-screen performance breakdown. ?days=7&limit=50
GET /openrtb/v2/reports/timeseries — Hourly or daily trends. ?days=7&granularity=hourly

## Rate Limits
Bidding: 1,000 req/min | Inventory: 200 req/min | Campaigns: 100 req/min | Onboard: 5/hr
Sandbox mode: 100 req/min for all endpoints.

## Error Codes (DSP API)
Every 4xx/5xx response uses the unified `DspErrorResponse` envelope:
  { success: false, error: "<human>", error_code: "<snake_case>", request_id: "req_<uuid>", ...extras }
Optional `extras` keys: param, retry_after_seconds, required_scope, granted_scopes, nbr (bid only).

# Authentication / authorization (4xx — fix the request; do not retry)
- authentication_required — API key missing or DSP context not populated. Send `x-api-key` or `Authorization: Bearer <key>`.
- not_authorized — API key resolved but does not own the requested resource.
- missing_scope — API key lacks the scope required by this route. `extras.required_scope` names the missing scope; `extras.granted_scopes` lists what the key has.

# Validation (4xx — fix the payload; do not retry)
- missing_required_field — `extras.param` names the missing field.
- missing_name — creative or campaign upload missing the `name` field.
- missing_content_type — creative upload missing `content_type`.
- missing_creative_id — campaign/assignment missing `creative_id`.
- missing_floor_cpm — deal proposal missing `floor_cpm`.
- invalid_eligible_screens — deal proposal sent an empty `eligible_screens`; send null (every screen) or a non-empty list of screen ids.
- missing_screen_ids — assignment missing the `screen_ids[]` array.
- missing_asset_url — creative upload missing `asset_url` or `creative_url`.
- missing_deal_id — deal lookup missing `deal_id`.
- invalid_email — contact_email failed format check on onboarding.
- invalid_seat_id — seat_id must match `^[a-z0-9_]+$` and be 3-40 chars.
- invalid_screen — screen_id does not resolve to a known Trillboards screen.
- invalid_budget — campaign budget out of allowed range or wrong type.
- invalid_date — date param is not ISO-8601 or violates start < end.
- invalid_webhook_url — webhook endpoint must be https:// and not localhost/private RFC1918.
- invalid_verification_tier — bidder requested a verification tier not enabled for their seat.
- invalid_bid_response — bid payload failed OpenRTB 2.6 schema validation; see `extras.nbr` for the no-bid reason code.
- invalid_events — webhook subscribe request listed events outside the allowlist.

# Resource state (4xx — most are not retryable without state change)
- seat_id_already_registered — onboarding with a seat_id that already exists; reuse the existing key.
- already_exists — generic conflict on a unique-key insert.
- deal_already_exists — POST /deals/propose against an existing deal_id.
- not_found — resource id not resolvable to anything the seat owns.
- creative_not_found — `creative_id` does not exist or is not owned by this seat.
- screen_not_found — `screen_id` does not exist.
- reservation_not_found — `reservation_id` does not exist or is not owned by this seat.
- deal_not_found — `deal_id` does not exist.
- webhook_not_found — `webhook_id` does not exist or is not owned by this seat.
- expired — reservation has passed its 15-min TTL; create a new one.

# Throttling (429 — retry after the indicated delay)
- rate_limited — Rate limit exceeded. `extras.retry_after_seconds` carries the cooldown. The `Retry-After` HTTP header is also set.

# Server (5xx — retry with exponential backoff; report `request_id` if persistent)
- api_key_provisioning_failed — onboard succeeded at the DB layer but the API key minting step failed. Re-call onboard.
- internal_error — caught uncaught exception. Retry once; if persistent, email developers@trillboards.com with `request_id`.
- unspecified_error — never used in practice; reserved fallback.

# Retry guidance summary
- 4xx → never retry the same payload. Fix and re-send.
- 429 → retry after `extras.retry_after_seconds` (or `Retry-After` header).
- 5xx → exponential backoff (e.g. 1s, 2s, 4s, 8s, max 60s) with at most 5 attempts. Include `request_id` from the response in support emails.

## FEIN Signals (Unique to Trillboards)
Screens with FEIN sensors provide real-time audience data in ext.trb.fein:
- live_face_count: people facing the screen (10s freshness)
- attention_score: gaze attention 0-1 (10s freshness)
- dominant_emotion: happy/sad/angry/neutral (10s freshness)
- vas_7d: Verified Attention Seconds, 7-day rolling average
- crowd_density: estimated venue occupancy
- purchase_intent: speech-derived intent level

---

# Proof-of-Play API
# Cryptographically signed ad impression verification

## Overview
Every ad impression on Trillboards is signed with Ed25519 cryptography.
Advertisers can export proofs and share them with third-party auditors
who verify signatures independently using our public key.

## API Base URL
Production: https://api.trillboards.com/v1/advertiser/proof

## OpenAPI Specification
Interactive docs (Scalar): https://api.trillboards.com/docs#measurement
Proof-of-Play OpenAPI spec: https://api.trillboards.com/docs/openapi/proof-of-play.yaml

## Philosophy: Open Verification, Closed Discovery
- PUBLIC: Signature verification (anyone can verify a proof they receive)
- RESTRICTED: Data discovery (only campaign owners can fetch proofs)

## Public Endpoints (No Auth)

### GET /.well-known/public-key
Returns Ed25519 public key for third-party signature verification.

Response:
```json
{
  "success": true,
  "publicKey": "a5a9c43785680c62ebcd01ec49a0d6055fd140023df0f142c3e37c6abafce34f",
  "algorithm": "ed25519",
  "version": "v2"
}
```

### POST /verify-proof
Verify a signature without needing the private key.

Request:
```json
{
  "signature": "ed25519=<hex>",
  "timestamp": 1705401600000,
  "adId": "campaign-abc123",
  "impressionId": "507f1f77bcf86cd799439011",
  "screenId": "screen-xyz789",
  "deviceId": "device-456"
}
```

Response:
```json
{
  "success": true,
  "verification": { "valid": true, "version": "v2" }
}
```

### GET /signature-info
Returns signature format documentation for integrators.

## Authenticated Endpoints (Bearer Token Required)

### GET /campaigns/{campaignId}/proof
Get signed proofs for a campaign. Owner only.
Supports cursor-based pagination via `cursor` query param.

Query params: startDate, endDate, limit (default 1000), cursor

### GET /screens/{screenId}/proof
Get proofs for a screen. Screen owner or advertiser who ran campaigns on it.
Supports cursor-based pagination.

### GET /campaigns/{campaignId}/audience-proof
Get per-screen impression counts for a campaign, with one aggregate signature over the roll-up. Owner only.

### POST /campaigns/{campaignId}/export-proof
Export proofs as JSON or CSV. Owner only.

## Signature Format

Version: v2 (Ed25519, current)
Payload: `version.timestamp.adId.impressionId.screenId.deviceId`
Signature prefix: `ed25519=`

Example proof object:
```json
{
  "impressionId": "507f1f77bcf86cd799439011",
  "adId": "campaign-abc123",
  "screenId": "screen-xyz789",
  "deviceId": "device-456",
  "timestamp": "2026-01-16T12:00:00.000Z",
  "eventType": "complete",
  "signature": "ed25519=a1b2c3d4e5f6...",
  "signatureVersion": "v2"
}
```

## Verification Example (Node.js)

```javascript
const crypto = require('crypto');

const PUBLIC_KEY_HEX = 'a5a9c43785680c62ebcd01ec49a0d6055fd140023df0f142c3e37c6abafce34f';

function verifyProof(proof) {
  const payload = `v2.${proof.timestamp}.${proof.adId}.${proof.impressionId}.${proof.screenId}.${proof.deviceId}`;
  const signatureHex = proof.signature.replace('ed25519=', '');
  const signatureBytes = Buffer.from(signatureHex, 'hex');

  const publicKey = crypto.createPublicKey({
    key: Buffer.concat([
      Buffer.from('302a300506032b6570032100', 'hex'),
      Buffer.from(PUBLIC_KEY_HEX, 'hex')
    ]),
    format: 'der',
    type: 'spki'
  });

  return crypto.verify(null, Buffer.from(payload), publicKey, signatureBytes);
}
```

## Verification Example (Python)

```python
from nacl.signing import VerifyKey

PUBLIC_KEY_HEX = 'a5a9c43785680c62ebcd01ec49a0d6055fd140023df0f142c3e37c6abafce34f'

def verify_proof(proof):
    verify_key = VerifyKey(bytes.fromhex(PUBLIC_KEY_HEX))
    payload = f"v2.{proof['timestamp']}.{proof['adId']}.{proof['impressionId']}.{proof['screenId']}.{proof['deviceId']}"
    signature_bytes = bytes.fromhex(proof['signature'].replace('ed25519=', ''))
    try:
        verify_key.verify(payload.encode(), signature_bytes)
        return True
    except:
        return False
```

## Legacy Support
Version v1 (HMAC-SHA256) is deprecated but still supported.
Signature prefix: `sha256=`
Use v2 Ed25519 for third-party verification.

---

---

# Attribution & Measurement API
# Closed-loop DOOH attribution with attention-verified impressions

## Overview
Trillboards provides the only deterministic DOOH attribution engine:
on-device computer vision measures actual human attention, third-party
mobile signals prove store visits, and Bayesian experiments measure
incremental lift. Every metric is MEASURED, not estimated.

## API Base URL
Production: https://api.trillboards.com/v1/advertiser/attribution
Authentication: Bearer JWT token

## OpenAPI Specification
Interactive docs (Scalar UI): https://api.trillboards.com/docs#measurement
Attribution OpenAPI spec: https://api.trillboards.com/docs/openapi/attribution-api.yaml
Attribution-focused AI guide: https://api.trillboards.com/llms-attribution.txt

## Key Concepts

### aCPM (Attention CPM)
Cost per 1,000 attention-verified impressions. Unlike standard CPM, aCPM only
counts impressions where someone was actually looking at the screen, as measured
by on-device face detection and gaze tracking.

### Incremental Lift
Percentage increase in store visits caused by the campaign, measured via
geo-holdout experiments with DMA-matched control groups. Not correlation — causation.

### CPIV (Cost Per Incremental Visit)
Total media cost / number of visits that would NOT have happened without the campaign.
The true cost of driving a store visit.

### Weighted Confidence
base_match_confidence * (1 + attention_weight). Combines spatial proximity
with FEIN attention verification for a single confidence score.

## Endpoints Summary

### Campaign Attribution
- GET /campaign/{id} — Comprehensive attribution summary (reach, visits, lift, CPIV)
- GET /campaign/{id}/timeseries — Daily attribution metrics over time
- GET /campaign/{id}/heatmap — Geospatial exposure and conversion density
- GET /campaign/{id}/journey — Attribution funnel (exposure -> visit -> transaction)

### Attention Metrics (Unique to Trillboards)
- GET /campaign/{id}/attention — aCPM, attention scores, dwell, emotion breakdown
- GET /campaign/{id}/attention/creative — Per-creative attention comparison
- GET /campaign/{id}/attention/timeseries — Attention fatigue detection over time

### Cross-Channel Attribution
- GET /campaign/{id}/multi-touch — Channel credit allocation (DOOH vs mobile vs web vs store)
- GET /campaign/{id}/cross-channel-journey — Sankey flow data for path visualization
- GET /campaign/{id}/channel-roas — Per-channel ROAS comparison

### Incrementality Measurement
- POST /experiment — Create geo-holdout, ghost ad, or PSA control experiment
- GET /experiment/{id} — Experiment results (Bayesian + frequentist)
- GET /experiment/{id}/power — Sample size needed for target MDE
- GET /campaign/{id}/incrementality — Campaign-level Bayesian uplift

### Creative Attribution
- GET /campaign/{id}/creative-attribution — Creative x outcome x context correlation
- GET /campaign/{id}/creative-attribution/{creativeId}/timeseries — Creative fatigue over time

### Signal Transparency
- GET /campaign/{id}/signal-quality — Data coverage, freshness, and confidence
- GET /campaign/{id}/methodology — Human-readable explanation of attribution methodology

### Cohort Export
- POST /campaign/{id}/cohort/export — Export MAID list to TTD, DV360, or Meta

## Cross-Channel Event Ingestion
- POST /v1/attribution/event/mobile — DSP postback (impressions/clicks)
- GET /v1/attribution/pixel/{advertiserId}/{campaignId} — 1x1 web tracking pixel
- POST /v1/attribution/event/transaction/:sourceId — Transaction/purchase data (per-source HMAC via X-Trill-Signature)

---

# OpenRTB 2.6 Signal Extensions
# Proprietary signals in every bid request

## Overview
Trillboards injects 30+ proprietary signals into OpenRTB 2.6 DOOH bid requests.
These signals are MEASURED by on-device edge AI, not estimated.

## Documentation
Schema reference: https://api.trillboards.com/docs/guides/openrtb-extensions
Schema spec: https://api.trillboards.com/docs/openapi/openrtb-extensions.yaml
Executable programmatic routes: https://api.trillboards.com/docs/openapi/programmatic-api.yaml

## Signal Namespaces

### ext.trillboards — Real-Time Audience (10-30s fresh)
- attention_score: Fraction of faces looking at screen (0-1, gaze detection)
- audience_count: Average face count
- crowd_density: Peak face count
- ad_receptivity: Audio-derived venue receptivity (0-1, YAMNet TFLite)
- emotional_engagement: Facial expression engagement (0-1)
- mood: Venue mood (energetic/calm/focused/social/neutral)
- estimated_occupancy: Venue occupancy estimate
- avg_dwell_ms: Average face dwell time
- signals_age_ms: Signal freshness (lower = fresher)
- reliability_score: Screen reliability from unified telemetry
- audience_quality: Audience data quality score
- screen_quality_composite: Combined quality score

### ext.trb.vas — Verified Attention Seconds (7-day rolling)
- predicted_vas: Predicted VAS for next impression
- historical_vas_avg: 7-day average VAS
- median_vas, p90_vas: Distribution metrics
- avg_face_count, avg_attention_score: Historical averages

### ext.trb.intent — Purchase Intent (10-30s fresh)
- score: Composite intent score (0-1)
- purchase_stage: READY_TO_BUY / COMPARING / CONSIDERING / BROWSING / NONE
- categories: Detected product interest categories
- brand_mentions: Whether brand names detected in ambient audio

### ext.trb.weather — Contextual Weather (60-min cache)
- temp_f, humidity, condition, uv_index, wind_mph, is_raining
- temp_segment: hot / warm / cool / cold

### ext.trb.foot_traffic — Venue Occupancy (10-30s fresh)
- current_audience, estimated_occupancy, avg_dwell_seconds
- traffic_tier: very_low / low / medium / high / very_high

### user.data[] — IAB Audience Taxonomy 1.1 Segments
Income (1001-1005), Lifestyle (2001-2020), Purchase Intent (3001-3003)
Plus seller-defined segments: venue (trb_vn_*), geo (trb_geo_*),
traffic (trb_trf_*), dwell (trb_dwl_*), daypart (trb_dpt_*), quality (trb_qly_*)

---

# FEIN Edge AI API
# On-device computer vision and audio classification

## Overview
FEIN (Face-detection Edge Intelligence) runs ML Kit and YAMNet TFLite
on CTV tablets. The FEIN API exposes analytics, webhooks, and SSE streaming.

## Documentation
Interactive docs (Scalar UI): https://api.trillboards.com/docs#demand
Programmatic & FEIN OpenAPI spec: https://api.trillboards.com/docs/openapi/programmatic-api.yaml

## FEIN Analytics (read, X-API-Key auth)
- GET /openrtb/v2/fein/creative-venue-performance — Creative x venue matrix
- GET /openrtb/v2/fein/fill-rate-by-venue — Fill rates by venue type
- GET /openrtb/v2/fein/screen-intelligence/{screenId} — Per-screen intelligence
- GET /openrtb/v2/fein/model-status — ML model deployment status
- GET /openrtb/v2/fein/audience-segments — Segment distribution
- GET /openrtb/v2/fein/inference-history — Historical inference results
- GET /openrtb/v2/fein/readiness — System readiness check

## Content Intelligence (read, X-API-Key auth)
- GET /openrtb/v2/fein/content-performance/{videoId} — How a video performs across the network (plays, attention, audience, venues)
- GET /openrtb/v2/fein/content-recommendations — Best content for a venue + time + audience context
- POST /openrtb/v2/fein/content-semantic-search — Natural language search over content embeddings (768-D pgvector)
- GET /openrtb/v2/fein/content-audience-correlation — Content category × audience demographic breakdown

## FEIN Webhooks & SSE
- POST /openrtb/v2/fein/webhooks — Register webhook for real-time events
- GET /openrtb/v2/fein/webhooks — List registered webhooks
- DELETE /openrtb/v2/fein/webhooks/{id} — Remove webhook
- GET /openrtb/v2/fein/stream — SSE event stream (inference_complete, attribution_updated, model_slice_updated, creative_outcome_updated)

---

# Attribution Data Model
# 6-layer pipeline from signal to insight

## Documentation
Schema reference: https://api.trillboards.com/docs/guides/attribution-data-models
Attribution data model spec: https://api.trillboards.com/docs/openapi/attribution-data-models.yaml

## Pipeline Layers

### Layer 1: Signal Ingestion
device_signals (Intuizi mobile pings) + poi_reference (brand locations)

### Layer 2: Exposure Matching
exposure_device_matches — PostGIS ST_DWithin joins device signals with ad plays

### Layer 3: Attention Enrichment
attention_exposure_matches — FEIN edge AI signals joined with exposures

### Layer 4: Identity Resolution
identity_nodes + identity_edges + household_clusters — cross-device graph

### Layer 5: Attribution
touchpoint_events + attribution_chains — multi-touch credit allocation

### Layer 6: Measurement
incrementality_experiments + incrementality_results + creative_attribution_performance

---

## Support

- Public API index: https://api.trillboards.com/docs/openapi.yaml
- Documentation: https://api.trillboards.com/docs/guides
- Email: developers@trillboards.com
- Partner API docs: https://api.trillboards.com/docs#partner
- Proof-of-Play API docs: https://api.trillboards.com/docs#measurement
- Attribution API docs: https://api.trillboards.com/docs#measurement
- Programmatic & FEIN docs: https://api.trillboards.com/docs#demand
- OpenRTB Extensions docs: https://api.trillboards.com/docs/guides/openrtb-extensions
- Data Model docs: https://api.trillboards.com/docs/guides/attribution-data-models
- Partner API spec: https://api.trillboards.com/docs/openapi/partner-api.yaml
- Proof-of-Play API spec: https://api.trillboards.com/docs/openapi/proof-of-play.yaml
- Attribution API spec: https://api.trillboards.com/docs/openapi/attribution-api.yaml
- Programmatic & FEIN API spec: https://api.trillboards.com/docs/openapi/programmatic-api.yaml
- OpenRTB Extensions schema spec: https://api.trillboards.com/docs/openapi/openrtb-extensions.yaml
- Attribution data model spec: https://api.trillboards.com/docs/openapi/attribution-data-models.yaml
- Attribution AI guide: https://api.trillboards.com/llms-attribution.txt
- Pricing endpoint: https://api.trillboards.com/v1/partner/pricing

---

# Machine-Readable Pricing
# Usage-based graduated pricing for all products

## Endpoint
GET https://api.trillboards.com/v1/partner/pricing

No authentication required. Returns the full pricing catalog in JSON.

## MCP Tool
Use the `get_pricing` MCP tool (no auth required) to fetch the same data
programmatically via MCP. Optionally filter by product:

```json
{ "name": "get_pricing", "arguments": { "product": "data_api" } }
```

## Pricing Model
All products use graduated usage-based pricing:
- **Free tier**: Every product has a generous free tier (no credit card needed)
- **Graduated volume**: Unit cost decreases as usage increases
- **Committed use**: Pre-commit to monthly spend for 10-40% additional discount
- **Annual discount**: Additional 10% off on annual commitments

## Products & Free Tiers
| Product | Free Tier | Unit |
|---------|-----------|------|
| Data API | 10,000/mo | API calls |
| Proof of Play | 1,000/mo | Proofs |
| Attribution | First campaign | Free trial |
| Data Marketplace | 5,000/mo | Queries |
| Partner Platform | Unlimited | Free forever (rev share) |
| Programmatic | Unlimited | Free (20% media fee) |
| FEIN Edge AI | Unlimited | Free for screen owners |

## Usage Tracking
Authenticated partners can check usage via:
- MCP tool: `get_usage_summary` (requires API key)
- REST: GET /v1/partner/usage

---

# AI Agent Quick Start (Zero Human Interaction)
# 5-step fully automated integration flow

## Step 1: Discover
Fetch pricing and capabilities — no signup required:
```bash
curl https://api.trillboards.com/v1/partner/pricing
curl https://api.trillboards.com/.well-known/adagents.json
```

Or via MCP:
```json
{ "name": "get_pricing" }
{ "name": "get_adcp_capabilities" }
```

## Step 2: Register
Create a partner account and receive an API key instantly:
```bash
curl -X POST https://api.trillboards.com/v1/partner/register \
  -H "Content-Type: application/json" \
  -d '{"company_name":"Acme AI","email":"ai@acme.com","contact_name":"AI Agent"}'
```

Or via MCP:
```json
{ "name": "register_partner", "arguments": { "company_name": "Acme AI", "email": "ai@acme.com" } }
```

Save the returned `api_key` — it is shown only once.

## Step 3: Discover Inventory
Browse available screens filtered by venue, location, or audience:
```json
{ "name": "discover_inventory", "arguments": { "venue_types": ["retail"], "location": { "city": "New York" } } }
```

## Step 4: Create Campaign
Launch a media buy targeting discovered screens:
```json
{
  "name": "create_media_buy",
  "arguments": {
    "name": "Q1 Retail Push",
    "buy_spec": {
      "venue_types": ["retail"],
      "budget": { "daily_usd": 100, "bid_cpm": 4.0 }
    },
    "creative": { "url": "https://cdn.acme.com/ad.mp4", "type": "video", "duration_seconds": 15 }
  }
}
```

## Step 5: Monitor & Optimize
Check delivery, provide feedback, log conversions:
```json
{ "name": "get_media_buy_delivery", "arguments": { "media_buy_id": "mbuy_..." } }
{ "name": "get_usage_summary" }
```

Total time: Under 60 seconds. No human approval gates. No credit card for free tier.

---

# Scored RL environment trials

Free source-bound scored trials, with reference runs and actor/verifier environments:
https://api.trillboards.com/docs/guides/integrations/rl-environments.md

Machine-readable trial downloads, task IDs, ZIP hashes and full-package marketplace links:
https://api.trillboards.com/docs/integrations/rl-environments.json

The recorded creative-feedback suite's public evaluation run on HUD, with every trace:
https://hud.ai/jobs/a5c98ef7-7d39-4920-bd65-a0c521ef10f6

# Creative AI feedback loop

Optimize model-generated images against attention and dwell from actual paid screen plays. The self-serve flow uses one partner buying account and the same native media buy, creative moderation, brand review and reporting APIs.

1. Discover inventory and fund a media buy; keep media_buy_id and package_id.
2. create_creative_experiment, then configure_feedback_brand.
3. generate_brand_creative or import_feedback_creative (image URL, same-partner source creative, or inline PNG/JPEG/WebP bytes).
4. review_feedback_creative; register_creative_variants once brand approval and AI moderation complete. Register your immutable model_version with each variant.
5. update_creative_policy with the current policy_version. Eligible updated weights affect the next signed paid play.
6. get_creative_rewards with fixed inclusive dates and a fresh idempotency_key for every page/poll. Follow next_cursor, then rewind after scan_complete. Apply upserts/retractions by canonical_key and deduplicate reward_revision_id.

Measured rewards refresh every five minutes, with a daily 48-hour correction sweep. Gaze share is 0–1; dwell/overlap are milliseconds; NULL means unmeasured. creative_feedback retains the issued variant, model, policy, bytes, render and selection probability for each actual play.

Media is funded against its contracted inventory/CPM quote. Generation, import and every reward page use the separate existing data_api/api_calls tariff/free quota and return usage_receipt. Free creative.rewards_ready webhook/SSE hints wake your reader; reconnect recovers through a bounded full rescan. A committed operation key returns 409 OPERATION_ALREADY_COMMITTED with its original receipt and server-derived creativeId/renderKey for generation/import. get_creative_experiment exposes the native creatives list (latest 500; creatives_truncated when more exist) for response recovery. Use a new key for new work.

Self-service partner account and API key quickstart (Markdown):
https://api.trillboards.com/docs/guides/quickstart/partner.md

Creative AI Feedback Loop: REST, MCP and TypeScript SDK walkthrough (Markdown):
https://api.trillboards.com/docs/guides/integrations/creative-feedback.md

Historical HUD packages reuse verified native play exports and immutable vintages; the live HUD adapter calls the same authenticated MCP tools.

# MCP Connection Details
# Connect from Claude Desktop, Cursor, or any MCP client

## Server URL
https://api.trillboards.com/mcp

## Transport
Streamable HTTP (MCP Protocol Version 2025-11-25)

## Authentication
For the open tools (get_products, get_pricing, get_adcp_capabilities,
list_creative_formats, register_partner and the discovery tools):
No headers required.

For authenticated tools:
```
Authorization: Bearer <platform_api_key>
```

Protected tools require mcp:tools plus the relevant domain capability (for
example inventory:read, reports:read, stats:read, or campaigns:write). Legacy
partner scopes preserve owned-screen behavior. Existing header alias:
```
X-Trillboards-API-Key: <platform_api_key>
```

## Claude Desktop Configuration
Add to your `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "trillboards": {
      "url": "https://api.trillboards.com/mcp",
      "headers": {
        "Authorization": "Bearer <platform_api_key>"
      }
    }
  }
}
```

## Cursor Configuration
Add to your `.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "trillboards": {
      "url": "https://api.trillboards.com/mcp",
      "headers": {
        "Authorization": "Bearer <platform_api_key>"
      }
    }
  }
}
```

## Agent Identification
Set `X-MCP-Client-Name` header to identify your agent (optional but recommended):
```
X-MCP-Client-Name: my-trading-desk-agent
```

## Direct Streamable HTTP Tool Call
Initialize/list tools using normal MCP protocol, then invoke tools with JSON-RPC:
```bash
curl -sS -X POST https://api.trillboards.com/mcp \
  -H 'Authorization: Bearer <platform_api_key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'X-MCP-Client-Name: my-trading-desk-agent' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "discover_inventory",
      "arguments": { "venue_types": ["retail"], "limit": 20 }
    }
  }'
```

Start with `tools/list`. `get_products` needs no key at all — call it with a
natural-language `brief` to read the catalogue before you decide to transact.
Then use `discover_inventory`, `get_audience_forecast`, `get_signals`, and
`get_network_stats` as allowed by the key's capabilities. Mutation tools such as
`activate_signal` and `create_media_buy` require write capabilities.

## Available Tools (Unauthenticated)
- get_products — Full DOOH product catalogue. Send a natural-language `brief`
  ("commuters who are bored and hungry around lunchtime") and each product's
  description answers it from what the screens actually observed: the hours
  people are in frame in local time, dwell, the mood/movement/gaze the sensors
  reported, what speech sensing heard people shopping for, and which of your
  words we cannot evidence. Products are ordered by that evidence. A key is
  needed only to buy.
- get_pricing — Pricing catalog with free tiers
- get_adcp_capabilities — Platform capability discovery
- register_partner — Instant partner registration
- list_creative_formats — Creative sizes and durations the screens play
- list_endpoints, describe_endpoint, validate_request, list_error_codes, query_changelog — The HTTP API, self-described
- get_device_ads — Fetch ads for a device

## Screen-Owner Tools (partner key of the screen's owner)
- record_impression — Record a single impression
- batch_impressions — Record up to 100 impressions
- device_heartbeat — Report device online status

## Available Tools (Authenticated)
- get_partner_info, register_device, list_devices, get_device, delete_device
- get_analytics, get_usage_summary
- create_webhook, list_webhooks, update_webhook, delete_webhook, test_webhook, get_webhook_deliveries
- discover_inventory, get_live_audience, get_audience_forecast
- create_campaign, get_campaign_performance, get_network_stats
- get_signals, activate_signal
- create_media_buy, update_media_buy, sync_creatives
- get_media_buy_delivery, provide_performance_feedback, log_event

## Available Tools (Attribution & Measurement)
- get_campaign_attribution — Comprehensive attribution summary (reach, visits, lift, CPIV)
- get_attribution_timeseries — Daily attribution metrics over time
- get_attention_metrics — aCPM, attention scores, dwell, emotion breakdown
- get_creative_attention — Per-creative attention comparison
- get_multi_touch_attribution — Channel credit allocation (DOOH vs mobile vs web vs store)
- get_cross_channel_journey — Sankey flow data for path visualization
- get_incrementality — Campaign-level Bayesian uplift
- create_experiment — Create geo-holdout, ghost ad, or PSA control experiment
- get_creative_attribution — Creative x outcome x context correlation
- get_roas — Per-channel ROAS comparison
- export_cohort — Export MAID list to TTD, DV360, or Meta
- get_audience_lookalike — Find screens with similar audience profiles
- semantic_audience_search — Natural language audience discovery
- get_campaign_heatmap — Geospatial exposure and conversion density
- verify_proof_of_play — Cryptographic proof verification for impressions

---

# Error reference
# Source: https://api.trillboards.com/docs/errors.md

# Trillboards API Error Reference

Every external Trillboards API endpoint returns errors using the canonical
envelope below. Phase 1 of the API DX overhaul locks this contract; Phase 2+
migrates each remaining surface onto it.

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "screen_not_found",
    "message": "Screen 'scr_xxx' not found or access denied.",
    "param": "screen_id",
    "doc_url": "https://api.trillboards.com/docs/errors#screen_not_found",
    "request_id": "req_a1b2c3d4e5f6789012345678901234ab",
    "details": [
      { "param": "screens[0].orientation", "code": "invalid_enum", "message": "Must be 'landscape' or 'portrait'." }
    ],
    "help": {
      "summary": "Screen IDs are prefixed 'scr_'. List your screens at GET /v1/partner/screens.",
      "suggestions": ["scr_abc123", "scr_def456"],
      "portal_url": "https://trillboards.com/earner/screens",
      "try_next": "/api/discover?q=screen"
    }
  }
}
```

**Field rules**

- `type` is one of `invalid_request_error` (4xx client), `authentication_error` (401),
  `permission_error` (403), `rate_limit_error` (429), `idempotency_error` (409),
  `api_error` (5xx).
- `code` is stable and machine-readable; it never changes across versions.
- `details` is present only when multiple field-level violations exist (e.g. a
  Zod validation result with more than one issue).
- `help` is present only when we have structured remediation context.
- `request_id` matches the `X-Request-Id` response header and is always set.
- `doc_url` is always computable as `https://api.trillboards.com/docs/errors#<code>`.

**HTTP status codes never change as part of the body migration.** Callers can
opt back into the prior flat envelope `{ statusCode, message, code, param,
request_id }` by sending the header `X-Error-Shape: legacy`. This opt-in is
removed two weeks after Phase 1 ships.

---

## Authentication Errors

### AUTH_REQUIRED

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: Connect an authenticated native buying account.

### authentication_required

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: No API key or access token was supplied.

```json
{ "error": { "type": "authentication_error", "code": "authentication_required", "message": "Authentication required.", "param": null, "doc_url": "https://api.trillboards.com/docs/errors#authentication_required", "request_id": "req_…" } }
```

**How to fix**: include `Authorization: Bearer <key>` on the request.

### invalid_api_key

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: The API key was not recognised or is inactive.

**How to fix**: rotate the key in the portal and retry with the fresh value.

### invalid_api_key_format

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: The API key does not match the expected format.

**How to fix**: Partner keys begin with `trb_partner_`. Make sure you copied
the full key, including the prefix.

### api_key_expired

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: The API key has expired and must be rotated.

**How to fix**: rotate the key in the partner portal.

### api_key_revoked

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: The API key has been revoked and can no longer be used.

**How to fix**: issue a new key in the portal.

### auth_error

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: Generic authentication failure.

**How to fix**: verify credentials and retry. Contact support with the
`request_id` if the problem persists.

---

## Permission Errors

### CREATIVE_ADVERTISEMENT_NOT_OWNED

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: The native advertisement is not owned by the resolved advertiser.

### creative_policy_forbidden

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: The native creative policy belongs to another advertiser.

### insufficient_scope

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: The API key is valid but lacks the scope required for this endpoint.

**How to fix**: inspect `help.required_scope` and issue a key with the needed
scopes.

### insufficient_permissions

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: The caller does not have permission to perform this action.

**How to fix**: contact an account owner to grant access, or use a different key.

### partner_inactive

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: The partner account is not currently active.

**How to fix**: contact support to reactivate the partner account.

### forbidden

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: Access denied.

**How to fix**: verify the resource belongs to the authenticated caller.

### tier_insufficient

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: This endpoint requires a higher data-access tier than the caller has.

**How to fix**: upgrade the data-access tier. `help.required_tier` indicates the
minimum tier needed.

---

## Validation & Request Errors

### INVALID_FEEDBACK_CREATIVE

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Supply exactly one valid HTTPS URL, owned creative ID or base64 image with the native creative fields.

### SOURCE_CREATIVE_NOT_FOUND

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: The source creative ID has no asset in this buyer library.

### UNSUPPORTED_CREATIVE_TYPE

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The actual creative bytes or declared media type are unsupported for this native import or serving path.

### INVALID_CREATIVE_URL

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The creative download URL must use HTTPS and resolve to a public destination.

### CREATIVE_TOO_LARGE

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The creative exceeds the existing native media byte budget.

### INVALID_FEEDBACK_REQUEST

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: A required native creative-feedback field is invalid.

### EXPERIMENT_NOT_FOUND

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: The native experiment is absent or belongs to another buyer.

### INVALID_FEEDBACK_OBJECTIVE

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Choose gaze_share, gaze_overlap_ms or dwell_ms.

### MEDIA_BUY_NOT_FOUND

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: The native media package is absent or belongs to another buyer.

### INVALID_POLICY_VERSION

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Supply an exact nonnegative decimal BIGINT policy version string.

### INVALID_CREATIVE_WEIGHTS

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Use unique registered creatives with finite weights 0–1 and at least one positive weight.

### INVALID_VARIANTS

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Use 1–100 unique native variant and creative identities.

### BRAND_PROFILE_NOT_FOUND

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: The native brand profile is absent or belongs to another buyer.

### INVALID_BRAND_RULES

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The brand rules do not satisfy the existing native BrandRulesSchema.

### invalid_creative_policy

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The native creative policy owner, mode, version or weight generation is invalid.

### validation_error

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Request data failed validation. See `details[]` for per-field violations.

```json
{ "error": { "type": "invalid_request_error", "code": "validation_error", "message": "2 validation errors occurred.", "param": "email", "details": [ { "param": "email", "code": "invalid_string", "message": "Invalid email" }, { "param": "age", "code": "too_small", "message": "Must be >= 18" } ], "doc_url": "https://api.trillboards.com/docs/errors#validation_error", "request_id": "req_…" } }
```

**How to fix**: inspect every entry in `details[]` and resubmit with corrected values.

### not_found

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: The requested resource does not exist or is not visible to the caller.

**How to fix**: list resources first to find a valid ID.

### IDEMPOTENCY_CONFLICT

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The enrollment key belongs to different arguments.

### CREATIVE_POLICY_CONFLICT

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: Refresh the native policy: its version or owner changed.

### EXPERIMENT_COMPLETED

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The native creative experiment has stopped.

### CREATIVE_NOT_READY

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The native creative must be brand approved, moderated and linked to the funded advertisement.

### VARIANT_IDENTITY_CONFLICT

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: An existing variant keeps its creative bytes and model identity.

### OPERATION_IN_PROGRESS

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The metered native operation is still in progress; do not execute it again under another key.

### OPERATION_ALREADY_COMMITTED

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The metered native operation already committed; its existing usage receipt is returned in help.usage_receipt.

### BRAND_PROFILE_CONFLICT

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The supplied native brand profile belongs to another campaign or owner scope.

### CREATIVE_NOT_LINKED

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: Explicit brand approval did not link the creative into the enabled native campaign.

### creative_policy_conflict

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The native creative policy version, mode or integration owner changed.

### FEEDBACK_POLICY_REQUIRED

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: Use the versioned partner creative-feedback methods for this funded experiment.

### conflict

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The requested change conflicts with the current state of the resource.

**How to fix**: re-fetch the resource and retry with the latest version.

### missing_required_field

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: A required field was not supplied.

**How to fix**: inspect `param` and include the missing field in the request body.

### invalid_field_value

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: A field was supplied with an invalid value.

**How to fix**: consult the OpenAPI schema for the accepted set of values.

### invalid_field_type

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: A field had the wrong JSON type.

**How to fix**: ensure the field type matches the schema (string/number/boolean/array).

### preferences_must_be_object

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The `preferences` field must be a JSON object (got a non-object type).

**How to fix**: send `preferences` as a JSON object (`{ ... }`), not an array, string, or number.

### field_must_be_boolean

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The named field must be a boolean `true` or `false`.

**How to fix**: pass the field as a JSON boolean, not as `"true"`/`"false"` strings or `0`/`1`.

### field_must_be_array

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The named field must be an array.

**How to fix**: wrap the value in square brackets — `[value]` even for a single entry.

### array_items_must_be_strings

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Every element of the named array must be a string.

**How to fix**: cast numeric or object elements to strings before sending, or remove them.

### lbar_settings_must_be_object

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The `lbar_settings` field must be a JSON object.

**How to fix**: send `lbar_settings` as a JSON object (`{ ... }`), or omit the field to use defaults.

### pip_settings_must_be_object

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The `pip_settings` field must be a JSON object.

**How to fix**: send `pip_settings` as a JSON object (`{ ... }`), or omit the field to use defaults.

### invalid_json

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The request body was not valid JSON.

**How to fix**: send a JSON body and set `Content-Type: application/json`.

### field_too_long

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: A string field exceeded its maximum length.

**How to fix**: shorten the offending field.

### array_too_large

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: An array field exceeded the maximum number of allowed items.

**How to fix**: split the request into multiple batches.

### invalid_array_items

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: One or more items in an array had an invalid type or value.

**How to fix**: inspect each item and ensure all match the schema.

### conflicting_lists

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The same value appeared in both an allow list and a block list.

**How to fix**: remove the duplicate entry from one of the lists.

### screen_not_found

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: Screen not found or access denied.

**How to fix**: call `GET /v1/partner/screens` to list valid screen IDs.

### invalid_screen_id

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Screen ID is not in the expected format.

**How to fix**: screen IDs are alphanumeric strings — verify you are not
prepending prefixes or trailing spaces.

### preset_not_found

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: Content preset not found.

**How to fix**: list available presets via `GET /v1/partner/content-presets`.

### preset_id_required

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `preset_id` is required.

**How to fix**: supply a valid `preset_id` in the request body.

### preferences_required

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Either `preferences` or `preset_id` is required.

**How to fix**: include one of the two fields in the request body.

### screen_ids_required

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `screen_ids` must be a non-empty array.

**How to fix**: pass at least one screen ID.

### batch_size_exceeded

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: More screens were sent in one request than the batch limit allows.

**How to fix**: split the request into smaller batches.

### invalid_preferences

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `preferences` must be an object.

**How to fix**: supply `preferences` as a JSON object.

### invalid_preference_level

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `preference_level` is not one of the allowed values.

**How to fix**: use one of the supported preference levels.

### invalid_age_rating

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `max_age_rating` is not one of the allowed values.

**How to fix**: use one of the supported age ratings.

### invalid_display_mode

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `display_mode` is not one of the allowed values.

**How to fix**: use one of the supported display modes.

### invalid_orientation

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `screen_orientation` is not one of the allowed values.

**How to fix**: use `landscape` or `portrait`.

### invalid_sizing_mode

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `advertisement_sizing` is not one of the allowed values.

**How to fix**: use one of the supported sizing modes.

### invalid_lbar_position

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `l_bar.position` is not one of the allowed values.

**How to fix**: choose one of the supported l-bar positions.

### invalid_pip_position

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `pip.position` is not one of the allowed values.

**How to fix**: choose one of the supported picture-in-picture positions.

### invalid_ad_surface_mode

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `ad_surface_mode` is not one of the allowed values.

**How to fix**: choose one of the supported ad-surface modes.

### ad_interval_out_of_range

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `ad_interval_seconds` is outside the supported range.

**How to fix**: clamp the interval to the documented min/max.

### lbar_size_out_of_range

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `l_bar.size_percent` is outside the supported range.

**How to fix**: clamp the size to the documented min/max.

### pip_size_ratio_out_of_range

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `pip.size_ratio` is outside the supported range.

**How to fix**: clamp the ratio to the documented min/max.

### pip_margin_out_of_range

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `pip.margin_px` is outside the supported range.

**How to fix**: clamp the margin to the documented min/max.

### invalid_lbar_settings

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `l_bar` must be an object.

**How to fix**: pass `l_bar` as a JSON object.

### invalid_pip_settings

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `pip` must be an object.

**How to fix**: pass `pip` as a JSON object.

### invalid_currency

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `currency` is not one of the allowed values.

**How to fix**: use a supported ISO-4217 currency code.

### invalid_provider

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `provider` is not one of the allowed values.

**How to fix**: choose one of the supported header-bidding providers.

### floor_price_out_of_range

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `floor_price_cpm` is outside the supported range.

**How to fix**: clamp `floor_price_cpm` to the documented min/max.

### allocation_out_of_range

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `programmatic_allocation_percent` is outside the supported range.

**How to fix**: clamp the value to the documented min/max.

### timeout_out_of_range

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: `timeout_ms` is outside the supported range.

**How to fix**: clamp `timeout_ms` to the documented min/max.

### blocked_advertisers_too_large

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Too many blocked advertisers.

**How to fix**: split the blocklist or remove stale entries.

### blocked_iab_categories_too_large

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Too many blocked IAB categories.

**How to fix**: split the blocklist or remove stale entries.

### webhook_not_found

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: Webhook endpoint not found.

**How to fix**: list webhooks and confirm the ID.

### invalid_webhook_url

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The webhook URL must be a valid HTTPS URL.

**How to fix**: supply an `https://` URL.

### webhook_url_unreachable

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The supplied webhook URL did not respond.

**How to fix**: confirm DNS, TLS, and that the target returns 2xx on a
health probe.

### invalid_webhook_events

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The supplied webhook event list contains unsupported values.

**How to fix**: consult the webhook documentation for supported event types.

### webhook_limit_exceeded

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The maximum number of webhooks for this partner has been reached.

**How to fix**: delete unused webhooks before creating new ones.

### webhook_secret_expired

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The webhook signing secret has expired.

**How to fix**: rotate the signing secret.

### device_not_found

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: Device not found or access denied.

**How to fix**: list devices first to find a valid ID.

### invalid_device_id

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Device ID is not in the expected format.

**How to fix**: confirm the device ID format with documentation.

### device_already_registered

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The device is already bound to another screen.

**How to fix**: unbind the device from its current screen before re-registering,
or register a new device.

### invalid_fingerprint

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Device fingerprint is not in the expected format.

**How to fix**: confirm the fingerprint format with documentation.

### stream_not_found

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: Stream not found or access denied.

**How to fix**: list streams first to find a valid ID.

### invalid_stream_type

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Stream type is not one of the allowed values.

**How to fix**: use a supported stream type.

### stream_content_required

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Stream content (video URL, images, etc.) must be provided.

**How to fix**: supply at least one content field.

### invalid_media_url

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Media URL is not a valid URL.

**How to fix**: supply a valid absolute URL.

### insufficient_data

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: Not enough audience data has been collected for this screen yet.

**How to fix**: retry after the screen has accumulated more impressions.

### segment_not_found

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: Audience segment not found.

**How to fix**: list segments first to find a valid ID.

### segment_limit_exceeded

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: Maximum number of audience segments reached.

**How to fix**: delete unused segments before creating a new one.

### invalid_segment_rules

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: One or more segment rules are invalid.

**How to fix**: every rule must have `field`, `operator`, and `value`.

---

## Rate Limiting

### rate_limit_exceeded

- **Type**: `rate_limit_error`
- **HTTP status**: 429
- **Summary**: Too many requests in the current window. Retry after the advertised time.

Rate-limit responses also set the `Retry-After` header.

**How to fix**: back off for the seconds indicated by `Retry-After`, then retry.

### daily_quota_exceeded

- **Type**: `rate_limit_error`
- **HTTP status**: 429
- **Summary**: The caller has exhausted their daily API quota.

**How to fix**: wait until the next UTC day or upgrade the plan.

### concurrent_request_limit

- **Type**: `rate_limit_error`
- **HTTP status**: 429
- **Summary**: Too many concurrent requests are in flight for this caller.

**How to fix**: reduce request concurrency.

---

## Concurrency & Idempotency

### resource_locked

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The resource is currently being modified by another request.

**How to fix**: retry after the in-flight request completes.

### stale_data

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: The resource has been modified since it was last fetched.

**How to fix**: re-fetch the resource and resend the update with the new version.

### idempotency_key_in_use

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: A request with this idempotency key is already in flight.

**How to fix**: retry with the same key once the previous request completes,
or use a fresh key.

### idempotency_key_mismatch

- **Type**: `idempotency_error`
- **HTTP status**: 422
- **Summary**: The idempotency key was reused with a different request body.

**How to fix**: either match the original body or use a fresh idempotency key.

### idempotency_error

- **Type**: `idempotency_error`
- **HTTP status**: 409
- **Summary**: Generic idempotency failure.

**How to fix**: consult the more specific idempotency_* codes and retry.

---

## API Errors

### internal_error

- **Type**: `api_error`
- **HTTP status**: 500
- **Summary**: An unexpected server error occurred. See `request_id` for the log correlation token.

The message never leaks server internals. Always include the `request_id` when
filing a support ticket.

**How to fix**: retry after a backoff. If the issue persists, contact support
with the `request_id`.

### database_error

- **Type**: `api_error`
- **HTTP status**: 500
- **Summary**: A database error occurred.

**How to fix**: retry after a backoff.

### service_unavailable

- **Type**: `api_error`
- **HTTP status**: 503
- **Summary**: A downstream service is temporarily unavailable.

**How to fix**: retry after a short backoff.

### CREATIVE_MODERATION_UNAVAILABLE

- **Type**: `api_error`
- **HTTP status**: 502
- **Summary**: The image bytes were staged but native moderation publication failed; the API allowance is released. Retry the bytes with a new operation key.

### POLICY_NOT_AVAILABLE

- **Type**: `api_error`
- **HTTP status**: 503
- **Summary**: The native campaign policy is unavailable.

### BRAND_CONFIGURATION_FAILED

- **Type**: `api_error`
- **HTTP status**: 503
- **Summary**: The native brand profile could not enable this funded reactive advertisement.

### device_offline

- **Type**: `api_error`
- **HTTP status**: 503
- **Summary**: The device is currently offline and cannot answer the request.

**How to fix**: retry once the device reconnects, or send the command via a
queueable endpoint.

### analytics_unavailable

- **Type**: `api_error`
- **HTTP status**: 503
- **Summary**: The audience analytics service is temporarily unavailable.

**How to fix**: retry after a short backoff.

### timeout

- **Type**: `api_error`
- **HTTP status**: 504
- **Summary**: The upstream operation exceeded its time budget.

**How to fix**: retry. If the problem persists, contact support with the
`request_id`.

### error

- **Type**: `api_error`
- **HTTP status**: 500
- **Summary**: Unspecified error. Callers should inspect `message` and retry if appropriate.

**How to fix**: fall back to retry with backoff; escalate with `request_id` if
the issue is persistent.

### device_identity_underivable

- **Type**: `api_error`
- **HTTP status**: 400
- **Summary**: `POST /v1/partner/device` (V2 registration) could not derive a
  canonical device identity — make, model, and OS — from the supplied `ua`
  string and `hardware` overrides.

**How to fix**: check `param` (a comma-separated list of the fields that could
not be resolved, e.g. `make,model`), then either send a real browser/WebView
User-Agent string in `ua`, or supply `hardware.make` / `hardware.model` /
`hardware.os` explicitly to bypass UA parsing entirely.

---

## Data API

Errors specific to the `/v1/data/*` surface (Phase 2 migration).

### screen_not_in_scope

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: The requested screen is outside the API key's `scoped_screen_ids` allow-list.

**How to fix**: use a screen whose ID is listed in your API key's
`scoped_screen_ids`, or issue a new key without screen-level scoping. `GET
/v1/data/screens` returns the full set of screens the current key can see.

### dataset_not_scopable

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: The FEIN DSL dataset does not support screen-level scoping.

**How to fix**: the dataset (for example `creative_venue_performance`) is
aggregated at venue granularity and cannot be restricted by screen. Either
remove screen-level scoping from the key or query a dataset with a
`screen_mongo_id` column.

### invalid_dataset

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The `dataset` body field is not one of the allowed FEIN DSL datasets.

**How to fix**: read `help.allowed` on the error payload for the list of
valid dataset names.

### invalid_dimensions

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: One or more requested dimensions are not defined on the target dataset.

**How to fix**: `help.allowed` lists the dimensions defined on the dataset;
use only those.

### invalid_measures

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: One or more requested measures are not defined on the target dataset.

**How to fix**: `help.allowed` lists the measures defined on the dataset;
use only those.

### invalid_order_by

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The `order_by` field is not in the selected dimensions/measures.

**How to fix**: every `order_by` entry must reference a field that is also
listed in `dimensions` or `measures`.

---

## SDK API

Errors specific to the `/v2/sdk/*` measurement surface (Phase 4 migration).

### client_ip_required

- **Type**: `invalid_request_error`
- **HTTP status**: 400
- **Summary**: The request did not carry a usable client IP.

**How to fix**: the SDK derives household identity and geolocation from the
client IP. Set `X-Forwarded-For` (via an upstream proxy) or send the request
from a direct connection so `getClientIP(req)` can resolve a valid value.

### api_key_owner_missing

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: The authenticated API key has no associated partner/owner.

**How to fix**: rotate the key in the portal. Missing owner IDs usually
indicate a test key that was created without a partner row and should be
replaced with a production key.

### sdk_enrich_rate_limit_exceeded

- **Type**: `rate_limit_error`
- **HTTP status**: 429
- **Summary**: `/v2/sdk/enrich` exceeded 300 requests per minute for this API key.

**How to fix**: batch enrichment client-side and back off for `Retry-After`
seconds. Cache the returned segments locally for the household lifetime of
the request IP (24h TTL server-side).

### sdk_qr_scan_rate_limit_exceeded

- **Type**: `rate_limit_error`
- **HTTP status**: 429
- **Summary**: `/v2/sdk/qr/scan` exceeded 100 requests per minute for this API key.

**How to fix**: a QR campaign should not produce more than ~100 scans per
minute per publisher — if you are seeing this frequently, investigate
whether the same QR is being mis-scanned by a crawler and coalesce client
side before posting.

### sdk_qr_beacon_rate_limit_exceeded

- **Type**: `rate_limit_error`
- **HTTP status**: 429
- **Summary**: `/v2/sdk/qr/beacon` exceeded 200 requests per minute for this API key.

**How to fix**: beacons should fire once per scan. Back off for `Retry-After`
seconds; if the limit is hit at steady state, request a quota lift via the
portal.

### sdk_impression_rate_limit_exceeded

- **Type**: `rate_limit_error`
- **HTTP status**: 429
- **Summary**: `/v2/sdk/impression` exceeded 1000 requests per minute for this API key.

**How to fix**: coalesce impressions client-side or split traffic across
multiple API keys with per-publisher scoping.

---

## Device API

Errors specific to the `/v2/device/*` managed-device control surface (Phase 4 migration).

### unknown_agent_type

- **Type**: `invalid_request_error`
- **HTTP status**: 404
- **Summary**: The requested device agent type has no OTA manifest entry.

**How to fix**: omit the `agent` query parameter to receive the full
manifest bundle, or supply one of the documented agent types
(`agent-core`, `agent-core-lite`, `tablet-agent`, `android-tv-agent`).

---

## Sensing API

Errors specific to the `/v2/sensing/*` paired-training surface (Phase 4 migration).

### paired_training_rate_limit_exceeded

- **Type**: `rate_limit_error`
- **HTTP status**: 429
- **Summary**: `/v2/sensing/paired-training-samples` exceeded 30 uploads per minute per device.

**How to fix**: the collector should batch ~500 samples per call and space
uploads across minutes. Back off for `Retry-After` seconds before the next
attempt.

### device_identity_missing

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: Device identity is missing after `requireDeviceRequestAuth` passed.

**How to fix**: ensure the device-token middleware is configured correctly.
If `deviceAuth.deviceId` is null, the resolved device has no canonical
identity and cannot be attributed — contact support with the `request_id`.

### paired_training_insert_failed

- **Type**: `api_error`
- **HTTP status**: 500
- **Summary**: Persisting the paired-training sample batch failed server-side.

**How to fix**: retry with backoff — the endpoint is idempotent on `sample_id`
so duplicate uploads from a previously partially-written batch are silently
deduped.

## OpenRTB / DSP

### openrtb_auth_failed

- **Type**: `authentication_error`
- **HTTP status**: 401
- **Summary**: The OpenRTB API key is missing or invalid.

**How to fix**: supply a valid API key via the `x-api-key` header or
`Authorization: Bearer <key>`. Keys are provisioned at DSP onboarding.

### openrtb_config_missing

- **Type**: `api_error`
- **HTTP status**: 500
- **Summary**: The server's OPENRTB_API_KEY environment variable is not configured.

**How to fix**: this is a server configuration issue. Contact support with the
`request_id` from the response.

### unsupported_media_type

- **Type**: `invalid_request_error`
- **HTTP status**: 415
- **Summary**: POST requests must set `Content-Type: application/json`.

**How to fix**: add the `Content-Type: application/json` header to your request.

### dsp_access_denied

- **Type**: `permission_error`
- **HTTP status**: 403
- **Summary**: The DSP account has been suspended or revoked.

**How to fix**: contact support@trillboards.com to resolve your account status.

### 204 No Content (no-fill)

The OpenRTB surface returns **HTTP 204 No Content** (empty body) when no ad
fill is available. This is canonical OpenRTB behavior and is NOT an error.
Callers must not treat 204 as a failure — it means no matching inventory was
available for the bid request parameters at the time of the request.

---

# Monetization requirements
# Source: https://api.trillboards.com/docs/monetization-requirements.md

# Partner Device Monetization Requirements

Every partner device registration and lookup response (`POST /v1/partner/device`,
`POST /v1/partner/devices/batch`, `GET /v1/partner/device/:id`,
`GET /v1/partner/devices`) carries a `monetization_status` and a structured
`requirements` object — modeled directly on Stripe's
`account.requirements.currently_due`. Instead of silently accepting a
registration that can never actually serve ads, the response tells you exactly
what's missing and how to fix it.

```json
{
  "monetization_status": "blocked",
  "requirements": {
    "currently_due": [
      {
        "code": "location_awaiting_device_gps",
        "field": "location",
        "reason": "awaiting_device_gps",
        "message": "This mobile screen has no location yet. Send a GPS fix in the heartbeat (location.lat/lng) and it resolves automatically.",
        "doc_url": "https://api.trillboards.com/docs/monetization-requirements#location_awaiting_device_gps"
      }
    ],
    "eventually_due": []
  }
}
```

**`monetization_status` values**

- **`ready`** — the screen has its own coordinates AND its venue is classified.
  Fully monetizable.
- **`limited`** — servable now, but not on every rail: the venue is not yet
  classified (missing venue taxonomy / floor-price refinement), or the screen
  has no position of its own yet and is listed in inventory feeds at your
  fleet's market location (see [Location capability](#location-capability)).
- **`blocked`** — no rail can serve it: no usable location for any rail, or
  venue classification permanently failed.

**`currently_due`** entries block (or limit) monetization right now.
**`eventually_due`** entries don't block serving — they improve creative
selection / targeting quality and are worth fixing, but there's no rush.

A device is never refused registration for missing location: it is created,
and the response says which rails can serve it until a position arrives.

## Location capability

Every response also carries `location_capability`: where the screen's location
comes from, and, per rail, whether that rail has the location it needs.

```json
{
  "location_capability": {
    "position": "fleet_market",
    "rails": {
      "inventory_feed": { "status": "ready", "location_source": "fleet_market", "reason": null },
      "geo_targeted_demand": { "status": "blocked", "location_source": null, "reason": "awaiting_device_gps" },
      "visit_attribution": { "status": "blocked", "location_source": null, "reason": "awaiting_device_gps" }
    }
  }
}
```

**`position`** — `precise` (the screen or its device has coordinates),
`fleet_market` (no coordinates of its own; your account's declared fleet market
location lists it), or `none`.

| Rail | What it reads | Ready from |
| --- | --- | --- |
| `inventory_feed` | The programmatic player feed, which accepts a fleet market location | The screen's or device's own coordinates (`screen`, `device`), or your fleet's declared market location (`fleet_market`) when it is complete and its state can be expressed as an ISO 3166-2 code |
| `geo_targeted_demand` | Geo-targeted programmatic demand, and the marketplace placement registries that publish a screen's own coordinate | The screen's or device's own coordinates (`screen`, `device`) |
| `visit_attribution` | Visit-attribution location data | The screen's own coordinates and a supported country (`screen`) |

`monetization_status` is computed over `inventory_feed` and
`geo_targeted_demand`; `visit_attribution` is a measurement capability and does
not change it.

A blocked rail's **`reason`**:

- `awaiting_device_gps` — a mobile screen with no fix yet. Send a GPS fix in the
  heartbeat (`location.lat` / `location.lng`); every rail that needs the
  screen's own position becomes ready.
- `no_location_provided`, `city_without_state`, `geocode_failed` — a static
  screen whose location could not be resolved (see
  [location_unresolvable](#location_unresolvable)).
- `screen_position_pending` — the device has reported a position and the
  screen's own coordinates have not been filled from it yet; the next GPS fix
  fills them.
- `country_unknown` — the rail needs the screen's country. Send
  `location.country` (ISO 3166-1 alpha-2).
- `country_not_supported` — visit-attribution data is not available in the
  screen's country.

---

### location_awaiting_device_gps

- **Field**: `location`
- **Blocks monetization**: yes (`blocked`), or `limited` when your account has
  declared its fleet market location, which lists the screen in inventory feeds
  until its own fix arrives
- **Summary**: This is a mobile or semi-mobile screen (`mobility_type`) with no
  usable coordinates yet, on either the screen record or the device record.

**How to fix**: this is self-healing — no separate API call needed. Include a
`location` object with a real GPS fix in the device's heartbeat body:

```json
{
  "location": {
    "lat": 45.5017,
    "lng": -73.5673,
    "accuracy_m": 12,
    "heading": 180,
    "speed_mps": 8.3,
    "source": "gps",
    "timestamp": 1784800000
  }
}
```

`lat`/`lng` (or `latitude`/`longitude`) are the only required fields; the rest
are optional. The very next heartbeat that includes a valid fix resolves this
requirement automatically. Note this is heartbeat-only — `location` is not
read from the device registration/PATCH body's `location.lat/lng` fields for
this particular gate on mobile screens, since a one-time registration-time
coordinate goes stale as a moving screen travels.

### location_unresolvable

- **Field**: `location`
- **Blocks monetization**: yes (`blocked`), or `limited` when your account has
  declared its fleet market location (see
  [Location capability](#location-capability))
- **Summary**: This is a static (non-mobile) screen with no usable
  coordinates, and what was provided couldn't be geocoded. The `reason`
  sub-field distinguishes three cases:
  - `no_location_provided` — no `location.lat/lng`, street address, or
    city+state was sent at all.
  - `city_without_state` — only a `city` was sent; a city alone cannot be
    geocoded.
  - `geocode_failed` — an address was sent but couldn't be resolved to
    coordinates.

**How to fix**: on `POST`/`PATCH /v1/partner/device`, send `location.lat` /
`location.lng` directly, or a full street address, or at minimum
`location.city` + `location.state`.

### enrichment_failed

- **Field**: `venue`
- **Blocks monetization**: yes (`blocked`)
- **Summary**: Automated venue classification permanently failed for this
  screen (`enrichment_status: "permanently_failed"`).

**How to fix**: verify the location and venue details are accurate and
re-save the device. If it fails again, contact support with the device's
`external_device_id` and `screen_id`.

### display_size_missing

- **Field**: `display`
- **Blocks monetization**: no (`eventually_due` — servable, just not ideal)
- **Summary**: `display.width` / `display.height` (pixels) were never sent, so
  creatives can't be sized precisely for this screen.

**How to fix**: send `display.width` and `display.height` in pixels on
`POST /v1/partner/device` (registration) or `PATCH /v1/partner/device/:id`
(update anytime after registration). This is not an automatic/heartbeat field
— the SDK must report it explicitly.

---

# Inventory security & venue verification
# Source: https://api.trillboards.com/docs/inventory-security.md

# Inventory Security & Venue Verification

How a screen becomes sellable inventory on Trillboards, what blocks it, and how a
demand partner can verify our delivery without trusting our reporting.

This page is the plain-language companion to three machine-readable references:
the [Partner API](https://api.trillboards.com/docs) (registration contract), the
[monetization requirements reference](https://api.trillboards.com/docs/monetization-requirements)
(the gate, code by code), and the
[proof-of-play specification](https://api.trillboards.com/docs/proof-of-play)
(independent verification).

---

## The short version

Our content-management app is free and open — anyone can install it on any
screen. **Installing the app does not create inventory.** A screen becomes
monetizable only after it clears an automated eligibility gate and a human
review, and it stays monetizable only while it keeps producing venue-shaped
telemetry.

If you are evaluating us for supply quality, the two things worth your time are
§3 (the monetization gate, which is machine-enforced and publicly documented)
and §6 (cryptographic proof of play, which lets you audit us without taking our
word for anything).

---

## 1. Two supply routes, two governance models

**Contracted networks.** Established operators integrate our ad-serving stack
into their own players under commercial agreement, with diligence performed at
the network level. For this inventory we declare the **partner's** original
bundle ID to demand — never ours — so the supply chain stays attributable
end-to-end. Every declared bundle appears in
[`trillboards.com/ads.txt`](https://trillboards.com/ads.txt) and
[`app-ads.txt`](https://trillboards.com/app-ads.txt), with ownership in
[`sellers.json`](https://trillboards.com/sellers.json).

**Self-registered venues.** Independent businesses — gyms, restaurants, bars,
laundromats, convenience stores — that sign up directly. This is the long tail,
and it is governed per-screen by the gates below before anything is sellable.

## 2. Registration binds a screen to a physical device

A screen cannot be registered in the abstract:

- Registration must bind to a **live device already displaying a pairing code**.
  A record with no real device behind it cannot be created.
- The database enforces **one device, one screen**. A second registration
  against the same device is rejected outright.

That second constraint is why an impression multiplier cannot be built on our
stack. On networks where several media players sit behind one physical display,
the same audience can be billed several times over and nothing downstream can
detect it. Here the binding is one-to-one at the data layer.

Registration also requires a structured record — location (`lat`/`lng`,
address, city, state, country, timezone), venue classification (category,
environment type, placement), display geometry, mobility type, and venue
photographs. The full contract is published as `POST /v1/partner/device` in the
[Partner API reference](https://api.trillboards.com/docs). Physical dimensions
are plausibility-checked at the API boundary.

## 3. The monetization gate is machine-enforced and publicly documented

Every device registration and lookup returns a `monetization_status` and a
structured `requirements` object, modeled on Stripe's
`account.requirements.currently_due`. Rather than silently accepting a
registration that can never serve, the response states exactly what is missing.

| Status | Meaning |
| --- | --- |
| `ready` | Coordinates present **and** venue classified. Monetizable. |
| `limited` | Not yet classified, or no coordinates of its own yet and listed in inventory feeds only at its operator's declared fleet market location. Servable, with reduced targeting. |
| `blocked` | Cannot serve. |

Blocking conditions include a screen whose submitted address **could not be
geocoded to real-world coordinates**, and a screen whose **automated venue
classification permanently failed**. A mobile screen that has never reported a
genuine GPS fix is also blocked, unless its operator has declared the fleet's
market location: inventory feeds then list it at that market (`limited`), and
geo-targeted demand waits for its own fix.

Each condition has a stable code, a documented cause and a documented
resolution path. The canonical, always-current list lives at
[api.trillboards.com/docs/monetization-requirements](https://api.trillboards.com/docs/monetization-requirements)
— a reviewer can read the blocking codes off a live API response rather than
taking a policy description on faith.

## 4. Human approval, default deny

The automated gate is necessary, not sufficient. Every self-registered screen
begins **outside** the sellable pool and is reviewed by our team before it
enters it.

An unapproved screen is not a screen that bids and loses. It is excluded from
every inventory feed, every DSP-facing endpoint and every SSP export we
publish — demand never sees it. Approval can be revoked, and a screen-level
kill switch removes inventory immediately.

## 5. Venue verification against submitted evidence

Venue claims are checked against evidence rather than accepted as declared:

- **Photographs are machine-graded** for whether they depict a real commercial
  display in a real venue. Submissions that do not are rejected.
- **Venue type is independently classified** from the submitted evidence, then
  mapped to the OpenOOH taxonomy — the same taxonomy Google and the IAB use to
  distinguish DOOH from CTV.
- **Location, venue type and device attestation travel in the bid request**,
  alongside IP, so a buyer can target and audit on the same fields we verified.

## 6. Proof of play you can verify yourself

Every proof-of-play record is signed **on the device** with an Ed25519 key held
in a hardware-backed keystore, and is verifiable by any third party against a
public key we publish openly.

| Resource | URL |
| --- | --- |
| Public verification key | [`/v1/advertiser/proof/.well-known/public-key`](https://api.trillboards.com/v1/advertiser/proof/.well-known/public-key) |
| Specification | [api.trillboards.com/docs/proof-of-play](https://api.trillboards.com/docs/proof-of-play) |

Fetch the key, rebuild the payload as
`version.timestamp.adId.impressionId.screenId.deviceId`, and verify the
signature. Any delivery record we hand you can be checked independently. If it
does not verify, we did not serve it.

## 7. Why a residential screen cannot quietly become inventory

The failure mode this page exists to address is a room full of devices
monetized as venues. Beyond the gates above, that pattern does not survive
contact with our measurement layer.

Our screens carry on-device AI that measures who is physically in front of the
display, and ads are served against measured presence. A living room does not
produce venue-shaped telemetry: no unique-visitor churn, no crowd, no dwell
distribution, no foot traffic pattern. Inventory that cannot produce that
signal is visible to us as an anomaly rather than invisible as a line in a
spreadsheet.

This is the structural difference between our supply and an inventory file of
declared venue types. On a static file, "is this screen really in a bar?" has
no answer after onboarding. Here it is answered continuously, on every
impression, in a record the buyer can verify.

---

## Snapshot

Figures below are a point-in-time snapshot, refreshed periodically. The
mechanisms above are the durable commitment; these numbers illustrate that the
gates carry real load.

*As of 5 August 2026:*

- **24,691** approved screens; **1,065** registered screens held unapproved and
  earning nothing; **92** deactivated after review
- **496 of 4,136** graded venue photographs rejected as not depicting a
  qualifying screen
- **11,859** screens venue-classified from submitted evidence rather than
  self-declaration
- Of screens transacting programmatically in the trailing 30 days, **99.2%**
  carried lat/long and **99.97%** a classified venue type in the bid request
- **4,240** sensing-equipped screens; **28.6M** measurement windows; **2.02
  billion** face observations recorded to date

---

## Contact

Quality, compliance or supply-path questions: **api@trillboards.com**.

We are able to provide demand partners with a dedicated seat drawn only from
the verified pool, so that inventory which has not cleared these controls
cannot appear in what you resell.

---

# Partner API Quickstart
# Source: https://api.trillboards.com/docs/guides/quickstart/partner.md

# Partner API Quickstart

The Partner API (`/v1/partner`) lets publishers manage screens and lets buyers optimize AI creatives against measured attention and dwell on paid plays. Use the same account for inventory, native creative review, serving, webhooks and reporting.

**Base URL:** `https://api.trillboards.com`

## 1. Get an API key

Register a new partner via `POST /v1/partner/register` (self-service, rate-limited to 5 req/hr per IP) or upgrade an existing earner account via `POST /v2/earner/upgrade-to-partner`. Save the token — the raw key is shown once.

For a new organization, replace the company name, unique lowercase slug and contact email:

```bash
curl -sS -X POST https://api.trillboards.com/v1/partner/register \
  -H 'Content-Type: application/json' \
  -d '{"name":"Your Company","slug":"your-company-unique-slug","contact_email":"developer@your-company.example"}'
```

Save `data.api_key` securely as `TRILLBOARDS_API_KEY` in your server environment. Existing organizations use the upgrade or key-management flow above. Portal access instructions are returned in `data.portal_access`.

**Newly minted partner keys always carry the `tb_prt_` prefix.** The older `trb_partner_` prefix is still *accepted* on existing keys but is no longer *issued*, so a key you mint today will never look like it. Do not hard-code, pattern-match, or validate against any prefix: prefixes are presentation metadata only, and authorization is decided exclusively by the scopes attached to the key (`services/platformApiAuthResolver.js`).

All authenticated endpoints expect:

```
Authorization: Bearer tb_prt_xxxxxxxxxxxx
```

## 2. Make your first call

Verify auth and pull partner info:

```bash
curl -s "https://api.trillboards.com/v1/partner/info" \
  -H "Authorization: Bearer tb_prt_xxxxxxxxxxxx"
```

Success response:

```json
{
  "success": true,
  "data": {
    "partner_id": "65f1c...",
    "name": "Acme Vending",
    "tier": "standard",
    "device_count": 42,
    "created_at": "2026-01-15T09:30:00Z"
  }
}
```

## 3. Handle errors

Every 4xx/5xx follows the canonical envelope and echoes a request ID you can share with support:

```json
{
  "error": {
    "type": "invalid_request_error",
    "code": "screen_not_found",
    "message": "Screen not found or access denied",
    "param": "screen_id",
    "request_id": "req_a1b2c3d4e5f6789012345678901234ab",
    "doc_url": "https://api.trillboards.com/docs/errors#screen_not_found",
    "help": {
      "summary": "Screen IDs are prefixed 'scr_'. List your screens at GET /v1/partner/devices.",
      "portal_url": "https://trillboards.com/earner/screens"
    }
  }
}
```

## 4. Common error codes

All codes below come from `utils/partnerApiErrors.ts` (see the error reference for the full catalog):

> `invalid_api_key_format` is defined in the error catalog but **no auth path ever emits it** — the
> server performs no prefix or format validation. A malformed or unknown token returns `invalid_api_key`.

| `error.code` | HTTP | When you see it |
|---|---|---|
| `authentication_required` | 401 | No `Authorization` header. Add `Bearer tb_prt_...`. |
| `invalid_api_key` | 401 | Token does not resolve to an active partner — rotate via `POST /v1/partner/api-key/rotate`. |
| `partner_inactive` | 403 | Account suspended. Contact support. |
| `screen_not_found` | 404 | `error.param` identifies the bad ID. Fetch the list from the portal or the devices endpoint. |
| `rate_limit_exceeded` | 429 | Honor the `Retry-After` header. The enforced authenticated cap is 1000 req/min per API key, flat across every data-access tier. |
| `tier_insufficient` | 403 | Endpoint requires a higher data-access tier; `error.help.current_tier` and `required_tier` tell you exactly what to upgrade to. |

## 5. Next common operations

- **List devices:** `GET /v1/partner/devices`
- **Register a device:** `POST /v1/partner/device` with `{ "name": "...", "venue_type": "..." }`
- **Record an impression batch:** `POST /v1/partner/impressions/batch` (for offline-sync SDKs)
- **Create a webhook:** `POST /v1/partner/webhooks` with `{ "url", "events" }` — payloads are HMAC-signed
- **Get screen earnings:** `GET /v1/partner/connect/earnings?range=7d`

## 6. Optimize AI creatives on real screens

Follow the [Creative AI Feedback Loop](https://api.trillboards.com/docs/guides/integrations/creative-feedback) to fund inventory, generate or import images, review and serve variants, and use measured attention and dwell to iterate your model through REST, MCP or the TypeScript SDK.

Install `@trillboards/api-client@3.2.1` for typed funding, native MCP buying, creative experiments, historical queries and the live audience tail. The walkthrough includes stable purchase keys, Stripe balance readback and correction-aware reward scans. Purchased HUD packages run locally without company credentials and then use this same account for paid live delivery.

## Next steps

- Full reference: [`/docs/partner`](https://api.trillboards.com/docs/partner)
- Error catalog: [`/docs/errors`](https://api.trillboards.com/docs/errors)
- Partner API client: `npm install @trillboards/api-client`
- Screen playback SDK: `npm install @trillboards/ads-sdk`

---

# CTV SDK Quickstart
# Source: https://api.trillboards.com/docs/guides/quickstart/sdk.md

# SDK Quickstart

The SDK API (`/v2/sdk`) powers CTV and DOOH measurement: census-based audience enrichment, QR scan attribution, and impression ingestion with GIVT dedup and frequency counting. Use it from a device SDK, a server-side measurement pipeline, or a pixel proxy.

**Base URL:** `https://api.trillboards.com`

## 1. Get an API key

SDK keys have the prefix `tb_dat_` (issued via the [portal](https://trillboards.com/developers)). They must carry SDK scopes such as `sdk:enrich`, `sdk:qr`, and `sdk:impression`. Pass the key in the `X-API-Key` header on every request.

## 2. Enrich an impression context

Census enrichment returns a stable household ID, IAB demographic segments, and connection-type hints for the caller's IP.

```bash
curl -s -X POST "https://api.trillboards.com/v2/sdk/enrich" \
  -H "X-API-Key: tb_dat_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Success response:

```json
{
  "geohash6": "dr5ruq",
  "iabIncomeSegmentId": "1003",
  "iabIncomeSegmentName": "$75,000-$99,999",
  "iabAgeSegmentId": "2004",
  "iabAgeSegmentName": "35-44",
  "educationTier": "bachelors_plus",
  "connectionType": "residential",
  "householdId": "a8c3f1d7b2e4...",
  "source": "maxmind"
}
```

`source` names the geolocation database behind the record: `maxmind` (MaxMind GeoLite2), `dbip` ([IP Geolocation by DB-IP](https://db-ip.com), CC BY 4.0), or `ipinfo` when neither is loaded.

Pass an optional `geohash6` (6-character geohash) in the body when the client knows its location more precisely than the caller IP suggests.

## 3. Handle errors

Authentication, validation, and rate-limit failures all return the canonical envelope:

```json
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after the specified time.",
    "request_id": "req_a1b2c3d4e5f6789012345678901234ab",
    "doc_url": "https://api.trillboards.com/docs/errors#rate_limit_exceeded"
  }
}
```

429 responses also include the standard `Retry-After` header. The enrich endpoint is capped at 300 req/min per key; QR beacon at 200 req/min; impression at 1000 req/min. Back off on the client side — don't stack retries.

## 4. Ingest impressions

Once enriched, post impressions to `/v2/sdk/impression` with a client-generated `impressionId` (UUID) so GIVT dedup can latch across retries. Required fields include `adId`, `placementId`, and `channel` (`ctv`, `dooh`, or `web`). See `validation/sdkSchemas.js` or the generated OpenAPI for the full body shape.

## Next steps

- Reference: [`/docs/sdk`](https://api.trillboards.com/docs/sdk)
- QR attribution flow: `POST /v2/sdk/qr/scan` then `POST /v2/sdk/qr/beacon`
- Error catalog: [`/docs/errors`](https://api.trillboards.com/docs/errors)

---

# OpenRTB / DSP Quickstart
# Source: https://api.trillboards.com/docs/guides/quickstart/openrtb.md

# OpenRTB / DSP Quickstart

The `/openrtb/v2` surface is the authenticated buyer/control plane: discover inventory, forecast, manage deals and creatives, report, and submit OpenRTB 2.6 bid responses. It uses the same centralized platform API key as MCP and reporting.

**Base URL:** `https://api.trillboards.com/openrtb/v2`

## 1. Mint and link one API key

Existing partner owners/admins self-mint at <https://trillboards.com/earner/settings?tab=api> under Partner API. Headless agents can use the existing autonomous registration route instead:

```bash
curl -sS -X POST 'https://api.trillboards.com/v1/partner/agent/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "agent_type": "dsp_agent",
    "name": "Example Buyer Agent",
    "email": "programmatic@example.com",
    "company": "Example Buyer"
  }'
```

The `201` response returns `api_key` once and the exact MCP endpoint
`https://api.trillboards.com/mcp`. Registration is limited to five attempts per
IP per hour. Store the key in a secrets manager and use the canonical header
everywhere:

```http
Authorization: Bearer <platform_api_key>
```

Link that same key to one DSP seat; this grants the DSP capabilities without minting a second credential:

```bash
curl -sS -X POST 'https://api.trillboards.com/openrtb/v2/onboard' \
  -H 'Authorization: Bearer <platform_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "company_name": "Example Buyer",
    "seat_id": "example_buyer",
    "contact_email": "programmatic@example.com"
  }'
```

The response includes `api_key.reused_platform_key: true` and does not echo the secret. Anonymous onboarding still mints a `tb_dsp_*` key only for backwards compatibility. Existing `x-api-key`, `tb_dsp_*`, `tb_prt_*`, and migrated `trb_partner_*` clients continue to work; capabilities, not prefixes, decide access.

## 2. Discover inventory

```bash
curl -sS 'https://api.trillboards.com/openrtb/v2/adslots?format=openrtb&country=US&limit=20' \
  -H 'Authorization: Bearer <platform_api_key>'
```

`format=openrtb` returns ready-to-use `bid_requests` with request and impression IDs. Omit it for the planning-oriented screen summary. Use `/forecast`, `/discover`, `/screens/availability`, and `/deals` with the same header for planning.

## 3. Submit a bid response

`POST /openrtb/v2/bid` accepts an OpenRTB **bid response**, not a supply-side bid request. Match `id` and `impid` to inventory/request IDs received from the buyer flow.

```bash
curl -sS -X POST 'https://api.trillboards.com/openrtb/v2/bid' \
  -H 'Authorization: Bearer <platform_api_key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "request_from_adslots",
    "seatbid": [{
      "seat": "example_buyer",
      "bid": [{
        "id": "bid_001",
        "impid": "imp_65a1b2c3d4e5f6a7b8c9d0e1",
        "price": 4.00,
        "adm": "<VAST version=\"3.0\">...</VAST>",
        "crid": "creative_001",
        "adomain": ["example.com"]
      }]
    }]
  }'
```

New seats start in sandbox. Sandbox status prevents auction injection, but it does not bypass scopes.

| HTTP | Meaning |
|---|---|
| `200` | One or more bids passed validation and were accepted. |
| `204` | No accepted bids; treat as a normal no-bid outcome. |
| `400` | Malformed bid response or missing required field. |
| `401` | Missing, invalid, revoked, or unlinked platform key. |
| `403` | The key lacks the route capability. |
| `415` | `Content-Type` is not `application/json`. |

## Raw exchange bidstream is different

A bilateral supply connection sends OpenRTB bid requests to its configured endpoint:

```text
POST https://api.trillboards.com/openrtb/bidder/<connection_alias>/bid
```

That high-QPS raw bidstream does **not** send the platform API key on every request. Trust comes from the provisioned exchange connection and alias, optional IP allowlist/mTLS/signature, QPS limits, and callback telemetry. Win, impression, and loss use the connection-specific callback URLs returned in each bid.

## Common errors

| `error.code` | HTTP | How to fix |
|---|---:|---|
| `authentication_required` | 401 | Add `Authorization: Bearer <platform_api_key>`. |
| `invalid_api_key` | 401 | Re-check or rotate the self-minted key in the portal. |
| `missing_scope` | 403 | Complete DSP onboarding for that same key or request the missing entitlement. |
| `invalid_json` | 400 | Send valid JSON with `Content-Type: application/json`. |
| `rate_limit_exceeded` | 429 | Honor `Retry-After`; do not retry 204 no-bids. |

## Next steps

- Full DSP reference: <https://api.trillboards.com/docs/dsp>
- Machine-readable OpenAPI: <https://api.trillboards.com/openrtb/v2/openapi.json>
- MCP endpoint: <https://api.trillboards.com/mcp>
- AI-readable contract: <https://api.trillboards.com/llms.txt>
- Error catalog: <https://api.trillboards.com/docs/errors>

---

# Data API Quickstart
# Source: https://api.trillboards.com/docs/guides/quickstart/data-api.md

# Data API Quickstart

The Data API gives agencies, DSPs, and data partners read access to Trillboards audience intelligence: live audience snapshots, historical aggregations, semantic search over scene embeddings, and lookalike screen discovery. Use it for planning, attribution, and measurement workflows that do not need ad-serving control.

**Base URL:** `https://api.trillboards.com`

## 1. Get an API key

Data API keys have the prefix `tb_dat_` and are issued from the [portal](https://trillboards.com/developers). Keys are scoped; common scopes are `read:live`, `read:historical`, `read:semantic`, and `stream:live`. Each request must include the key in the `X-API-Key` header.

## 2. Make your first call

List the screens your key is authorized to see:

```bash
curl -s "https://api.trillboards.com/v1/data/screens?limit=5" \
  -H "X-API-Key: tb_dat_xxxxxxxxxxxx"
```

Success response:

```json
{
  "screens": [
    { "screen_id": "...", "mongo_screen_id": "...", "name": "Lobby #3",
      "venue_type": "fitness", "city": "Brooklyn", "country": "US", "status": "active" }
  ],
  "count": 1, "offset": 0, "limit": 5
}
```

If the `X-API-Key` header is missing or invalid, you get the canonical error envelope:

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid or inactive API key provided.",
    "request_id": "req_a1b2c3d4e5f6789012345678901234ab",
    "doc_url": "https://api.trillboards.com/docs/errors#invalid_api_key"
  }
}
```

Every 4xx/5xx response echoes `error.request_id` matching the `X-Request-Id` response header. Paste it into a support ticket and we can trace the request end-to-end.

## 3. Common errors

| `error.code` | HTTP | How to fix |
|---|---|---|
| `authentication_required` | 401 | Add the `X-API-Key` header. |
| `invalid_api_key` | 401 | Check the key you copied from the portal. Rotate if compromised. |
| `insufficient_permissions` | 403 | Your key is missing a required scope (for example, `read:historical`). Request an upgrade from your account manager. |
| `rate_limit_exceeded` | 429 | Back off using the `Retry-After` header; default limit is 60 req/min per key. |

## Next steps

- Full reference: [`/docs/data`](https://api.trillboards.com/docs/data)
- Error catalog: [`/docs/errors`](https://api.trillboards.com/docs/errors)
- FEIN query DSL: `POST /v1/data/query` for composable dimensions + measures
- Streaming: `GET /v1/data/stream` (Server-Sent Events, scope `stream:live`)

---

# RL Environment Trials
# Source: https://api.trillboards.com/docs/guides/integrations/rl-environments.md

# Try Trillboards RL environments

Download a free scored trial and test your agent against the same grading core used in its full package. Each trial includes two tuning tasks, the evidence needed to attempt them, a reference workflow and a local grader.

Choose the decision you want your model to improve:

| Trial | What your agent does | Full package |
|---|---|---|
| Inventory Planning | Forecast inventory and build an allocation schedule. | https://datavendor.ai/listings/75707605-cbea-43ca-ba7f-4c2299cb3fbe |
| Creative Attention | Allocate creatives and forecast measured attention. | https://datavendor.ai/listings/e6d9f988-4224-403f-a786-3652123b1367 |
| Ad Serving Debugging | Diagnose serving failures from native evidence. | https://datavendor.ai/listings/ada56f81-08f5-4754-9584-50bdb5423b10 |
| Scene Search | Retrieve scenes and check caption or provenance evidence. | https://datavendor.ai/listings/225f6b8f-7543-4152-8a58-dd6ec46447d9 |
| Creative Policy Fit | Route creatives and explain owner-policy compatibility. | https://datavendor.ai/listings/e4950087-ad62-473f-9f76-fbc2aa25714f |
| Campaign Operator | Activate and pause a campaign through native services. | https://datavendor.ai/listings/702c01df-7005-428f-a160-ea129efc6dd8 |
| Creative Response | Forecast measured response by context and reconcile native play evidence. | https://datavendor.ai/listings/c1917228-bd5a-44c6-a09d-acf7eefe8a05 |
| Fleet Diagnosis | Diagnose incidents and find supporting heartbeat evidence. | https://datavendor.ai/listings/d1cb1a18-4305-431f-8fe1-9db48eac39f0 |
| Finance Operations | Audit invoice basis, current allocation admission and historical allocations. | https://datavendor.ai/listings/1915d698-4235-4b63-82e1-55e458c98942 |
| Auction Calibration | Attribute settled plays and forecast measured settled CPM. | https://datavendor.ai/listings/87b4a3d4-96c5-4592-aca1-7beacb1276b0 |
| Camera Alert Operations | Replay native routing state and reconcile notification receipts. | https://datavendor.ai/listings/60ffc1df-8354-4e82-adff-11847a73000e |

The machine-readable catalog supplies each product's download URL, ZIP byte count and SHA-256, task IDs, and embedded manifest SHA-256:

https://api.trillboards.com/docs/integrations/rl-environments.json

## Download and run a recorded trial

Use Python 3.11 or 3.12. Copy the download URL and SHA-256 from your chosen catalog entry, then extract into a new directory. Reference runs use the included evidence and require no Trillboards account or model-provider key.

~~~sh
DOWNLOAD_URL='COPY_DOWNLOAD_URL_FROM_CATALOG'
SHA256='COPY_SHA256_FROM_THE_SAME_ENTRY'

curl --fail --location "$DOWNLOAD_URL" --output trial.zip
python3 - "$SHA256" <<'PY'
import hashlib, sys
with open("trial.zip", "rb") as archive:
    actual = hashlib.file_digest(archive, "sha256").hexdigest()
if actual != sys.argv[1]:
    raise SystemExit("ZIP SHA-256 mismatch")
PY
mkdir trial
unzip -q trial.zip -d trial
cd trial

python3 -S -B run.py --verify
python3 -S -B run.py --list
python3 -S -B run.py --receipt ../reference.json
~~~

The receipt contains each task's answer and numeric score. A reference is a reproducible comparison point; scores can be below 1. The recorded trials use recorded evidence, with zero production actions and zero model calls in the reference run.

To score your own answer, select a task returned by the list command. Read its public case and place your answer JSON outside the extracted package:

~~~sh
TASK_ID='COPY_A_TASK_ID_FROM_THE_LIST'
python3 -S -B actor/evidence.py case "$TASK_ID"
python3 -S -B run.py --task "$TASK_ID" \
  --answer ../answer.json --receipt ../answer-score.json
~~~

For an agent evaluation, give the agent the included actor package and public task. Keep the grader and reference answers on your grading host. The trial README describes its evidence and media profile; the full package's listing describes the purchased archive.

## Optional HUD model evaluation

The recorded trials also include a HUD runner with actor and verifier isolation. Install its pinned requirements into a separate environment:

~~~sh
python3 -m venv ../hud-venv
. ../hud-venv/bin/activate
export PYTHONDONTWRITEBYTECODE=1
python -m pip install --no-compile -r requirements.lock

python hud-run.py --check
python hud-run.py --receipt ../hud-reference.json
~~~

With no model option, the runner uses the included reference agent and makes no inference calls. To evaluate a model, configure your own provider key outside the trial and select a supported provider and model:

~~~sh
python hud-run.py --provider openai --model YOUR_MODEL_ID \
  --receipt ../model-score.json
~~~

Your model provider bills inference. Use the package's included guide for its optional Prime adapter.

## Run the Campaign Operator trial

Campaign Operator uses Linux x86-64, Docker Engine and its CLI, at least 8 GiB available RAM and 10 GB free disk. The initial build downloads public dependencies and service images. Its two reference tasks require no Trillboards account, model key or Stripe key.

Start from a fresh extraction of the Campaign Operator ZIP and verify it using the catalog's ZIP SHA-256 as above:

~~~sh
python3 -S -B run.py --verify
python3 -S -B run.py --manifest
python3 -S -B run.py --build
python3 -S -B run.py --baseline --task operator-activate-01 \
  --receipt ../activation.json
python3 -S -B run.py --baseline --task operator-pause-01 \
  --receipt ../pause.json
~~~

Each episode creates isolated PostgreSQL, Redis and ClickHouse services, then grades the resulting native campaign, billing, moderation and serving state. The reference workflow cleans up its owned services. These trial actions run inside that environment; they do not book production media or charge a card.

To connect your own agent, follow the included SDK/MCP, HUD or Prime instructions. The agent receives the filtered native campaign tools and public task. The independent verifier reads the final state to assign its score.

## Move from the trial to the full package

Open the matching full-package link above for its complete task set, held-out evaluations, evidence, provenance and benchmark reports. DataVendor requires buyer-account approval before checkout; the free trials above run without that approval. Preserve the archive and manifest checks in your evaluation pipeline. The workflow bundle contains four existing products; its member tasks overlap those individual packages.

## Connect to live Trillboards inventory

Use the existing API client:

~~~sh
npm install @trillboards/api-client@3.2.1
~~~

Create your account and API access, discover inventory, submit reviewed creatives and follow the live workflow in the partner quickstart:

https://api.trillboards.com/docs/guides/quickstart/partner

For the creative feedback loop, live signals and integration contract:

https://api.trillboards.com/docs/guides/integrations/creative-feedback

Production serving follows native availability, CPM, screen-owner preferences, moderation and funding checks. Funded media spend and API/data usage are separate charges. The downloadable environment purchase does not fund production media.

Machine-readable API discovery:

https://api.trillboards.com/llms.txt

https://api.trillboards.com/api/discover

---

# Creative AI Feedback Loop
# Source: https://api.trillboards.com/docs/guides/integrations/creative-feedback.md

# Creative AI Feedback Loop

Connect your creative model to real advertising screens. Generate or import images, choose what runs, and feed measured attention and dwell into the next decision. This guide covers the live creative optimization workflow through REST, MCP and the TypeScript SDK.

**Base URL:** `https://api.trillboards.com`

## Get your buying key

Use the existing [Partner API onboarding](https://api.trillboards.com/docs/guides/quickstart/partner) to create your account and key. Your key identifies the same buying account throughout inventory discovery, funding, creative review, serving and reward reads.

## Live workflow

### Fund a media buy

Discover products with `get_products` and inventory with `discover_inventory` on the [MCP endpoint](https://api.trillboards.com/mcp). Complete the existing `create_media_buy` flow and retain its `media_buy_id` and selected `package_id`. The experiment binds to that package's actual funded advertisement and placements. Use a production buying account to serve; a sandbox buy exercises validation without creating live placements.

Media and API usage have separate payment decisions. The media buy uses its accepted inventory, CPM and contracted quote; activation requires the native funding receipt. Generation, image import and each reward page use the existing `data_api/api_calls` tariff, free quota and API allowance. Media credit alone does not authorize an unfunded API read. Check current rates at [pricing](https://api.trillboards.com/v1/partner/pricing); metered responses include `usage_receipt` with exact units and charges. Stripe-backed account funding follows the existing verified payment flow; posting a creative does not fund a placement.

API holds use your current graduated tariff. A lone request that crosses the free allowance reserves only its paid suffix. Concurrent admitted work can rebalance active holds; commitment, cancellation and expiry return excess reserves. Your final `usage_receipt` reports the exact actual charge. Repeating an operation key retains its original identity and tariff.


Use a partner buying key with `campaigns:write`, `bid:write` or `partner:write` for writes, and `reports:read`, `stats:read` or `partner:read` for reads. MCP additionally requires `mcp:tools`.

### Fund and book with the SDK

Install `@trillboards/api-client@3.2.1`. The SDK uses the native MCP protocol for media buying and REST for account funding and creative experiments.

```typescript
import { TrillboardsClient } from '@trillboards/api-client';

const client = new TrillboardsClient({ apiKey: process.env.TRILLBOARDS_API_KEY! });

// Persist purchaseKey before calling; reuse it only for this exact purchase.
async function openCreditCheckout(purchaseKey: string) {
  const checkout = await client.billing.createCreditCheckout(
    { tier: 'tier_500' }, { idempotencyKey: purchaseKey },
  );
  return checkout.checkout_url;
}

async function readFunding() {
  const usage = await client.billing.getUsageSummary();
  return {
    balanceCents: usage.credit_balance_cents,
    reservedCents: usage.credit_reserved_cents,
  };
}

async function bookInventory(input: {
  productId: string; budgetUsd: number; brandDomain: string;
  startTime: string; endTime: string; operationKey: string;
}) {
  try {
    const accounts = await client.mediaBuys.listAccounts();
    const account = accounts.accounts.find(value => value.status === 'active');
    if (!account) throw new Error('Use an active production buying account.');
    const catalog = await client.mediaBuys.getProducts({
      pagination: { max_results: 100 },
    });
    const product = catalog.products.find(value => value.product_id === input.productId);
    const fixed = product?.pricing_options.find(value => value.fixed_price !== undefined);
    if (!product || !fixed) throw new Error('Select a current product and fixed CPM option from the catalog.');
    const buy = await client.mediaBuys.create({
      idempotency_key: input.operationKey,
      account: { account_id: account.account_id },
      brand: { domain: input.brandDomain },
      start_time: input.startTime, end_time: input.endTime,
      packages: [{ product_id: product.product_id,
        pricing_option_id: fixed.pricing_option_id, budget: input.budgetUsd }],
    });
    if (!buy.media_buy_id || !buy.packages?.length) throw new Error('Buy did not return its native identifiers.');
    return buy;
  } finally {
    await client.mediaBuys.close();
  }
}
```

Open the returned Checkout URL and complete payment. Read `credit_balance_cents` and `credit_reserved_cents` after the verified Stripe webhook commits the credit; a browser redirect or Checkout-session creation alone does not fund the account. These values and usage amounts are exact decimal strings in cents. `billing.setup({payment_method_id})` saves a payment method; `billing.purchaseCredits({tier}, {idempotencyKey})` uses an already configured payment method. Both credit-purchase paths require a stable `Idempotency-Key`. Direct purchases return `status`, `requires_action` and, when Stripe needs confirmation, `client_secret`; complete that Stripe action before treating credits as settled.

Call `mediaBuys.getProducts` to choose the product and pricing-option identifiers, following `pagination.cursor` when `pagination.has_more` is true. Supply your budget, brand domain and future ISO8601 flight bounds to `bookInventory`. Retain `media_buy_id`, `packages[].package_id` and the returned funding state. The native buy quote, funding receipt, creative eligibility and screen-owner preferences determine serving readiness. `status` at the MCP task layer describes task execution. Once the package is funded, use those exact identifiers in the experiment below; creative review and registration complete its native serving workflow.

### Create, review and register an action

Create the experiment after funding. Policy versions are exact decimal strings. Reuse the enrollment key only for the same creation request.

```bash
curl -sS -X POST https://api.trillboards.com/v1/partner/creative-experiments \
  -H "Authorization: Bearer $TRILLBOARDS_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Creative attention loop","media_buy_id":"YOUR_MEDIA_BUY_ID","package_id":"YOUR_PACKAGE_ID","objective":"gaze_share","idempotency_key":"enroll-attention-v1","expected_policy_version":"0"}'
```

Keep the response's `data.id` and `data.policy_version`. Configure `/brand` using your `brand_name`, complete `brand_rules`, optional `brand_assets` and `stance`. The brand-rules object contains `brand_name`, `palette` (`primary`, `secondary`, `accents`), `typography` (`headline`, `body`), `voice_tone`, `mandatory_elements`, `prohibited_elements`, `products`, `taglines` and `stance_preferences`; see the [Partner reference](https://api.trillboards.com/docs/partner) for the full schema.

A complete brand body for `/brand`:

```json
{
  "brand_name": "Acme",
  "brand_rules": {
    "brand_name": "Acme",
    "palette": {"primary": "#111111", "secondary": "#FFFFFF", "accents": []},
    "typography": {"headline": "Bold sans serif", "body": "Sans serif"},
    "voice_tone": ["clear"],
    "mandatory_elements": ["Brand name", "Clear call to action"],
    "prohibited_elements": [],
    "products": [],
    "taglines": [],
    "stance_preferences": ["intent_capture"]
  },
  "brand_assets": [],
  "stance": "intent_capture"
}
```

Then choose an image source:

- Call `/creatives/generate` with `stance`, `aspectRatio`, `brief` and a fresh `idempotency_key` to use native generation.
- Call `/creatives/import` with a fresh key and exactly one of `asset_url`, `source_creative_id` or `image_base64`. Inline bytes also require `content_type`. PNG, JPEG and WebP are validated from their actual bytes; an existing source creative must belong to this partner.

Both paths return a staged `creativeId` and `cdnUrl`. If a response is lost, reuse its operation key: the committed 409 response retains the original receipt. Get the existing experiment to recover your native `creatives` library, which returns the latest 500 candidates and marks `creatives_truncated` when more exist. Each row retains its original `advertisement_mongo_id` and reports `linked_to_experiment_ad` for this experiment's current ad; the committed receipt also retains its server-derived `creativeId` and `renderKey`. This recovery does not repeat paid generation/import. `moderation_status` and `content_sha256` stay NULL until the review matches that exact asset URL. Preview the image and call `/creatives/review` with `{"creative_id":"YOUR_CREATIVE_ID","decision":"approve"}` or `"reject"`. Brand approval and AI moderation are separate steps. Registration succeeds once the creative is approved, linked to this advertisement and eligible; `CREATIVE_NOT_READY` means it has not reached that state.

Register the approved action with the latest version:

```json
{
  "expected_version": "1",
  "variants": [
    {"variant_id": "headline-a", "creative_id": "YOUR_CREATIVE_ID", "model_version": "your-model-v3"}
  ]
}
```

Post that body to `/v1/partner/creative-experiments/YOUR_EXPERIMENT_ID/variants`, using the actual current version from the experiment response. Registration returns a new `policy_version`; retain it. Variant, model and byte identity stay fixed after registration. A new model/image gets a new variant identity.

### Start serving and iterate

Put a weight generation to `/v1/partner/creative-experiments/YOUR_EXPERIMENT_ID/policy`:

```json
{
  "expected_version": "2",
  "weights": [{"creative_id": "YOUR_CREATIVE_ID", "weight": 1}]
}
```

Use the registration response's version. Weights must be between zero and one, with at least one positive entry; zero removes that creative from selection. Every update returns the next version. On `CREATIVE_POLICY_CONFLICT`, get the experiment and reconcile the current version before writing again.

The next signed paid play uses the current eligible policy. Screen preferences and current approval are checked at selection. Each resulting reward retains the issued variant, model version, policy version, byte hash, render specification and selection probability. You can update the next play's policy as soon as your model makes a decision. Measured rewards follow the existing five-minute refresh and daily 48-hour correction sweep.

### Read rewards and keep corrections

```bash
curl -sS -G "https://api.trillboards.com/v1/partner/creative-experiments/$EXPERIMENT_ID/rewards" \
  -H "Authorization: Bearer $TRILLBOARDS_API_KEY" \
  --data-urlencode "from=$FROM_DATE" --data-urlencode "to=$TO_DATE" \
  --data-urlencode 'limit=500' --data-urlencode "idempotency_key=$READ_OPERATION_KEY"
```

Dates are inclusive UTC calendar dates, up to 31 days per scope; pages contain at most 5,000 rows. Use a fresh operation key for each page and each new poll. A repeated pending or committed key returns HTTP 409 (`OPERATION_IN_PROGRESS` or `OPERATION_ALREADY_COMMITTED`); a committed response includes the original receipt at `error.help.usage_receipt`.

Follow `next_cursor` with the same dates. When `scan_complete` is true, the next poll starts with no cursor. This reads latest measured states and recovers late writes on the next complete rescan. Store rows by `canonical_key` and deduplicate by `reward_revision_id`: an `upsert` replaces that play's contribution; a `retract` removes it. Keep the revision so a repeated tombstone has no second effect. `build_stamp` and `builder_version` record provenance; a rebuild can retain the same logical revision.

`gaze_share` uses `gaze_pct_on_screen` on a 0–1 scale; `gaze_overlap_ms` uses milliseconds; `dwell_ms` uses `dwell_capped_ms_mean`. NULL means unmeasured. Parse `creative_feedback` for the immutable issued action and model metadata. Train/evaluate against actual served observations; an unserved candidate has no measured reward.

Subscribe to `creative.rewards_ready` through existing partner webhooks or SSE. Hints are free and carry an experiment, date range, build provenance and reward-reader URL. Fetching each reward page uses the API tariff. On reconnect, recover with a full bounded rescan and logical deduplication. The hint is a wake-up signal; your stored canonical keys and revisions own recovery.

### Complete operation map

All paths below use `/v1/partner/creative-experiments`; `{id}` is the returned experiment ID. REST responses use `{success:true,data:...}`. MCP tools use the same schemas and native account.

| REST | MCP tool | Result / usage |
|---|---|---|
| POST base | `create_creative_experiment` | Funded enrollment; free |
| GET `/{id}` | `get_creative_experiment` | Current experiment/version; free |
| POST `/{id}/brand` | `configure_feedback_brand` | Native brand/reactive configuration; free |
| POST `/{id}/creatives/generate` | `generate_brand_creative` | Staged generated image; metered |
| POST `/{id}/creatives/import` | `import_feedback_creative` | Staged imported image; metered |
| POST `/{id}/creatives/review` | `review_feedback_creative` | Brand approve/reject; free |
| POST `/{id}/variants` | `register_creative_variants` | Approved immutable actions; free |
| PUT `/{id}/policy` | `update_creative_policy` | Versioned weights/start; free |
| GET `/{id}/rewards` | `get_creative_rewards` | Latest-state reward page/receipt; metered |
| POST `/{id}/stop` | `stop_creative_experiment` | Stop using `expected_version`; free |

Use the REST examples above or these MCP tools to start optimizing creatives. Both transports accept the same request bodies and return the same typed results.

Historical HUD tasksets use the existing verified product export, immutable vintage, manifest and dictionary. Their actor sees earlier measured observations; their verifier grades against later actual plays. The live HUD adapter calls these same MCP operations. See the repository's `integrations/hud/creative-feedback/README.md` for packaging and runtime commands.


## TypeScript SDK

Install the published client:

```bash
npm install @trillboards/api-client@3.2.1
```

The same operations are available on `client.creativeExperiments`. These functions use your funded media-buy identifiers, actual brand configuration and model-generated assets. Persist the experiment ID and each returned policy version. Call `approveAndServe` after inspecting the returned `cdnUrl` and completing AI moderation; `CREATIVE_NOT_READY` means that candidate is not eligible yet.

```typescript
import { TrillboardsClient } from '@trillboards/api-client';
import { randomUUID } from 'node:crypto';

const apiKey = process.env.TRILLBOARDS_API_KEY;
if (!apiKey) throw new Error('Set TRILLBOARDS_API_KEY to your partner buying key.');
const client = new TrillboardsClient({ apiKey });

type BrandConfiguration =
  Parameters<typeof client.creativeExperiments.configureBrand>[1];

async function createLoop(
  mediaBuyId: string, packageId: string, brand: BrandConfiguration,
  operationKey: string,
) {
  const experiment = await client.creativeExperiments.create({
    name: 'Creative attention loop',
    media_buy_id: mediaBuyId,
    package_id: packageId,
    objective: 'gaze_share',
    idempotency_key: operationKey,
    expected_policy_version: '0',
  });
  const id = experiment.data.id;
  await client.creativeExperiments.configureBrand(id, brand);
  return id;
}

async function stageAction(
  id: string, brief: string, operationKey: string, assetUrl?: string,
) {
  const creative = assetUrl
    ? await client.creativeExperiments.importCreative(id, {
        asset_url: assetUrl, idempotency_key: operationKey,
      })
    : await client.creativeExperiments.generate(id, {
        brief, stance: 'intent_capture', aspectRatio: '16:9',
        idempotency_key: operationKey,
      });
  return creative.data; // creativeId, cdnUrl and the usage_receipt
}

async function approveAndServe(
  id: string, creativeId: string, variantId: string, modelVersion: string,
) {
  await client.creativeExperiments.review(id, {
    creative_id: creativeId, decision: 'approve',
  });
  const current = await client.creativeExperiments.get(id);
  const registered = await client.creativeExperiments.registerVariants(id, {
    expected_version: current.data.policy_version,
    variants: [{
      variant_id: variantId, creative_id: creativeId, model_version: modelVersion,
    }],
  });
  return client.creativeExperiments.updatePolicy(id, {
    expected_version: registered.data.policy_version,
    weights: [{ creative_id: creativeId, weight: 1 }],
  });
}

async function* readRewardPages(
  id: string, from: string, to: string,
) {
  const scanId = randomUUID();
  let cursor: string | undefined;
  let page = 0;
  do {
    const result = await client.creativeExperiments.getRewards(id, {
      from, to, limit: 500, idempotency_key: `${scanId}:page:${page}`,
      ...(cursor ? { cursor } : {}),
    });
    yield result.data;
    if (result.data.scan_complete) return;
    cursor = result.data.next_cursor ?? undefined;
    page += 1;
    if (!cursor) throw new Error('Incomplete reward scan returned no next cursor.');
  } while (cursor);
}

async function stopLoop(id: string) {
  const current = await client.creativeExperiments.get(id);
  return client.creativeExperiments.stop(id, {
    expected_version: current.data.policy_version,
  });
}
```

Generate and persist a unique operation key (for example, `crypto.randomUUID()`) before each new creation, generation or import. Pass the same key only for the same operation and inputs. `readRewardPages` creates a fresh `scanId` for every invocation; its pages derive distinct billing keys.

Create the loop once, then stage and review each new model candidate against that experiment. A full reward-page scan feeds your next decision; apply each row's upsert or retraction using the keys above. Start the next poll with no cursor so corrections remain visible. For generation/import, keep the original operation key after a lost response: retrying it recovers the committed receipt and creative identity without repeating generation/import. For reward reads, the committed receipt contains no reward rows or cursor. Abandon an interrupted scan and invoke `readRewardPages` again from the beginning; it creates fresh page keys. Each recovery page follows the normal API tariff. Apply its latest states using the same canonical-key and revision deduplication.

## Inventory planning and ad-serving debugging environments

The Inventory Planning package combines measured screen-hour history with a dated native catalog and availability snapshot. Its HUD tasks forecast gaze share, dwell milliseconds and face density, then grade budget-constrained plans against that frozen snapshot and separate recorded reference windows. The downloadable package contains the source Parquets, dictionary, exact units, task splits, baseline scores and separate numerical verifier.

The Ad-serving Debugging package follows actual issued request and impression identifiers through request, auction, render and completion evidence. Tasks diagnose the observed stage or evidence gap and reconcile canonical billable plays and recorded USD amounts. Native billing-key and eligibility projections retain the existing billing policy.

Both version-3 downloads include a portable Python project and HUD0.6.20. From the extracted directory:

```bash
python3.12 -m venv ../trillboards-venv
. ../trillboards-venv/bin/activate
python -m pip install -r requirements.lock
export PYTHONDONTWRITEBYTECODE=1
python -m trillboards_hud.product_package verify .
python -m trillboards_hud.product_runner . --split evaluation --receipt ../evaluation.json
```

The baseline needs no account or model key. Add `--provider openai --model YOUR_MODEL` with your provider credential to evaluate a model through the same tools and verifier. Put execution receipts beside the immutable download. Live inventory discovery and delivery use `client.mediaBuys`; creative outcomes use `client.creativeExperiments.getRewards`. General screen history and the separate live audience tail are exposed through `client.data`, with their endpoint scopes `read:historical`, `read:live` and `stream:live`. The audience stream is a live tail; use bounded history reads after reconnect. Creative reward recovery uses the canonical-key/revision protocol above.

## References

- [Complete Partner API reference](https://api.trillboards.com/docs/partner)
- [Current API pricing](https://api.trillboards.com/v1/partner/pricing)
- [Error reference](https://api.trillboards.com/docs/errors)

---

# Webhook signature verification
# Source: https://api.trillboards.com/docs/guides/integrations/webhook-signature-verification.md

# Webhook signature verification

Canonical contract for verifying Trillboards-emitted webhook deliveries.
Single source of truth — partner-api.yaml, dsp-api.yaml, the
`@trillboards/api-client` SDK, and the `/api/discover.globals.webhook_contract`
runtime manifest all derive from this document.

## TL;DR

Every outbound webhook from `api.trillboards.com` carries:

```
X-Trillboards-Event:        <event_name>             # e.g. "impression.recorded"
X-Trillboards-Timestamp:    <unix_seconds>           # mirrored from `t=` for redundancy
X-Trillboards-Signature:    t=<unix_seconds>,v0=<hex>,v1=<hex>
X-Trillboards-Webhook-Id:   <subscription_id>        # Partner surface only
X-Trillboards-Delivery-Id:  del_<uuid>               # DSP surface (Partner adds in PR-D-ish)
User-Agent:                 Trillboards-Webhook/1.0  # Partner
                            Trillboards-DSP-API/1.0  # DSP
```

Where:

- `v1 = HMAC-SHA256(secret, "${timestamp}.${payload}")` — **canonical**, replay-protected
- `v0 = HMAC-SHA256(secret, payload)` — legacy body-only digest emitted during the
  migration window for partners on pre-`@trillboards/api-client@0.3.0` verifiers
  or who built their own body-only verifier from earlier dsp-api.yaml examples

A verifier MUST:

1. Parse the compound `X-Trillboards-Signature` header.
2. Extract `t=<ts>`; reject if `|now - ts| > tolerance` (default 300 seconds, Stripe-aligned).
3. Compute `expected_v1 = HMAC-SHA256(secret, "${t}.${payload}")` and compare
   against `v1=` from the header using a constant-time string comparison.
4. If `v1=` is absent (server in pre-migration state), fall back to verifying
   `v0=` against `HMAC-SHA256(secret, payload)`.
5. If the header is the legacy `sha256=<hex>` form, try both `v1` and `v0`
   candidate inputs.
6. Reject with HTTP 401 on any mismatch.

## Recommended: `@trillboards/api-client@>=0.3.0`

```ts
import { Webhooks } from '@trillboards/api-client';

app.post('/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = Webhooks.constructEvent(
      req.body,                                  // raw Buffer or string
      req.headers,                               // IncomingHttpHeaders
      process.env.WEBHOOK_SECRET!,
    );
    console.log('Received', event.event);
    res.sendStatus(200);
  } catch (err) {
    // TrillboardsError { code: 'webhook_signature_invalid', statusCode: 401 }
    res.sendStatus(401);
  }
});
```

Override the replay window (default 300s):

```ts
Webhooks.constructEvent(req.body, req.headers, secret, { tolerance: 600 });
```

## Manual verification (no SDK)

```js
const crypto = require('crypto');

function verifyTrillboardsWebhook(rawBody, headers, secret, toleranceSec = 300) {
  const sigHeader = headers['x-trillboards-signature'];
  if (!sigHeader) throw new Error('missing signature header');

  // Parse `t=<ts>,v0=<hex>,v1=<hex>`
  const parts = Object.fromEntries(
    sigHeader.split(',').map((p) => {
      const i = p.indexOf('=');
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    })
  );
  const ts = Number(parts.t);
  if (!Number.isFinite(ts)) throw new Error('missing t=<unix_seconds>');

  // Replay protection
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - ts) > toleranceSec) throw new Error('timestamp outside tolerance');

  // Prefer v1; fall back to v0
  if (parts.v1) {
    const expected = crypto.createHmac('sha256', secret)
      .update(`${ts}.${rawBody}`)
      .digest('hex');
    if (parts.v1.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))) {
      return JSON.parse(rawBody);
    }
  }
  if (parts.v0) {
    const expected = crypto.createHmac('sha256', secret)
      .update(rawBody)
      .digest('hex');
    if (parts.v0.length === expected.length &&
        crypto.timingSafeEqual(Buffer.from(parts.v0), Buffer.from(expected))) {
      return JSON.parse(rawBody);
    }
  }
  throw new Error('signature mismatch');
}
```

## Replay window

Default tolerance: **300 seconds** (Stripe-aligned). Configurable per partner
via `network_config.webhook_replay_tolerance_seconds` on the partner record.
Outside-window deliveries are rejected with HTTP 401 + a structured error
envelope (`code: webhook_signature_invalid`).

## Migration timeline

| Phase | Status | Server emits | SDK reads |
|---|---|---|---|
| Pre-0.3.0 (broken) | done | `sha256=<v1_hex>` + separate `X-Trillboards-Timestamp` | only `payload` — FAILS verification |
| 0.3.0 dual-emit (NOW) | active | `t=<ts>,v0=<hex>,v1=<hex>` | parses compound + replay window |
| Post-T+180d | future | `t=<ts>,v1=<hex>` only (drop v0=) | unchanged |

The `v0=` value is emitted **only during the migration window** so partners
who built their own body-only verifier (matching the original dsp-api.yaml
example) pass verification for the first time. After T+180 days, once
`@trillboards/api-client@0.3.0` adoption is confirmed via npm download
stats, `v0=` is dropped in a separate PR. Nothing schedules that drop: the
npm download share is the trigger and a human has to read it, so this
paragraph is the only thing that remembers. The drop itself is one place —
`services/webhooks/canonicalSigner.js`, which builds the `t=,v0=,v1=` header
for every outbound surface listed below.

## Industry alignment

The compound header shape is byte-for-byte compatible with Stripe's
`Stripe-Signature` parser. A partner who already integrated Stripe webhooks
can copy their parsing helper unchanged; only the secret and signed input
change.

## Outbound surfaces using this contract

- **Partner API webhooks** (`services/partner/webhookQueue.js`) — emitted on
  events declared in partner-api.yaml (`device.online`, `device.offline`,
  `impression.recorded`, `campaign.allocated`, `payout.processed`,
  `programmatic.*`).
- **DSP API webhooks** (`services/programmatic/dspWebhookDispatcher.js`) —
  emitted to seats subscribed via `POST /openrtb/v2/webhooks`. Currently
  delivers `impression.delivered`; events declared in dsp-api.yaml.

Both call `services/webhooks/canonicalSigner.js#buildSignatureHeader` so
the format cannot drift between them.

## NOT covered by this document (different verifier per sender)

- `routes/webhooks/github.js` — GitHub inbound, `X-Hub-Signature-256`
- `middleware/vapiAuth.js` — Vapi inbound, `vapi-signature`
- `services/partner/impressionSecurity.js` — Trillboards impression-pixel
  inbound verifier, custom `timestamp.adid.impid.did.sid.aid` format
- `modules/mdm/services/alertService.js` — internal MDM dashboard, `X-MDM-Signature`
- `controller/openrtb/feinWebhookController.js` — FEIN signal partners,
  `X-FEIN-Signature: sha256=<hex>` (body-only)

These are scoped to their respective senders/consumers and are not part of
the Trillboards public-partner webhook contract.

## Test plan

A cross-package golden-vector test at
`trillboards-api-client/tests/interop.test.ts` imports
`services/webhooks/canonicalSigner.js#buildSignatureHeader` directly and
asserts that:

1. The compound header parses + verifies through `Webhooks.constructEvent`.
2. Modified payloads are rejected.
3. Expired timestamps are rejected (replay protection).
4. v0-only headers verify when v1 is absent (back-compat path).
5. The header shape is byte-stable across regenerations (locked vector).

If `buildSignatureHeader`'s output changes without a coordinated SDK update,
this test fails loudly in CI before any partner is affected.

---

# Native IMA SDK (Android)
# Source: https://api.trillboards.com/docs/guides/integrations/partner-native-ima-sdk.md

# Trillboards Partner Integration Guide — Native IMA SDK (Android)

**Status:** Production-verified. First successful integration: Take 10 Media, April 2026.
**Fill rate achieved:** 61% (Adipolo). Completion rate: 79% of fills. Effective: 48% of all ad requests.

This guide documents the exact integration that works for native Android IMA SDK on Rockchip-class devices. Follow it literally — every point here was discovered the hard way through a week of debugging.

---

## 0. Integration requirements — read this before you write any code

Every line below is a hard requirement, not a suggestion. Each one exists because a partner shipped without it and lost revenue or went black on-screen. If you only read one section of this guide, read this one.

**R1 — The waterfall is a LOOP, not a single tag.** `/ads` returns `header_bidding_settings.vast_waterfall.sources[]` — an **array**. You must iterate **every** source, in `priority` **ascending** order, and skip any source with `enabled: false`. Reading `sources[0].vast_url` and stopping is the single most common integration bug we see. Response shape: [§4](#4-the-ad-request--get-v1partnerdevicedeviceidads). Loop contract + pseudocode: [§4.1](#41-the-waterfall-loop-contract).

**R2 — Advance on EVERY failure, not just "no ad".** Move to the next source on no-fill, empty/zero-`<Ad>` VAST, HTTP error, per-source timeout, IMA **load** error, *and* IMA **playback** error. Named VAST codes you must treat as "try the next source", never as "stop": **303** (no ads VAST response after wrapper), **300** (wrapper URI unparseable/timeout), **301** (wrapper timeout / unresolvable), **1009** (empty VAST response). See [§4.1](#41-the-waterfall-loop-contract).

**R3 — Budget both clocks.** Each source has its own `timeout_ms` — apply it per source. The whole loop is capped by `vast_waterfall.total_timeout_ms` — when that budget is spent, stop trying sources and return to content. Never let one slow source eat the whole break.

**R4 — ALWAYS handle player error. Never leave the surface black.** Register `Player.Listener.onPlayerError` (Media3) or `AdErrorEvent.AdErrorListener` + your own content-playback error path (raw IMA). On any error you must fall back to your own content or a house creative. A black screen is worse than no ad — the venue sees it, and so does the earner. The exact ExoPlayer footgun that produced a fleet of black screens is worked through in [§6.1](#61-pitfall-the-uriempty-content-resume-black-screen-media3--ima).

**R5 — Fire the `<Error>` beacon.** Every VAST we serve — the programmatic wrap path *and* the first-party `trillboards_direct` rail — carries an `<Error>` element with the `[ERRORCODE]` macro. On any ad failure, substitute the numeric IMA/VAST error code for `[ERRORCODE]` and fire that URL. On the first-party rail this beacon is the **only** ad-failure signal that exists: we ship no agent to your player, so if you do not fire it we are structurally blind to your failures and cannot tell "nothing broke" from "everything broke". See [§7.1](#71-the-error-beacon--mandatory).

**R6 — Report `programmatic-event`.** `ad_started` / `ad_ended` / `no_fill` / `error`, each with `request_id` + `variant_name` from the source you actually used. See [§7](#7-reporting-events-back--post-v1partnerdevicedeviceidprogrammatic-event).

### Reference implementation and self-verification

- **Reference implementation:** [`trillboard-screen/public/partner-sdk/trillboards-lite.src.js`](https://github.com/trillboards/packages/blob/production/trillboard-screen/public/partner-sdk/trillboards-lite.src.js) — the Trillboards Lite SDK. Its `onAdError` handler is the canonical shape of R2 + R5: it classifies 303/1009 as no-fill, fires the `<Error>` pixel with `[ERRORCODE]` substituted, records the VAST request outcome, reports the `programmatic-event`, and **only** resolves the caller once the pending waterfall sources are exhausted. When in doubt about ordering or classification, copy what it does.
- **Self-verification:** append **`?test=1`** to your `/ads` call. That forces a guaranteed-fill test source (public alias `src_test`, a direct MP4 with no wrapper chain) into that one response — no allowlist enrollment, no revenue impact, real devices polling without the flag are unaffected. If `src_test` plays end-to-end but real sources don't, your VAST handling is fine and the problem is in the partner-response path. If `src_test` *doesn't* play, the bug is in your player.

---

## 1. What this guide is for

You are integrating the Trillboards `/ads` endpoint into a native Android player that uses Google IMA SDK (not WebView). Your devices are digital signage — kiosks, TVs, menu boards, ATM toppers — running a custom Android app with Media3 + ImaAdsLoader or raw IMA SDK.

This path is the highest-performing integration for partner devices. It gives you server-side wrapper chain resolution, device-specific demand targeting, and full impression attribution.

---

## 2. Required endpoints (five of them)

All base URLs: `https://api.trillboards.com`. Partner API key auth on registration only.

| # | Method | Path | Purpose |
|---|---|---|---|
| 1 | POST | `/v1/partner/device/{deviceId}/heartbeat` | Every 60s. Reports device identity. |
| 2 | GET | `/v1/partner/device/{deviceId}/ads` | Request waterfall of VAST sources. |
| 3 | GET | `/openrtb/v1/vast-wrap/{provider}/{screenId}?url=...&req=...&var=...&pt=partner_api` | Fetch resolved VAST XML for a waterfall source. |
| 4 | POST | `/v1/partner/device/{deviceId}/programmatic-event` | Report ad_started / ad_ended / no_fill / error. |
| 5 | (automatic) | Tracking pixels embedded in the VAST | IMA SDK fires these when the ad plays. |

---

## 3. The heartbeat — player identity

**Endpoint:** `POST /v1/partner/device/{deviceId}/heartbeat` (every 60 seconds)

For a user-agent update, the supported body is `{"device":{"ua":"<actual WebView user agent>"}}`. The empty body remains a liveness heartbeat but provides no player UA. The following example includes optional hardware facts:
```json
{
  "device": {
    "make": "Rockchip",
    "model": "rk3568_r",
    "os": "Android",
    "osv": "11",
    "android_api_level": 30,
    "ua": "Mozilla/5.0 (Linux; Android 11; rk3568_r Build/RD2A.211001.002; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/105.0.5195.136 Safari/537.36"
  },
  "application": {
    "agentVersion": "2.0.18"
  }
}
```

### Field-by-field rules

**`device.make`** — The actual manufacturer reported by the device; use a known hardware value, not a guessed vendor.

**`device.model`** — The actual hardware model. Keep internal serial numbers and asset IDs in their identifier fields.

**`device.os`** — `Android`; report the release version separately in `device.osv`.

**`device.osv`** — The Android release version, for example `"11"` or `"13"`, from [`Build.VERSION.RELEASE`](https://developer.android.com/reference/android/os/Build.VERSION#RELEASE). Send `Build.VERSION.SDK_INT` separately as the integer `device.android_api_level`, for example `30` or `33`. This matches [OpenRTB's OS-version field](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3218---object-device).

**`device.ua`** — **The single most important field.** Read it directly from the device at app startup:
```kotlin
val webView = WebView(context)
val realUA = webView.settings.userAgentString
webView.destroy()
```
Or if WebView can't be instantiated (non-certified devices may restrict it):
```kotlin
val realUA = WebSettings.getDefaultUserAgent(context)
```

Send the exact UA returned by the installed WebView. Do not append serial numbers or manufacture unique strings, Build fingerprints, or `wv` tokens. Devices with the same software and hardware can legitimately share a UA. [`WebSettings.getDefaultUserAgent`](https://developer.android.com/reference/android/webkit/WebSettings#getDefaultUserAgent(android.content.Context)) returns the platform default.

**`application.agentVersion`** — Your SDK/app version. Helps us correlate issues to specific rollouts.

### Hardware model and asset identifiers

Keep serial numbers and asset-tracking IDs in the partner device identifier. If a device's model property has been repurposed as a serial number, use a verified hardware model or omit the optional model field. Preserve the UA returned by WebView.

---

## 4. The ad request — GET /v1/partner/device/{deviceId}/ads

**Endpoint:** `GET /v1/partner/device/{deviceId}/ads`

**Optional query params** (player truth — send whatever you know):
- `slot_w`, `slot_h` — Actual video container dimensions in pixels
- `orientation` — `portrait` or `landscape`
- `muted` — `1` or `0`
- `autoplay` — `1` or `0`
- `ua` — The real WebView UA (same as heartbeat), URL-encoded once by your URL builder
- `lang` — `en-US` etc.
- `screen_w`, `screen_h` — Physical screen dimensions in pixels
- `sdk_type` — `google-ima`
- `sdk_version` — IMA SDK version you're linking against
- Hardware and dimension fields are optional. Send actual pixel dimensions; omit unknown values. Start the UA update on a few identified devices and verify their outgoing requests before a fleet rollout.
- `ipd` — Inventory Partner Domain root domain, for example `trillboards.com`. Only send this when Trillboards tells you to; it must match an `inventorypartnerdomain=<domain>` declaration in the relevant ads.txt/app-ads.txt inventory-sharing setup, and it must not include a scheme, path, query, or port.

**Response shape:**
```json
{
  "success": true,
  "data": {
    "header_bidding_settings": {
      "enabled": true,
      "vast_waterfall": {
        "enabled": true,
        "total_timeout_ms": 15000,
        "sources": [
          {
            "name": "adipolo",
            "vast_url": "https://api.trillboards.com/openrtb/v1/vast-wrap/adipolo/{screenId}?url=...&req=req_...&var=adipolo&pt=partner_api",
            "timeout_ms": 10000,
            "priority": 1,
            "enabled": true,
            "cpm": 5.0,
            "degraded": false,
            "request_id": "req_1775716769503_eb810d042466"
          },
          {
            "name": "vidverto",
            "vast_url": "https://api.trillboards.com/openrtb/v1/vast-wrap/vidverto/{screenId}?url=...&req=req_...&var=vidverto&pt=partner_api",
            "timeout_ms": 10000,
            "priority": 2,
            "enabled": true,
            "cpm": 0.8,
            "degraded": false,
            "request_id": "req_1775716769503_8a85f754fd8a"
          },
          {
            "name": "trillboards_direct",
            "vast_url": "https://api.trillboards.com/openrtb/v1/vast?screenId=...&adId=...",
            "timeout_ms": 8000,
            "priority": 5,
            "enabled": true,
            "duration_seconds": 15,
            "request_id": "req_1775716769503_c31f0a9be7d2"
          }
        ]
      }
    },
    "screen_id": "69cce...",
    "dooh_signals": { ... }
  }
}
```

The `vast_url` values already point to our vast-wrap endpoint with `pt=partner_api`. **Do not rewrite them.** Use them exactly as given.

Each source carries its own `request_id` and `name` — save these. You'll need them for the `programmatic-event` report later (`variant_name` on the event is the source's `name`).

#### `duration_seconds` — for continuous loop playback

The first-party `trillboards_direct` source carries **`duration_seconds`**: the whole-second length of the creative that source will serve. It is there so you can schedule a continuous loop **without** fetching the VAST and probing the MP4 first.

- It is the **same number** as the `<Duration>` in the VAST that `vast_url` returns — the two are computed by one function server-side and cannot disagree. Use whichever is convenient.
- It is **scheduling metadata, not a playback control.** IMA takes its real timing from the media itself, so keep honouring the actual quartile and `complete` events rather than assuming the ad ended after `duration_seconds` elapsed. If the two ever disagree on your device, the *events* are right and that is a bug worth telling us about.
- Programmatic sources do **not** carry it — a DSP's creative length is unknown until its own VAST is fetched. Read it only off `trillboards_direct`, and treat it as absent everywhere else.
- A creative longer than your ad slot will still be cut off by the next `/ads` poll. We warn the advertiser at upload time when their creative exceeds the slot, so this should be rare — but do not assume `duration_seconds` fits your slot without checking.

Programmatic `/ads` responses are intentionally not HTTP-cacheable. Treat each call as a fresh ad opportunity because the VAST URLs include per-request IDs, correlators, and yield-routing metadata. Static direct-ad responses may still use short private ETag caching.

### 4.1 The waterfall loop contract

**`sources` is an ordered array and you must walk all of it.** This is not optional and it is not an optimization — it is how a Trillboards ad request is defined.

We return the array already in the order we want it tried, and `priority` ascends with array position. Sort by `priority` ascending anyway: it costs you three lines and it makes your player correct if the transport, a cache, or a JSON library ever reorders the array.

**Treat `priority` as an opaque ascending sort key — not an index.** Do not assume it starts at 1, and do not assume the values are contiguous:

- **`priority: 0` is real and valid.** A source we want to win outright is stamped `priority: 0` — that includes the `?test=1` source, an injected first-party bid, and an auction winner. A player that treats `0` as "unset" and skips it, or that starts its loop at 1, will drop exactly the source we most wanted served.
- **Gaps are normal.** Some paths renumber the surviving sources `1..N`; others leave the original catalog values, so `11` and `13` with nothing in between is a perfectly ordinary response.

Only the relative order carries meaning. `sortBy(priority)` handles all of this; arithmetic on the values does not.

```
sources ← response.data.header_bidding_settings.vast_waterfall.sources
sources ← sources.filter(s -> s.enabled != false).sortBy(s -> s.priority)   // ascending
deadline ← now() + vast_waterfall.total_timeout_ms

for (source in sources):
    if now() >= deadline: break                       // R3 — whole-loop budget spent
    vast ← GET source.vast_url  with timeout = source.timeout_ms
    if (transport failed) or (timed out) or (vast is empty) or (vast has zero <Ad>):
        lastTried ← source; continue                   // R2 — advance
    outcome ← handToIma(vast)
    if outcome is AD_LOAD_ERROR or AD_PLAY_ERROR:
        fire <Error> beacon with [ERRORCODE]           // R5 — always
        lastTried ← source; continue                   // R2 — advance
    report ad_started / ad_ended for this source       // §7
    return PLAYED                                      // stop at the FIRST source that plays

// every source exhausted, or budget spent
report no_fill for lastTried                           // §7
resumeOwnContent()                                     // R4 — never leave the surface black
```

**Rules the pseudocode encodes:**

- **Iterate all sources by `priority` ascending.** Stop only on the first source that *actually plays*.
- **Skip `enabled: false`.** A source can be present-but-disabled in the array; treat it as if it weren't there.
- **Advance on every failure class**, not just "no ad": no-fill, empty VAST, zero-`<Ad>` VAST, HTTP/transport error, per-source timeout, IMA **load** error, and IMA **playback** error. A creative that loads and then fails mid-roll still means "this source did not deliver" — go to the next one.
- **VAST error codes that mean "advance", never "stop":**

  | Code | Meaning | What you do |
  |---|---|---|
  | **303** | No ads VAST response after one or more wrappers | Next source |
  | **300** | Wrapper URI unparseable, unsupported, or wouldn't load | Next source |
  | **301** | Timeout / unresolvable URI in the wrapper chain | Next source |
  | **1009** | Empty VAST response | Next source |

- **Two clocks.** `source.timeout_ms` bounds one source's fetch+load. `vast_waterfall.total_timeout_ms` bounds the whole loop. Honour both; when the total budget is gone, stop and return to content.
- **`degraded: true`** means we've measured a high recent error rate for that source. We already push degraded sources to the tail of the array for you — you don't need to act on the flag, and you must **not** skip a source just because it's degraded.
- **Report against the source you actually used.** `request_id` and `variant_name` come from *that* source's entry, not from `sources[0]`. The `<Error>` beacon (R5) fires per failed source, always. The `programmatic-event` minimum is unchanged — the source that played, plus one `no_fill` for the last source tried if none did ([§7](#7-reporting-events-back--post-v1partnerdevicedeviceidprogrammatic-event)) — but a per-source `error` report is accepted and makes your waterfall legible to us end to end.

> **This is the exact bug that cost a partner a full production forensics session.** Their player read `sources[0].vast_url` only. Indexes 0–3 were programmatic DSPs that returned no-fill for their geo; the `trillboards_direct` house creative sat at index 4. Their player got VAST **303** on source 0 and stopped — one index before the ad it was looking for. Every request looked like "Trillboards has no demand". The demand was there the whole time, one loop iteration away.

---

## 5. Fetching VAST — the critical part

For **each** source in the waterfall — all of them, in `priority` ascending order, per the loop contract in [§4.1](#41-the-waterfall-loop-contract):

```
GET {source.vast_url}        # with a per-request timeout of source.timeout_ms
```

**Response:** Full VAST XML (Content-Type: application/xml), 15-25 KB, containing wrapper chains resolved server-side. Our server:
1. Fetches the upstream partner VAST (Adipolo, VidVerto, etc.) using your device's IP via `X-Forwarded-For` for geo-targeting
2. Follows `<VASTAdTagURI>` wrapper chains up to 5 hops to resolve to inline creative
3. Injects Trillboards tracking pixels at the wrapper/inline level
4. Returns the final VAST XML ready for IMA SDK to play

**Do NOT:**
- Parse the XML and extract only `<MediaFile>`
- Strip `<Wrapper>` elements
- Check for VPAID and skip (let IMA SDK handle it)
- Modify the XML in any way before passing to IMA

**Why:** Our tracking pixels (`<Impression>` and `<TrackingEvents>`) are embedded at the wrapper level. If you strip them, IMA SDK never fires them, and we have no record of the impression → no revenue attribution → no earnings.

---

## 5b. If you're NOT using Google IMA SDK (raw VAST player)

IMA SDK automatically fires every embedded `<Impression>` and `<TrackingEvents event="...">` URL as the ad plays. Custom VAST players do **not**. If you are rolling your own — raw HTML5 `<video>` wrappers, `svp`, `video.js` without the VAST plugin, Shaka without the ads plugin, or any other non-IMA stack — you are responsible for firing those pixels yourself.

**If you skip this, our server has no record of the impression. Zero revenue attribution. Zero earnings.**

Extract tracking URLs directly from the VAST XML with browser-native `DOMParser` — no dependencies:

```js
function parseVastTrackingUrls(vastXml) {
  const doc = new DOMParser().parseFromString(vastXml, 'application/xml');
  const getUrls = (selector) => Array.from(doc.querySelectorAll(selector))
    .map((n) => (n.textContent || '').trim())
    .filter(Boolean);
  return {
    impression:    getUrls('Impression'),
    error:         getUrls('Error'),   // fire on failure with [ERRORCODE] substituted — see §7.1
    start:         getUrls('Tracking[event="start"]'),
    firstQuartile: getUrls('Tracking[event="firstQuartile"]'),
    midpoint:      getUrls('Tracking[event="midpoint"]'),
    thirdQuartile: getUrls('Tracking[event="thirdQuartile"]'),
    complete:      getUrls('Tracking[event="complete"]'),
  };
}

function firePixels(urls) {
  urls.forEach((u) => { const img = new Image(1, 1); img.src = u; });
}
```

**Fire order:**
1. `Impression` URLs on the first video frame render.
2. `start` URLs immediately after the impression fire.
3. Quartile URLs (`firstQuartile`, `midpoint`, `thirdQuartile`, `complete`) from the corresponding player lifecycle callbacks (`timeupdate` / `ended` in HTML5, equivalent events in other stacks).
4. `error` URLs on any load or playback failure, with `[ERRORCODE]` replaced by the numeric VAST/player error code — see [§7.1](#71-the-error-beacon--mandatory).

**Rules:**
- Fire each URL exactly once per ad playback. Double-fire inflates our reconciliation counts and gets your supply flagged.
- Parse the VAST as XML, not regex. Tracking URLs live inside both `<InLine>` and `<Wrapper>` blocks — follow the chain like IMA does, or let our server resolve wrappers for you (we already do — see §5).
- The page hosting the player must allow our tracking host in its Content Security Policy: `img-src https://api.trillboards.com` (or wider). If CSP blocks the pixel request, the impression is lost silently.
- Use the `Image()` pattern (GET with no response handling) — not `fetch()` — so you don't inherit CORS constraints. Pixel endpoints are intentionally unauthenticated and idempotent.

---

## 6. Handing VAST XML to IMA SDK

### Raw IMA SDK (google-ima3)

```java
AdsRequest request = sdkFactory.createAdsRequest();
request.setAdsResponse(vastXmlString);  // the full XML, untouched
request.setContentProgressProvider(contentProgressProvider);
adsLoader.requestAds(request);
```

### Media3 + ImaAdsLoader (recommended for Android)

Media3 doesn't expose `setAdsResponse` directly — it uses a `data:` URI scheme that internally converts to `setAdsResponse`:

```kotlin
// 1. Get resolved VAST XML from vast-wrap
val vastXml = fetchVastWrap(source.vastUrl)

// 2. Build data: URI — Media3 internally calls setAdsResponse() for data: scheme
val adsUri = Util.getDataUriForString("text/xml", vastXml)

// 3. Pass to Media3 AdsConfiguration
val mediaItem = MediaItem.Builder()
    .setUri(contentUri)
    .setAdsConfiguration(
        MediaItem.AdsConfiguration.Builder(adsUri)
            .setAdsId(source.requestId)  // use source.request_id for tracking
            .build()
    )
    .build()

player.setMediaItem(mediaItem)
player.prepare()
```

### Critical: do NOT set MIME type filter

```kotlin
// WRONG — this blocks VPAID and non-mp4 creatives from VidVerto, AdX, etc.
ImaAdsLoader.Builder(context)
    .setAdMediaMimeTypes(listOf("video/mp4"))  // ← REMOVE THIS
    .build()

// RIGHT — let IMA SDK negotiate supported types per creative
ImaAdsLoader.Builder(context)
    .build()
```

The mp4 MIME filter was the single biggest completion-rate killer in Take 10's integration. Leaving it set cost 100% of VidVerto fills and some percentage of Adipolo fills. Remove it unconditionally.

### 6.1 Pitfall: the `Uri.EMPTY` content-resume black screen (Media3 + IMA)

This one is not partner-specific — it is a general IMA + ExoPlayer footgun, and it produced a fleet of black screens that took a full production forensics session to diagnose. Read it even if your integration "already works", because it only bites *after* an ad plays successfully.

**The setup.** Digital signage often has no "content" — the screen shows your own app UI or playlist, and you want the player to do nothing but play ads. So the natural thing to write is:

```kotlin
// WRONG — this is a black screen waiting to happen
val mediaItem = MediaItem.Builder()
    .setUri(Uri.EMPTY)                                // or "" , or omitted entirely
    .setAdsConfiguration(
        MediaItem.AdsConfiguration.Builder(adsUri).build()
    )
    .build()
```

**What actually happens.** The ad plays fine. Then IMA fires `CONTENT_RESUME_REQUESTED` at ad end — it always does, because IMA's model is *ad interrupts content, ad finishes, content resumes*. ExoPlayer dutifully opens the content URI. Now the failure chain runs:

1. The content URI is empty, so it has **no scheme**.
2. In media3, `Util.isLocalFileUri()` returns **true** for any scheme-less URI — an empty URI looks exactly like a relative local path.
3. So the load is routed to `FileDataSource`, which does `new RandomAccessFile("", "r")`.
4. That throws → `PlaybackException` with `ERROR_CODE_IO_FILE_NOT_FOUND`.
5. With no `onPlayerError` handler registered, nothing catches it. The player stops, the surface is never repainted, and the screen stays **black** until someone power-cycles it.

Note the shape of this bug: **there is no error on the ad path at all.** Fills are fine, completions are fine, your `programmatic-event` reports are fine. The failure is entirely in content-resume, which is why it survives every ad-side check you might run.

**The fix — two halves, and you need both.**

*(a) Give the player something real to resume into.* Point content at your own loop/filler asset, or a 1-frame looping local file, so `CONTENT_RESUME_REQUESTED` has a valid destination:

```kotlin
// RIGHT — content resume has a real, playable destination
val contentUri = Uri.parse("asset:///filler_loop.mp4")   // any real, local, scheme-ful URI
val mediaItem = MediaItem.Builder()
    .setUri(contentUri)
    .setAdsConfiguration(
        MediaItem.AdsConfiguration.Builder(adsUri)
            .setAdsId(source.requestId)
            .build()
    )
    .build()
```

If you genuinely have no content, use `ImaAdsLoader`'s ad-only path (`setPlayer` + a content source you control) rather than an empty URI. The invariant is simply: **never hand ExoPlayer a scheme-less or empty content URI.**

*(b) Always register an error handler (R4).* This is the part that turns any future variant of this bug into a recoverable blip instead of a black screen:

```kotlin
player.addListener(object : Player.Listener {
    override fun onPlayerError(error: PlaybackException) {
        Log.e("TrillboardsAds", "player error ${error.errorCodeName}", error)
        // Do not stop here. Recover the SURFACE:
        showOwnContent()     // your playlist / house creative / static frame
        // and tell us, so the failure is visible on our side too:
        reportProgrammaticEvent(
            event = "error",
            requestId = currentSource.requestId,
            variantName = currentSource.name,
            errorCode = error.errorCodeName,
            errorMessage = error.message ?: "player error",
        )
        fireVastErrorBeacon(currentVastErrorUrl, error.errorCodeName)   // §7.1
    }
})
```

`onPlayerError` is **not** the same listener as IMA's `AdErrorEvent.AdErrorListener`. `AdErrorListener` covers ad load/play failures; `onPlayerError` covers everything ExoPlayer itself fails at, including content resume. Register **both**. The Lite SDK reference implementation does exactly this — ad errors go through `onAdError`, and the host gets a callback so it can repaint its own surface.

---

## 7. Reporting events back — POST /v1/partner/device/{deviceId}/programmatic-event

Fire these from your player lifecycle callbacks. You only need to report for the **one source that actually played** (the first accepted source in the waterfall). You do not need to report for sources that were skipped.

### When IMA SDK fires `STARTED`
```http
POST /v1/partner/device/{deviceId}/programmatic-event
Content-Type: application/json

{
  "event": "ad_started",
  "request_id": "req_1775716769503_eb810d042466",
  "variant_name": "adipolo",
  "creative_id": "<from IMA AdEvent.getAd().getCreativeId()>",
  "impression_id": "<from IMA AdEvent.getAd().getAdId() or generate UUID>"
}
```

### When IMA SDK fires `COMPLETE`
```http
POST /v1/partner/device/{deviceId}/programmatic-event

{
  "event": "ad_ended",
  "request_id": "req_1775716769503_eb810d042466",
  "variant_name": "adipolo",
  "creative_id": "<same as ad_started>",
  "impression_id": "<same as ad_started>"
}
```

### When the waterfall returns no ads
```http
POST /v1/partner/device/{deviceId}/programmatic-event

{
  "event": "no_fill",
  "request_id": "<request_id from the last source tried>",
  "variant_name": "<last variant name>"
}
```

### When IMA SDK fires `ERROR`
```http
POST /v1/partner/device/{deviceId}/programmatic-event

{
  "event": "error",
  "request_id": "...",
  "variant_name": "...",
  "error_code": "<IMA error code>",
  "error_message": "<IMA error message>"
}
```

### Required fields

You **must** include `request_id` and `variant_name` on every event. Events without these are silently dropped on our side.

### 7.1 The `<Error>` beacon — mandatory

`programmatic-event` is our HTTP report channel. The VAST `<Error>` element is the *IAB-standard* one, and it is **not** optional. Fire both.

Every VAST we serve carries an `<Error>` URL with the IAB `[ERRORCODE]` macro in it — on the programmatic wrap path, and, as of the signed-beacon change that shipped on the first-party direct rail, on `trillboards_direct` too. The URL is HMAC-**signed** by us (`sig=`), so it is only fireable as the beacon we minted:

```xml
<Error><![CDATA[https://api.trillboards.com/openrtb/v1/event?...&event=error&sig=...&errorCode=[ERRORCODE]]]></Error>
```

**On any ad failure, substitute the numeric IMA/VAST error code for the literal `[ERRORCODE]` and issue a GET to that URL.** IMA fires wrapper-level `<Error>` URLs for you when it can, but it cannot fire them for failures it never sees (your own fetch timeouts, your transport errors, a playback error you caught yourself) — so a custom or partly-custom player must fire them itself. Fire it once per failed source.

```kotlin
fun fireVastErrorBeacon(errorUrlFromVast: String?, errorCode: Any?) {
    val url = errorUrlFromVast ?: return
    val substituted = url.replace("[ERRORCODE]", Uri.encode(errorCode?.toString() ?: ""))
    // fire-and-forget GET; unauthenticated + idempotent, no response handling needed
    Thread { runCatching { URL(substituted).openStream().close() } }.start()
}
```

**Why this matters more than it looks.** On the first-party `trillboards_direct` rail the player is yours and we ship no agent onto it, so the `<Error>` beacon is the **only** ad-failure signal that exists for that rail. Without it we are structurally error-blind: our lifecycle rollups read `error_count = 0` for `self_promo` / `paid_direct` not because nothing failed, but because nothing *could report*. That blindness is precisely what turned one partner's black screen into a full production forensics session — there was no signal to look at.

Notes on the URL:

- `errorCode` is deliberately **outside** our signature, so substituting `[ERRORCODE]` can never invalidate the beacon. Do not strip, re-encode, or reorder the other query parameters — pass the URL through with only the macro replaced.
- `event` **is** signed, so an `error` beacon can never be replayed as a `complete`. The beacon is pure telemetry and can never move money — there is no reason to withhold it.
- Same dedup semantics as our other pixels; a duplicate fire collapses server-side.

The Lite SDK does all of this in one place — see `onAdError` in `trillboards-lite.src.js`: `[ERRORCODE]` substitution, `keepalive` GET (not `sendBeacon` — the endpoint is GET-only), then `trackVastRequest` and `reportProgrammaticEvent`. If you copy one function out of the reference implementation, copy that one.

**Custom / non-IMA players:** the `<Error>` URL is extracted the same way as the tracking URLs in [§5b](#5b-if-youre-not-using-google-ima-sdk-raw-vast-player) — add `error: getUrls('Error')` to `parseVastTrackingUrls`, and preserve `<Error>` at every wrapper level of the chain, exactly as you do for `<Impression>`.

### Automatic tracking (no code required)

On top of `programmatic-event`, our server also receives impression events automatically via tracking pixels embedded in the VAST XML. When IMA SDK processes the VAST and fires the `<Impression>` tag, it hits `https://api.trillboards.com/openrtb/v1/pixel?...&provider=adipolo` automatically. You don't need to do anything for this — it happens because you passed the full unmodified VAST to IMA.

Both paths (programmatic-event and tracking pixels) are deduplicated on our side by `request_id + impression_id`.

---

## 8. Verification — how to tell it's working

Ask your Trillboards contact to run these:

```bash
# Live fills from your devices
aws logs tail /ecs/trillboards-api --since 5m | grep 'vast-wrap.*adipolo/<screenId>.*fill=true'
```

Expected output format:
```
[vast-wrap] adipolo/{screenId} client={device IP} fill=true type=wrapper vpaid=false pt=partner_api size=21378 204ms
```

`fill=true` means Adipolo returned a real ad creative. `pt=partner_api` confirms your integration path. `size=21378` is a normal Adipolo wrapper response size — if it's much smaller the wrapper chain didn't resolve.

Completions arrive ~3-15 seconds after the fill. You'll know it's end-to-end working when you see `completed_impressions` rows with:
- `source_provider = 'adipolo'`
- `ingestion_path = 'vast_event'` (from the tracking pixels embedded in the VAST — what IMA fires automatically, and what a custom player must fire itself per [§5b](#5b-if-youre-not-using-google-ima-sdk-raw-vast-player)) OR `ingestion_path = 'proof_of_play'` OR `ingestion_path = 'partner_sdk'` (from your `programmatic-event` report)
- `request_id` matches the one from the waterfall source

> **Do not use `ingestion_path = 'impression_callback'` as your success signal.** That
> path is guarded and deliberately excluded from the revenue rollup — rows carrying it
> are not counted, so "I can see `impression_callback` rows" is not evidence that
> anything settled. `vast_event` and `proof_of_play` are the billing-grade paths.

A booked first-party direct ad delivered on the `data.ads` rail settles under
`ingestion_path = 'owned_direct'` instead, from the signed
`tracking.owned_direct_complete_url` beacon on the ad object. Fire that URL verbatim —
signature and all — and never rebuild it.

---

## 9. Common failure modes we've seen

### "You never have any demand — every request is a no-fill"
You are almost certainly reading `sources[0]` and stopping. Programmatic DSPs no-fill constantly and legitimately (wrong geo, no bid, budget exhausted) — the waterfall exists precisely so the *next* source gets a turn, and our own guaranteed `trillboards_direct` creative often sits several indexes down. Walk every source by `priority` ascending, skip `enabled: false`, and advance on 303/300/301/1009. See [§4.1](#41-the-waterfall-loop-contract) — this exact bug cost a partner a full production forensics session.

### "The screen goes black after every ad"
Content resume, not the ad. Your content `MediaItem` almost certainly has an empty or scheme-less URI, so media3 routes it to `FileDataSource` and dies with `ERROR_CODE_IO_FILE_NOT_FOUND` the moment IMA fires `CONTENT_RESUME_REQUESTED`. Full chain and both halves of the fix: [§6.1](#61-pitfall-the-uriempty-content-resume-black-screen-media3--ima). The tell is that ad-side metrics look perfect — fills and completions are fine, because nothing on the ad path failed.

### "Something is failing but you can't see anything on your side"
You are not firing the VAST `<Error>` beacon. On the first-party `trillboards_direct` rail it is the only ad-failure signal that exists — no beacon means our error counts read zero no matter how badly your player is failing. See [§7.1](#71-the-error-beacon--mandatory).

### "I'm getting fills but no completions"
Either:
1. Your IMA SDK has `setAdMediaMimeTypes("video/mp4")` set — remove it.
2. You're stripping the VAST wrapper before passing it to IMA — pass the full XML unmodified.
3. Your device can't reach `api.trillboards.com` to fire the tracking pixels (firewall / DNS).

### "My heartbeat sends device fields but you don't see them"
The heartbeat field must be `device.ua` (not `device.uaSample` or `telemetry.ua`). Our normalizer reads `body.device.ua`.

### "Fill rate is 1% when our own Rockchip screens fill at 60%"
Your heartbeat identity is bad. Check:
- `make` = the actual device manufacturer; do not infer it from the chipset name
- `model` = the actual hardware model; keep device serials and asset IDs in their identifier fields
- `osv` = Android release version (`"11"` or `"13"`); send the API level separately as `device.android_api_level` (`30` or `33`)
- `ua` = the actual WebView UA; identical models may legitimately report the same value, so do not invent unique identifiers or Build tokens

### "VidVerto specifically isn't completing"
VidVerto serves VPAID creatives. Native IMA SDK needs `setAdMediaMimeTypes` to be unset (or include `application/javascript`). This is the default — only override it if you're certain your player can only play mp4.

### "I want to test the wire format without building a full SDK"
Append **`?test=1`** to your `/ads` call. That forces a guaranteed-fill test source into that one response — public alias **`src_test`**, a direct MP4 URL with no wrapper chain to resolve. No allowlist enrollment is needed, it's per-request only (real devices polling without the flag are unaffected), and the creative is non-revenue. If `src_test` completes but real partners don't, your VAST handling is fine and the problem is in the partner response path (probably MIME filter). If `src_test` *doesn't* complete, the bug is in your player — start with [§4.1](#41-the-waterfall-loop-contract) and [§6.1](#61-pitfall-the-uriempty-content-resume-black-screen-media3--ima).

---

## 10. What's happening server-side (optional context)

When you GET a vast-wrap URL with `pt=partner_api`, our server does this:

1. **Fetches** the upstream partner VAST (e.g., Adipolo's `pubads.adipolo.co/ctv/ad?...`) with your device's IP in `X-Forwarded-For` so DSPs geo-target correctly.
2. **Resolves wrapper chains** up to 5 hops. Adipolo returns a wrapper pointing to GAM; we follow it and get the inline creative. Your device never sees the chain.
3. **Injects tracking pixels** at the outermost wrapper level — `<Impression>` and `<TrackingEvents>` for start/quartile/complete. These include `&provider={source_name}` so attribution is baked in at injection time.
4. **Returns** the final VAST XML (inline or resolved wrapper) with our pixels embedded.

You get back a VAST that's ready to hand straight to IMA SDK with no processing on your end.

---

## 11. Reference implementation

### The canonical code: the Trillboards Lite SDK

[`trillboard-screen/public/partner-sdk/trillboards-lite.src.js`](https://github.com/trillboards/packages/blob/production/trillboard-screen/public/partner-sdk/trillboards-lite.src.js) is our own player, and it is the reference implementation for everything in [§0](#0-integration-requirements--read-this-before-you-write-any-code). It's JavaScript, but the *control flow* is what you're copying, and it ports directly to Kotlin.

Read `onAdError` first. In one handler it does all of this, in this order:

1. Pulls `errorCode` + `errorMessage` off the IMA `AdErrorEvent`.
2. Classifies the failure — `1009` / `303` / a message containing `no fill` or `no ads vast response` is a **no-fill**; anything else is an **error**. (R2)
3. Fires the VAST `<Error>` URL with `[ERRORCODE]` substituted for the real code, as a `keepalive` GET. (R5)
4. Records the VAST request outcome (`no_fill` vs `error`) with latency and source name.
5. Reports the `programmatic-event` with `request_id`, `variant_name`, `error_code`, `error_message`. (R6)
6. **Only resolves the caller when `_pendingWaterfallSources` is empty** — while sources remain, it advances to the next one instead of finishing. (R1 + R2)
7. Invokes a host callback so the embedding app can repaint its own surface. (R4)

Points 6 and 7 are the two that partners most often miss, and they're the two that produce the two worst failure modes: a waterfall that gives up at index 0, and a screen that stays black.

### The reference deployment: Take 10 Media

Take 10 Media (`com.take10media.adplayer`) is the reference *native Android* integration. Key facts about their working setup:

- Native Android IMA SDK via Media3 + ImaAdsLoader 1.10.0
- Rockchip devices (`rk3288`, `rk3568_r`) running Android 9-14
- **No** Google Play Services (the devices are not Google-certified — this is fine)
- Agent version 2.0.18 (removed `setAdMediaMimeTypes` in this version)
- Heartbeat every 60 seconds with full WebView UA
- VAST XML passed to IMA via `data:text/xml` URI (Media3 internally calls `setAdsResponse`)
- Events reported via `programmatic-event` for the first played source only

Fill rate: 61% Adipolo. Completion rate: 79% of fills. Effective: ~48% of all ad requests result in billable completions.

---

## 12. Trillboards Sensing SDK (Android) — optional, alongside the IMA integration

Two artifacts cover two distinct hardware classes. Pick by what your screens actually have, NOT by what features you might want — installing the wrong one wastes bundle size and (for AGP <8) won't even link.

### Which SDK matches your hardware?

- **Camera/mic-equipped retail screens** (digital signage, in-store displays with an audience-facing camera) → **`com.trillboards:agent-core:1.14.0`** — full Sensing SDK with face / audio / speech / pose / VLM. See §12.B.
- **Camera-less appliance screens** (vending machines, ATMs, EV charging stations, self-checkout, smart lockers, transit shelters) → **`com.trillboards:ctv-measurement:1.3.2`** — passive BLE / WiFi / mDNS / SSDP / HTTP-probe / native-sensor capture only. See §12.A.

Both ship sensing data over the same `/openrtb/v1/heartbeat` endpoint. After
registration, liveness and targeting-identity heartbeats require no Partner API
key; the stable registered device ID supplies the screen binding. The two SDKs
are wire-format-compatible, so partners with a mixed fleet (some
camera-equipped + some appliance) emit identically-shaped heartbeats from both.

### Build compatibility matrix

| Artifact | Hardware profile | Min AGP | Min Gradle | Min JDK | Min Android | Bundle | Jetifier OK |
|---|---|---|---|---|---|---|---|
| `ctv-measurement` | Camera-less appliance (vending / ATM / charging / kiosk) | **4.1** | 6.5 | 8 | 24 (Android 7.0) | ~3 MB | **Yes** |
| `agent-core` (full) | Camera + mic equipped retail screen | 8.0 | 8.0 | 17 | 26 (Android 8.0) | ~180 MB | No |

> **Why the AGP gap?** `agent-core` bundles CameraX 1.5.3, which embeds `minAndroidGradlePluginVersion=8.0.0` in its AAR metadata — AGP 4.x consumers will hard-fail at `checkDebugAarMetadata`. `ctv-measurement` ships Java 1.8 bytecode (class v52) with no camera/ML deps, so AGP 4.1 + Jetifier (ASM 8, max class v58) can consume it cleanly.

### What the backend does with the raw signals

Whichever SDK you install, you ship raw signals — Trillboards' audience resolver does all the math server-side:

- **BLE proximity** → presence-graph contribution + dwell estimation
- **WiFi network analysis** → venue intelligence (network density, RSSI variance as motion proxy, frequency-band ladder for venue-type classification)
- **mDNS / SSDP / HTTP-probe** → on-network device-class fingerprint (smart TVs, IoT hubs, point-of-sale terminals, printers) feeding co-viewing inference
- **Native sensors** (accelerometer, light, barometer, proximity) → ambient context for footfall / illumination cross-checks

All derived signals are attached to your bid requests automatically. You do not run any aggregation, ML, or schema-translation code client-side. Updating to a newer SDK version never requires backend coordination — the wire contract is stable.

---

## 12.A Camera-less appliances — `ctv-measurement`

For vending machines, ATMs, EV charging stations, self-checkout kiosks, smart lockers, and other Android appliance hardware **without cameras or microphones**.

**Maven coordinate:** `com.trillboards:ctv-measurement:1.3.2`

**Registry:** `maven.trillboards.com` (anonymous read, no auth tokens — the canonical Trillboards SDK Maven CDN).

**Source mirror:** https://github.com/trillboards/ctv-measurement-sdk (Apache 2.0).

### 12.A.1 Add the Maven registry

In your project's `settings.gradle.kts` (or root `build.gradle.kts`):

```kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.trillboards.com") }
    }
}
```

### 12.A.2 Add the dependency

In your app module's `build.gradle.kts`:

```kotlin
dependencies {
    implementation("com.trillboards:ctv-measurement:1.3.2")
}
```

The AAR is self-contained: BLE / WiFi / mDNS / SSDP / HTTP-probe / native-sensor scanners, plus a Rust-backed mDNS discovery layer (UniFFI bindings + per-ABI `.so` for `arm64-v8a` and `armeabi-v7a`). No camera, no microphone, no ML — works as-is on AGP 4.1+ + Jetifier.

### 12.A.3 Manifest permissions

Declare in your app's `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_MULTICAST_STATE" />

<!-- BLE — API 31+ uses BLUETOOTH_SCAN + neverForLocation; older API falls back to ACCESS_FINE_LOCATION -->
<uses-permission android:name="android.permission.BLUETOOTH_SCAN"
    android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
    android:maxSdkVersion="30" />

<!-- WiFi — API 33+ uses NEARBY_WIFI_DEVICES; older API uses ACCESS_WIFI_STATE -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES"
    android:usesPermissionFlags="neverForLocation" />
```

**Both `BLUETOOTH_SCAN` and `NEARBY_WIFI_DEVICES` are runtime-dangerous — you
must request each one at runtime.** Declaring them (or letting the AAR's
manifest merge in) is not a grant. Requesting only `BLUETOOTH_SCAN` yields BLE
observations and a permanent zero on WiFi; requesting only `NEARBY_WIFI_DEVICES`
yields the reverse. Below API 31 BLE falls back to `ACCESS_FINE_LOCATION`.
**WiFi scanning needs `ACCESS_FINE_LOCATION` at every API level — including
33+, where it is required *in addition to* `NEARBY_WIFI_DEVICES`** — because
`WifiManager.startScan()`/`getScanResults()` are the documented carve-out that
`NEARBY_WIFI_DEVICES` does not cover. The AAR caps its own declaration at
`maxSdkVersion="30"`, so on API 31+ you must declare an uncapped
`ACCESS_FINE_LOCATION` yourself. Copy the per-API-level `requestPermissions`
snippet and the logcat verification from
[CTV Measurement SDK — Partner Integration Guide § Step 1b](https://api.trillboards.com/docs/integrations/ctv-measurement-partner-integration.md).

Radio observations remain bounded to the measurement contract. Targeting
identities are separate: the SDK sends the real resettable GAID/AAID when the
platform exposes one, and can send exact host-owned HEM/UID2 values. It never
uses a screen or registered-device UUID as a MAID.

### 12.A.4 Initialize the SDK

Call once from `Application.onCreate()`:

```kotlin
import com.trillboards.measurement.*

TrillboardsMeasurement.initialize(
    context = applicationContext,
    config = MeasurementConfig.Builder(
            deviceId = yourStableRegisteredDeviceId,
        )
        .scanIntervalMs(30_000L)
        .enabledSources(setOf(
            SignalSource.BLE, SignalSource.WIFI, SignalSource.MDNS,
            SignalSource.SSDP, SignalSource.HTTP_PROBE, SignalSource.NATIVE_SENSOR,
        ))
        .build(),
)
TrillboardsMeasurement.setConsentStatus(true)
TrillboardsMeasurement.startScheduledScans()
```

The SDK posts to `/openrtb/v1/heartbeat` on its own schedule without an API
key. Use the same stable ID registered as the device's `external_id`. Call
`TrillboardsMeasurement.shutdown()` if you need to wind sensing down (rare).

### 12.A.5 WebView bridge (optional)

If your ad creatives need to read cached snapshots from JavaScript:

```kotlin
TrillboardsMeasurement.attachToWebView(myWebView)
// Inside the ad creative:
//   window.TrillboardsMeasurement.getSnapshot()   → JSON string
//   window.TrillboardsMeasurement.getVersion()    → bridge version
```

Bridge must be attached **before** `WebView.loadUrl()`. The SDK holds the WebView via a `WeakReference` so there's no Activity/Fragment leak risk.

---

## 12.B Camera/mic-equipped retail screens — `agent-core`

For retail screens with audience-facing cameras and/or microphones (digital signage, in-store displays, kiosks with depth/RGB cameras). Face detection, attention estimation, audio classification, speech ASR, pose and VLM inference run on the screen. The agent sends Trillboards a record for each detected person, a face-identity template on the full sensing profile, speech transcripts, the Bluetooth, Wi-Fi and local-network identifiers of nearby devices, the screen's GPS position, and selected camera frames for cloud analysis.

**Maven coordinate:** `com.trillboards:agent-core:1.14.0`

**Registry:** `maven.trillboards.com` (anonymous read, no auth tokens — the canonical Trillboards SDK Maven CDN).

**Source mirror:** https://github.com/trillboards/agent-core (Apache 2.0).

### 12.B.1 Add the Maven registry

In your project's `settings.gradle.kts` (or root `build.gradle.kts`):

```kotlin
dependencyResolutionManagement {
    repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.trillboards.com") }
    }
}
```

No credentials needed — `maven.trillboards.com` serves every Trillboards Sensing SDK release anonymously from the canonical Maven CDN. Pin an exact version (`com.trillboards:agent-core:1.14.0`) or float the minor line (`com.trillboards:agent-core:1.14.+`). The public source mirror lives at `trillboards/agent-core`.

### 12.B.2 Add the dependency

In your app module's `build.gradle.kts`:

```kotlin
dependencies {
    implementation("com.trillboards:agent-core:1.14.0")
}
```

The AAR pulls MediaPipe Tasks, TensorFlow Lite, CameraX, and Media3 transitively — face detection, audio classification, BLE/WiFi co-viewing, and demographic inference work out of the box. (sherpa-onnx ASR is opt-in via the BYO flow in §12.5b.)

**Do not exclude transitive groups to disable a modality.** agent-core hard-codes references to `com.google.mediapipe.tasks.audio.*`, `com.google.mediapipe.tasks.vision.*`, and friends; excluding the corresponding artifact at the Gradle level produces a `NoClassDefFoundError` at runtime the first time the agent tries to instantiate that processor — long after your CI passes. Use the `SensingSdkConfig` runtime flags in §12.4 instead:

```kotlin
TrillboardsSensingSdk.start(
    context = applicationContext,
    config = SensingSdkConfig(
        deviceId = yourStableRegisteredDeviceId,
        audioClassificationEnabled = false,  // mic-less screens
        speechIntelligenceEnabled = false,   // no ASR
        // …other modality flags
    )
)
```

This keeps the dep graph valid while skipping the processors at runtime — same effect, no crash risk.

### 12.B.3 Manifest permissions

Declare in your app's `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" />        <!-- API 31+ -->
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />     <!-- API 31+, required for BLE GATT 0x180A device-info enrichment -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />  <!-- API <31 fallback for BLE; required for WiFi scanning at EVERY API level, incl. 33+ -->
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" />  <!-- API 33+ WiFi scan -->
<uses-permission android:name="android.permission.INTERNET" />
```

Camera, microphone, **`BLUETOOTH_SCAN` (API 31+), and `NEARBY_WIFI_DEVICES` (API 33+)** are all runtime permissions — request every one of them via the standard Android prompt before starting the agent. The radio permissions are the easy ones to miss because they merge in from the AAR and never prompt on their own: skip the `NEARBY_WIFI_DEVICES` request and WiFi scanning returns nothing on Android 13+ while BLE keeps reporting normally. Use the per-API-level snippet in [CTV Measurement SDK — Partner Integration Guide § Step 1b](https://api.trillboards.com/docs/integrations/ctv-measurement-partner-integration.md). The agent records no video and no audio; everything it sends is listed at the top of §12.B.

### 12.B.4 Initialize the SDK

Call `TrillboardsSensingSdk.start()` once — typically from
`MainActivity.onCreate()` or `Application.onCreate()`. Pass the same stable
device ID used during registration. Do not embed a Partner API key; the SDK
resolves the registered screen and manages any privileged sensing-channel
credential internally.

```kotlin
import com.trillboards.sdk.SensingSdkConfig
import com.trillboards.sdk.TrillboardsSensingSdk

class MainActivity : AppCompatActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        TrillboardsSensingSdk.start(
            context = applicationContext,
            config = SensingSdkConfig(
                deviceId = yourStableRegisteredDeviceId
            )
        )
    }
}
```

Need to disable a modality (e.g., your screens have no microphone) or point at a non-prod environment? Pass a `SensingSdkConfig`:

```kotlin
TrillboardsSensingSdk.start(
    context = applicationContext,
    config = SensingSdkConfig(
        deviceId = yourStableRegisteredDeviceId,
        audioClassificationEnabled = false,
        speechIntelligenceEnabled = false,
        apiBaseUrl = "https://staging.api.trillboards.com",
        socketUrl = "https://staging.chat.trillboards.com"
    )
)
```

Call `TrillboardsSensingSdk.stop(applicationContext)` if you need to wind sensing down (rare — the SDK is designed to run continuously alongside your ad-serving loop).

That's the minimum integration. The agent handles camera initialization, model OTA download (~178 MB FaceXFormer + Moonshine, downloaded once on first run, then cached), heartbeat scheduling, and Socket.io reconnection internally.

### 12.B.5 What you get on the wire

The agent emits two channels:

1. **HTTP heartbeat** — `POST /openrtb/v1/heartbeat` every 30s. Carries device
   health, capabilities, BLE/WiFi co-viewing arrays, the actual platform MAID
   when available, and typed host-provided HEM/UID2. The POST is unauthenticated
   after device registration; the device/screen binding provides attribution.
   Read live state with authenticated
   `GET /v1/partner/device/{deviceId}/heartbeat` (see API reference).
2. **Real-time signals** — Socket.io to `chat.trillboards.com`, room joined automatically on `start()`. Events: `audienceSignals` (face/audio/speech detections), `audienceDemographics` (rolling demographic estimates), `deviceCapabilities` (model availability). These feed our backend for the audience-attention flywheel; you don't need to subscribe to them directly unless you want to mirror the data.

### 12.B.6 Speech recognition

**agent-core 1.22 and later: included, nothing to add.** On-device speech recognition (Moonshine ASR via [sherpa-onnx](https://github.com/k2-fsa/sherpa-onnx)) comes with the SDK. agent-core depends on `com.trillboards.bundled:sherpa-onnx-static-ort:1.12.40`, served from the same repository as agent-core, and carries the Moonshine model in its assets. Remove any `sherpa-onnx-*.aar` you added to `libs/` for an earlier agent-core: two copies of `com.k2fsa.sherpa.onnx` on one classpath fail the build as duplicate classes.

- **Your own ONNX Runtime is safe.** The bundled sherpa-onnx links ONNX Runtime statically and exports none of its symbols, so an app that also depends on `com.microsoft.onnxruntime:onnxruntime-android` (any version) builds with no `pickFirst` and runs both. (If your app uses ONNX Runtime with R8, keep `ai.onnxruntime.**` in your own rules — onnxruntime-android does not ship that rule.)
- **R8 / minified builds need nothing from you** for agent-core: its consumer ProGuard rules keep the sherpa-onnx classes its JNI reads by name and the LiteRT-LM classes it loads by reflection.
- **APK size (arm64-v8a):** the sherpa-onnx JNI library is 22.2 MB (the shared-ORT AAR earlier versions asked you to add was 35.1 MB for the same ABI).

Spanish transcription and spoken-language ID use a Whisper model that is delivered over the air to screens it is rolled out to; it is not in the APK.

**Earlier agent-core versions: bring your own sherpa-onnx.** There speech recognition is opt-in, because agent-core declares sherpa-onnx `compileOnly`. Face detection, audio classification, BLE/WiFi co-viewing and demographics work without any extra setup; only speech recognition is gated. To turn it on:

1. Download `sherpa-onnx-1.12.26.aar` from the [sherpa-onnx releases page](https://github.com/k2-fsa/sherpa-onnx/releases) (or contact `engineering@trillboards.com` for the Trillboards-bundled copy with the matching native libs).
2. Drop it into your app's `libs/` folder.
3. Register a `flatDir` repository so Gradle can resolve it:

   ```kotlin
   // settings.gradle.kts
   dependencyResolutionManagement {
       repositories {
           flatDir { dirs(file("app/libs")) }
       }
   }
   ```

4. Add the implementation dep:

   ```kotlin
   // app/build.gradle.kts
   dependencies {
       implementation(":sherpa-onnx-1.12.26@aar")
   }
   ```

5. Bundle the Moonshine model assets under `app/src/main/assets/moonshine-tiny/`. The agent's runtime probe looks for `moonshine-tiny/tokens.txt`; if the file isn't present, speech recognition is silently skipped without affecting other modalities.

### 12.B.7 Reference implementation

`com.trillboards:agent-core:1.14.0` ships the canonical Kotlin codebase that powers Trillboards' first-party retail screens. Source mirror lives at https://github.com/trillboards/agent-core (Apache 2.0).

---

## 12.C Cross-references (both SDKs)

- **WebView ad creatives that need to read sensing data**: [`docs/integrations/partner-native-bridge.md`](https://github.com/trillboards/packages/blob/production/docs/integrations/partner-native-bridge.md) — the `__TRILL_BRIDGE_V1__` JS interface the agent injects into your WebView.
- **CTV measurement integration patterns** (frame-rate budgeting, signal mapping, partner OEM cookbook): [`trillboard-api/docs/integrations/ctv-measurement-partner-integration.md`](https://api.trillboards.com/docs/integrations/ctv-measurement-partner-integration.md).
- **Embed SDK for partner CMS surfaces** (web players, kiosk shells embedding Trillboards content): [`docs/integrations/partner-embed-sdk.md`](https://github.com/trillboards/packages/blob/production/docs/integrations/partner-embed-sdk.md).
- **Browser/CTV sensing without native Android**: `npm i @trillboards/ctv-measurement` for browser-side BLE bridge consumers + Census enrichment + QR attribution.
- **Linux/Windows DOOH partners** (no Android): `npm i @trillboards/edge-sdk` for V4L2 / DirectShow / BlueZ-based sensing.
- **Zero-friction NPM facade for vending / kiosk monetization** (no native code): `npm i @trillboards/connect`.

The Sensing SDK page on the developer hub at `https://trillboards.com/support/developers/sensing-sdk` covers configuration tuning, what the SDK sends and how long Trillboards keeps it, model lifecycle, and capability tier defaults.

---

## 13. Support

When something breaks, share the following with Trillboards support:

1. **A screen_id** that's actively requesting ads
2. **Your device's actual heartbeat body** (the HTTP POST body, not a logcat sample)
3. **The full `vast_waterfall` object** from one `/ads` response — the whole `sources[]` array, not just the entry you used — plus **which indexes your player actually tried**. This one line of evidence separates "no demand" from "your loop stopped at index 0" instantly.
4. **The VAST response you got back** from vast-wrap for one request (save the raw XML)
5. **IMA SDK error codes** if playback fails (from the `AdErrorEvent` callback) **and** any `PlaybackException` from `onPlayerError` — they are different listeners and different failure classes ([§6.1](#61-pitfall-the-uriempty-content-resume-black-screen-media3--ima))
6. **Your `programmatic-event` POST body** for both ad_started and ad_ended for one ad

With these six artifacts we can trace the complete request lifecycle and tell you exactly what's broken.

---

# Partner Native Bridge protocol
# Source: https://api.trillboards.com/docs/guides/integrations/partner-native-bridge.md

# Partner Native Bridge Protocol

The Trillboards Lite SDK includes a **Universal Native Bridge** that enables seamless
communication between the SDK (running in a WebView/iframe) and your native host
application. This allows you to receive ad events and send commands from Android,
iOS, React Native, Flutter, CTV, Electron, and other platforms.

## Overview

When embedding the Trillboards Lite SDK in a native application, you need a way to:

1. **Receive events** when ads start, complete, error, or have no fill
2. **Send commands** to show/hide ads, skip, or refresh

The Native Bridge handles this by:
- **Auto-detecting** standard bridge interfaces (Android, iOS, React Native, etc.)
- **Allowing custom bridge registration** for non-standard integrations
- **Using a standardized event protocol** across all platforms

## Quick Start (Zero Config)

For most platforms, the SDK auto-detects the native bridge. Just expose the
standard interface in your native code:

### Android WebView

```kotlin
// In your WebView setup
webView.addJavascriptInterface(object {
    @JavascriptInterface
    fun onEvent(payload: String) {
        val event = JSONObject(payload)
        when (event.getString("event")) {
            "ad_started" -> handleAdStarted(event.getJSONObject("data"))
            "ad_completed" -> handleAdCompleted(event.getJSONObject("data"))
            "ad_error" -> handleAdError(event.getJSONObject("data"))
            "no_ads" -> handleNoAds(event.getJSONObject("data"))
        }
    }
}, "TrillboardsBridge")
```

### iOS WKWebView

```swift
// In your WKWebView setup
let contentController = webView.configuration.userContentController
contentController.add(self, name: "trillboards")

// Implement WKScriptMessageHandler
extension YourViewController: WKScriptMessageHandler {
    func userContentController(_ controller: WKUserContentController,
                               didReceive message: WKScriptMessage) {
        guard message.name == "trillboards",
              let body = message.body as? [String: Any],
              let event = body["event"] as? String else { return }

        switch event {
        case "ad_started": handleAdStarted(body["data"] as? [String: Any])
        case "ad_completed": handleAdCompleted(body["data"] as? [String: Any])
        case "ad_error": handleAdError(body["data"] as? [String: Any])
        case "no_ads": handleNoAds(body["data"] as? [String: Any])
        default: break
        }
    }
}
```

### React Native WebView

```tsx
import { WebView } from 'react-native-webview';

function AdPlayer() {
  const handleMessage = (event: WebViewMessageEvent) => {
    const data = JSON.parse(event.nativeEvent.data);
    if (data.type !== 'trillboards') return;

    switch (data.event) {
      case 'ad_started':
        console.log('Ad started:', data.data);
        break;
      case 'ad_completed':
        console.log('Ad completed:', data.data);
        break;
      case 'ad_error':
        console.log('Ad error:', data.data);
        break;
      case 'no_ads':
        console.log('No ads available:', data.data);
        break;
    }
  };

  return (
    <WebView
      source={{ uri: 'https://screen.trillboards.com/partner-sdk/embed.html?device=YOUR_DEVICE_ID' }}
      onMessage={handleMessage}
      javaScriptEnabled
      mediaPlaybackRequiresUserAction={false}
    />
  );
}
```

### Flutter WebView

```dart
import 'package:webview_flutter/webview_flutter.dart';
import 'dart:convert';

class AdPlayerWidget extends StatefulWidget {
  @override
  _AdPlayerWidgetState createState() => _AdPlayerWidgetState();
}

class _AdPlayerWidgetState extends State<AdPlayerWidget> {
  late WebViewController _controller;

  @override
  Widget build(BuildContext context) {
    return WebViewWidget(
      controller: WebViewController()
        ..setJavaScriptMode(JavaScriptMode.unrestricted)
        ..addJavaScriptChannel(
          'Flutter',
          onMessageReceived: (message) {
            final data = jsonDecode(message.message);
            if (data['type'] != 'trillboards') return;

            switch (data['event']) {
              case 'ad_started':
                print('Ad started: ${data['data']}');
                break;
              case 'ad_completed':
                print('Ad completed: ${data['data']}');
                break;
              case 'ad_error':
                print('Ad error: ${data['data']}');
                break;
              case 'no_ads':
                print('No ads: ${data['data']}');
                break;
            }
          },
        )
        ..loadRequest(Uri.parse(
          'https://screen.trillboards.com/partner-sdk/embed.html?device=YOUR_DEVICE_ID'
        )),
    );
  }
}
```

## Auto-Detection Matrix

The SDK automatically detects these interfaces (in order):

| Platform | Detection | Interface |
|----------|-----------|-----------|
| Android WebView | `window.TrillboardsBridge.onEvent` | `TrillboardsBridge.onEvent(jsonString)` |
| Android (alt) | `window.Android.onTrillboardsEvent` | `Android.onTrillboardsEvent(jsonString)` |
| iOS WKWebView | `window.webkit.messageHandlers.trillboards` | `trillboards.postMessage(object)` |
| React Native | `window.ReactNativeWebView.postMessage` | `ReactNativeWebView.postMessage(jsonString)` |
| Flutter | `window.Flutter.postMessage` | `Flutter.postMessage(jsonString)` |
| CTV (Tizen/webOS/Fire TV) | `window.__TRILL_CTV_BRIDGE__.postEvent` | `__TRILL_CTV_BRIDGE__.postEvent(jsonString)` |
| Electron | `window.electronAPI.trillboardsEvent` | `electronAPI.trillboardsEvent(object)` |
| Tauri | `window.__TAURI__.event` | Emits `trillboards-event` |
| Iframe embed | `window.parent !== window` | `parent.postMessage(object, '*')` |

## Custom Bridge Registration

For non-standard integrations, register a custom bridge:

```javascript
// In your WebView's JavaScript context
TrillboardsLite.registerBridge({
    // Required: how to send events to host
    send: function(event, data) {
        // Your custom transport
        MyCustomBridge.sendEvent(JSON.stringify({ event, data }));
    },

    // Optional: receive commands from host
    receive: function(callback) {
        // Set up listener for host commands
        MyCustomBridge.onCommand = callback;
    },

    // Optional: filter which events to send (reduces noise)
    events: ['ad_started', 'ad_completed', 'ad_error', 'no_ads'],

    // Optional: bridge name for debugging
    name: 'MyCustomBridge'
});
```

## Event Protocol

All events follow this standardized payload structure:

```typescript
interface TrillboardsEvent {
    type: 'trillboards';           // Message type identifier
    version: '1.0';                // Protocol version
    event: string;                 // Event name (see table below)
    data: object;                  // Event-specific data
    timestamp: number;             // Unix timestamp (ms)
    deviceId: string;              // Device identifier
    screenId?: string;             // Screen identifier (if linked)
    sessionId: string;             // Session identifier
}
```

### Events Reference

| Event | Description | Data |
|-------|-------------|------|
| `ready` | SDK initialized | `{ deviceId, screenId, adCount, waterfallMode }` |
| `ad_started` | Ad began playing | `{ type: 'programmatic'\|'image'\|'video', adId?, url? }` |
| `ad_completed` | Ad finished naturally | `{ type, reason: 'complete', completed: true }` |
| `ad_skipped` | User skipped ad | `{ type }` |
| `ad_ended` | Ad playback ended | `{ type?, reason? }` |
| `ad_error` | Ad failed | `{ type, error: { message, code? } }` |
| `no_ads` | No fill available | `{ reason: 'no_fill'\|'offline'\|'programmatic_unavailable' }` |
| `overlay_clicked` | User tapped CTA | `{}` |
| `ads_refreshed` | Ad list updated | `{ count }` |
| `online` | Network restored | `{}` |
| `offline` | Network lost | `{}` |
| `state_changed` | State response | Full state object (see `getState()`) |

## Sending Commands to SDK

Your native app can send commands to control the SDK.

### From Android

```kotlin
// Show an ad
webView.evaluateJavascript("TrillboardsLite.show()", null)

// Hide the player
webView.evaluateJavascript("TrillboardsLite.hide()", null)

// Skip current ad
webView.evaluateJavascript("TrillboardsLite.skipAd()", null)

// Refresh ad list
webView.evaluateJavascript("TrillboardsLite.refresh()", null)
```

### From iOS

```swift
// Show an ad
webView.evaluateJavaScript("TrillboardsLite.show()")

// Hide the player
webView.evaluateJavaScript("TrillboardsLite.hide()")
```

### From React Native

```tsx
const webViewRef = useRef<WebView>(null);

// Show an ad
webViewRef.current?.injectJavaScript('TrillboardsLite.show(); true;');

// Hide the player
webViewRef.current?.injectJavaScript('TrillboardsLite.hide(); true;');
```

### Via postMessage (Iframe)

```javascript
// From parent window to iframe
const iframe = document.getElementById('trillboards-iframe');

// Show an ad
iframe.contentWindow.postMessage({
    type: 'trillboards-command',
    action: 'show'
}, '*');

// Hide the player
iframe.contentWindow.postMessage({
    type: 'trillboards-command',
    action: 'hide'
}, '*');

// Get current state (response via state_changed event)
iframe.contentWindow.postMessage({
    type: 'trillboards-command',
    action: 'getState'
}, '*');

// Update configuration
iframe.contentWindow.postMessage({
    type: 'trillboards-command',
    action: 'configure',
    params: { waterfall: 'programmatic_only', volume: 0 }
}, '*');
```

### Command Reference

| Command | Description | Parameters |
|---------|-------------|------------|
| `show` | Request and play an ad | `{ immediate?: boolean }` |
| `hide` | Stop and hide player | `{ silent?: boolean }` |
| `skip` | Skip current ad | `{}` |
| `refresh` | Refresh ad list from API | `{}` |
| `getState` | Request current state | `{}` (responds with `state_changed`) |
| `configure` | Update settings | `{ waterfall?, volume? }` |

## Platform-Specific Guides

### CTV (Smart TVs)

For Tizen (Samsung), webOS (LG), Fire TV, and Android TV:

```javascript
// On your CTV app, expose this interface before loading the WebView
window.__TRILL_CTV_BRIDGE__ = {
    postEvent: function(jsonString) {
        // Parse and route to your CTV app's event system
        const event = JSON.parse(jsonString);
        TizenBridge.sendEvent(event.event, event.data);
    }
};
```

### Electron

```javascript
// In preload.js
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('electronAPI', {
    trillboardsEvent: (data) => {
        ipcRenderer.send('trillboards-event', data);
    }
});

// In main.js
ipcMain.on('trillboards-event', (event, data) => {
    console.log('Trillboards event:', data.event, data.data);
});
```

### Tauri

```rust
// In your Tauri app
use tauri::Manager;

fn main() {
    tauri::Builder::default()
        .setup(|app| {
            let window = app.get_window("main").unwrap();
            window.listen("trillboards-event", |event| {
                println!("Trillboards event: {:?}", event.payload());
            });
            Ok(())
        })
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}
```

### Capacitor/Cordova

```typescript
// Using @capawesome/capacitor-app-webview
import { AppWebview } from '@capawesome/capacitor-app-webview';

// Listen for messages
AppWebview.addListener('message', (event) => {
    const data = JSON.parse(event.message);
    if (data.type === 'trillboards') {
        console.log('Trillboards event:', data.event);
    }
});
```

## Event Filtering

To reduce noise, filter events at registration:

```javascript
TrillboardsLite.registerBridge({
    send: (event, data) => { /* ... */ },
    // Only receive these critical events
    events: ['ad_started', 'ad_completed', 'ad_error', 'no_ads']
});
```

## Best Practices

### 1. Handle Offline Gracefully

The SDK caches ads for offline playback. Listen for `online`/`offline` events:

```kotlin
"offline" -> {
    // Show offline indicator or pause ad requests
}
"online" -> {
    // Resume normal operation
}
```

### 2. Track Session State

Use the `sessionId` in events to correlate ads within a user session:

```kotlin
val sessionMetrics = mutableMapOf<String, MutableList<String>>()

fun handleEvent(event: JSONObject) {
    val sessionId = event.getString("sessionId")
    val eventName = event.getString("event")
    sessionMetrics.getOrPut(sessionId) { mutableListOf() }.add(eventName)
}
```

### 3. Implement Retry Logic

When `no_ads` occurs, the SDK automatically retries in `programmatic_only` mode.
For manual control:

```kotlin
"no_ads" -> {
    // SDK handles retry automatically, but you can track
    Log.d("Trillboards", "No fill - SDK will retry")
}
```

### 4. Clean Up on Destroy

```kotlin
override fun onDestroy() {
    webView.evaluateJavascript("TrillboardsLite.destroy()", null)
    super.onDestroy()
}
```

## Troubleshooting

### Events Not Received

1. **Check interface name**: Ensure your bridge uses the exact name the SDK expects
2. **Check timing**: Register your interface before the WebView loads the SDK
3. **Check console**: Look for `[Trillboards] Bridge auto-detected:` log
4. **Use custom bridge**: If auto-detection fails, register explicitly

### Commands Not Working

1. **Check WebView is loaded**: Wait for page load before sending commands
2. **Check JavaScript enabled**: Ensure `javaScriptEnabled = true`
3. **Check console errors**: Look for JavaScript errors in WebView

### Debugging

Enable verbose logging:

```javascript
// In WebView console
console.log('[Trillboards] Bridge detected:', window.TrillboardsBridge ? 'yes' : 'no');
console.log('[Trillboards] State:', TrillboardsLite.getState());
```

## FAQ

### Is `/programmatic-event` API for native communication?

**No.** The `/device/{deviceId}/programmatic-event` endpoint is a **server-side
analytics endpoint**. It records events for Trillboards' internal analytics and
triggers webhooks. It does NOT push events to your native app.

For native app event delivery, use the **JavaScript Native Bridge** described
in this document.

### Can I use both webhooks and native bridge?

**Yes.** They serve different purposes:
- **Native Bridge**: Real-time events to your native app UI
- **Webhooks**: Server-side event processing, analytics, billing integration

### What if my platform isn't listed?

Use the custom bridge registration:

```javascript
TrillboardsLite.registerBridge({
    send: (event, data) => {
        // Your custom transport mechanism
    }
});
```

### How do I test the bridge?

1. Load the SDK in your WebView
2. Open developer console
3. Trigger an ad: `TrillboardsLite.show()`
4. Check your native handler receives events

## Related Documentation

- [Lite SDK Overview](partner-lite-sdk.md)
- [Local Testing](partner-lite-sdk-local-testing.md)
- [Partner CMS API](partner-cms-api.md)
- [Programmatic Settings](partner-programmatic-settings.md)

---

# Sensing SDK (Android)
# Source: https://api.trillboards.com/docs/guides/integrations/partner-sensing-sdk.md

# Trillboards Sensing SDK — Android Integration Brief (agent-executable)

> **This is NOT the ad-monetization (IMA) guide.** This is the **camera + microphone + Wi-Fi + Bluetooth audience-SENSING** SDK — the same `agent-core` engine that powers Trillboards' own retail screens. It produces audience **Moments, scenes, demographics, and custom chips** in the Trillboards Venue portal. Ad serving is a separate, optional SDK.
>
> **How to use this doc:** paste it into Claude Code / Cursor inside your Android app's repo. The AI agent should follow it top-to-bottom and stop only at the **Done criteria** at the end. Everything needed is here.

---

## What you're integrating
You are embedding the **Trillboards Sensing SDK** (`com.trillboards:agent-core`, from GitHub Packages) into an **existing Android app** that runs on in-store screens/boxes. After integration, each box's camera/mic/Wi-Fi/BLE feed on-device AI (face, age/gender, emotion, pose, audio, speech, BLE/Wi-Fi co-viewing), and the resulting **audience intelligence attributes to that box's screen** in the Trillboards Venue portal — automatically. No ads, no kiosk takeover; the SDK runs as a library inside the host app.

## Prerequisites (you already have these)
1. **Your devices are already registered** with Trillboards (one row per box) via authenticated `POST /v1/partner/device`, each with a stable **`external_id`** you chose (e.g. a serial like `DD-H80F55`). That `external_id` is the **only per-box value the SDK needs at runtime.** If a box is not yet registered, register it first (see Appendix A).
2. **Your Trillboards Partner API key** (format `trb_partner_…` or `tb_prt_…`) is used only for provisioning actions such as registration. Do not bundle it in the device app for heartbeat, identity, or sensing startup.

> The SDK passes your `external_id` to the backend, which already knows which screen+venue that box maps to (from registration). That is what makes the data attribute to the right location.

---

## Step 1 — Add the dependency

In **`settings.gradle.kts`** (or root `build.gradle`), add the canonical public
Trillboards Maven repository:
```kotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://maven.trillboards.com") }
    }
}
```
The repository is anonymous-read. No GitHub token or Trillboards API key belongs
in Gradle credentials.

In your **app module `build.gradle.kts`**:
```kotlin
dependencies {
    implementation("com.trillboards:agent-core:1.14.0")
    // Moonshine ASR runtime — enables on-device speech→structured output (FunctionGemma 270M).
    // agent-core ships ASR compileOnly; this supplies the runtime. Omit only if you don't want speech.
    implementation("com.trillboards.bundled:sherpa-onnx:1.12.26")
}
```

**Build floor (required):** `minSdk = 26`, Android Gradle Plugin `8.0+`, JDK 17. The AAR is ~180 MB (bundled on-device models). If your app is below these, bump them.

**Release candidates.** A new version is first published to the staging
repository, and it becomes the public `latest` only after that exact build passes
a 48 h soak on an Ember-class tablet. To build a candidate before then, add the
staging repository and pin the exact version:
```kotlin
maven { url = uri("https://maven.trillboards.com/staging") }
// app module: implementation("com.trillboards:agent-core:<candidate version>")
```
Staging has no `latest`, so a dynamic version (`1.+`) never resolves to a
candidate. A staged version never changes, and the public release is the same
bytes: what you tested as the candidate is what ships. The version directory's
`build-info.json` lists the SHA-256 of the AAR and the POM. Remove the staging
line once the version is public.

## Step 2 — Permissions + foreground service

In **`AndroidManifest.xml`**, declare (inside `<manifest>`):
```xml
<uses-permission android:name="android.permission.CAMERA" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" />
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
<uses-permission android:name="android.permission.BLUETOOTH_SCAN" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.BLUETOOTH_CONNECT" />
<uses-permission android:name="android.permission.NEARBY_WIFI_DEVICES" android:usesPermissionFlags="neverForLocation" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
```
Grant the runtime permissions (`CAMERA`, `RECORD_AUDIO`, `ACCESS_FINE_LOCATION`, `BLUETOOTH_SCAN`, and — on Android 13+ / API 33+ — `NEARBY_WIFI_DEVICES`) at app start (or via MDM auto-grant on managed fleets). `BLUETOOTH_SCAN` and `NEARBY_WIFI_DEVICES` are runtime-**dangerous**: declaring them (or letting the AAR merge them in) is not a grant, and skipping either request leaves that radio silently reporting nothing while the other looks healthy. WiFi scanning additionally needs `ACCESS_FINE_LOCATION` at **every** API level — on 33+ it is required alongside `NEARBY_WIFI_DEVICES`, because `WifiManager.startScan()`/`getScanResults()` are the carve-out `NEARBY_WIFI_DEVICES` does not cover — and the AAR caps its own declaration at `maxSdkVersion="30"`, so declare an uncapped one yourself on API 31+. The per-API-level `requestPermissions` snippet is in the [CTV Measurement SDK — Partner Integration Guide § Step 1b](https://api.trillboards.com/docs/integrations/ctv-measurement-partner-integration.md).

**Foreground service:** the SDK binds the camera to the app process lifecycle. If your screen app is **always in the foreground** (kiosk/always-on display), no extra work is needed. If you sense while the app is **backgrounded**, declare a foreground service with `foregroundServiceType="camera|microphone"` and call `startForeground()` before sensing — otherwise Android stops the camera in the background.

## Step 3 — Start the SDK

Call this once at app start (e.g. `Application.onCreate()` or your main Activity), passing **this box's `external_id`** as `deviceId`:

```kotlin
import com.trillboards.sdk.SensingSdkConfig
import com.trillboards.sdk.TrillboardsSensingSdk

TrillboardsSensingSdk.start(
    context = applicationContext,
    config = SensingSdkConfig(
        deviceId = "DD-H80F55"   // ← THIS box's external_id (the one you registered)
        // speech/ASR + on-device FunctionGemma 270M run by default (sherpa-onnx dep added in Step 1)
    )
)
```
That's the whole integration. The SDK resolves this box's screen from `deviceId`
(`check-screen`), handles any privileged sensing-channel credential internally,
opens the camera/mic, runs on-device AI, and emits attributed observations.
Heartbeat liveness and targeting-identity ingestion are unauthenticated after
registration. To stop: `TrillboardsSensingSdk.stop(applicationContext)`.

> **`deviceId` MUST equal the `external_id` you registered for this box.** That's the entire attribution contract. If you templatize the app across a fleet, inject each box's `external_id` at provisioning time (build config, MDM app-config, or a per-device file).

---

## Step 4 — Verify it worked (do this, don't skip)
1. Run the app on a real device with a camera in view of people (or yourself).
2. In **logcat**, confirm: `TrillboardsSensingSdk: Resolved screen binding: screenId=…` and `FrameCaptureManager: ... SENDING TO API ... screenId=<non-null>`.
3. In the **Trillboards Venue portal** (`/earner`), open that box's screen → the **Moments** card populates within a few minutes (scenes, demographics, custom chips). That is success.

## What you get (in the portal + via the partner API)
- **Moments / scenes** — Gemini scene descriptions per capture.
- **Demographics** — age range, gender, group composition (age/gender model downloads ~178 MB on first run; until then those fields are empty, everything else works).
- **Custom chips** — fitness archetype, dietary signal, attire, lifestyle, brands detected, ad-fit categories (IAB + Trillboards taxonomy).
- **Audio → structured insights** — on-device **FunctionGemma 270M** turns speech (via Moonshine ASR) into structured retail-conversation signals (brand mentions, purchase-journey stage, sentiment, objections…). Needs the sherpa-onnx dep (Step 1); see "On-device speech LLM" below.
- **Co-viewing / proximity (BLE + Wi-Fi)** — produced by the **co-installed Measurement SDK** (Step 5), not this SDK. The Sensing SDK is camera + audio.
- Same data is readable via the partner API audience/moments endpoints.

## Step 5 — Proximity graph: co-install the Measurement SDK (BLE/Wi-Fi)
The Sensing SDK is camera + audio. **Wi-Fi/Bluetooth proximity** (the co-viewing graph) is produced by the **CTV Measurement SDK**, which runs the scans on its **own scheduler** — so proximity never weighs down the camera/audio path. To capture the full sensor suite, co-install it with the **same `deviceId`** so both attribute to the same screen:
```kotlin
// app/build.gradle.kts (same GitHub Packages repo as agent-core, from Step 1):
dependencies {
    implementation("com.trillboards:ctv-measurement:1.3.2")
}
```
```kotlin
import com.trillboards.measurement.MeasurementConfig
import com.trillboards.measurement.TrillboardsMeasurement

TrillboardsMeasurement.initialize(
    applicationContext,
    MeasurementConfig.Builder(deviceId = "DD-H80F55").build()
)
TrillboardsMeasurement.setConsentStatus(true)
TrillboardsMeasurement.startScheduledScans()
```
This SDK also reports the box's hardware (incl. RAM) and, when the platform
exposes it, the real resettable GAID/AAID on its heartbeat. It never substitutes
the registered device or screen ID for a MAID. The hardware report is what lets
the backend serve the FunctionGemma 270M model to capable (≥ 2 GB) boxes.
**Camera-only?** Skip this step. **Full suite (proximity + on-device speech LLM)?**
Co-install it.

Both SDKs expose an `ExtendedIdentityProvider` for host-owned, exact targeting
identities. Supply an already-computed SHA-256 email digest as `hem_sha256` or a
current opaque UID2 advertising token as `uid2_token`. HEM is lowercased once
and never re-hashed; UID2 remains case-sensitive and should carry its expiry.
These values stay separate from MAID and leave the backend as OpenRTB
`user.eids`; MAID leaves as `device.ifa`.

## Step 6 — Report your own plays, trips and taps (optional, agent-core 1.22+)

Three calls tell Trillboards what YOUR app owns, so the audience the SDK measured
is attributed to it: the ads your app plays, your taxi meter, and what riders do
with the screen. They do nothing unless you call them.

```kotlin
import com.trillboards.sdk.HostInteractionType
import com.trillboards.sdk.TrillboardsSensingSdk

// An ad your app played. creativeRef is the content hash POST /v1/partner/creatives returned.
TrillboardsSensingSdk.reportPlay(
    playId = "play-7f3a",                       // your unique id for this play
    creativeRef = "sha256:6c4b8f3e2a1d7b90c5e42f18a3d6b7e90124fa5c83b16d0e7f294a5c81b3d6e1",
    completedAtEpochMs = System.currentTimeMillis(),
    durationSeconds = 15.0,
    impressionId = null,                        // ONLY for an ad Trillboards served (see below)
)

// The meter: number the changes of one trip 0, 1, 2...
TrillboardsSensingSdk.setTripState(tripId = "trip-9", eventSeq = 0, meterOn = true, stateAtEpochMs = startedAt)
TrillboardsSensingSdk.setTripState(
    tripId = "trip-9", eventSeq = 1, meterOn = false, stateAtEpochMs = endedAt,
    fareCents = 2450, tipCents = 400, paymentType = "card", passengerCount = 2, destination = "JFK T4",
)

// What a rider did: TAP, QR_SHOWN, QR_SCANNED or DWELL_PROMPT.
TrillboardsSensingSdk.reportInteraction("tap-1", HostInteractionType.TAP, tappedAt, creativeId = "cr-9", tMs = 8000)
```

From Java they are static methods with short overloads:
`TrillboardsSensingSdk.reportPlay("play-7f3a", creativeRef, System.currentTimeMillis());`,
`TrillboardsSensingSdk.setTripState("trip-9", 0L, true, startedAt);`,
`TrillboardsSensingSdk.reportInteraction("tap-1", HostInteractionType.TAP, tappedAt);`.

How they behave:
- **Each call returns at once and never throws.** `true` means the event was queued for delivery;
  `false` means it was refused as invalid, with the reason in logcat under `TrillboardsHostHooks`.
  Bounds: `playId` 1–256 characters, `tripId` and `interactionId` 1–128, `creativeRef` a
  `sha256:<64 hex>` content hash, `durationSeconds` 0–86,400, `eventSeq`, fares and `tMs` 0–4,294,967,295,
  `passengerCount` 0–255.
- **Delivery is in the background**, to `POST /v1/partner/device/<device>/{plays,trips,interactions}`
  with this device's own credential (never your partner API key). The screen is the device's
  binding; you never pass it.
- **Offline-safe.** Events are written to a queue on the device and sent once the device is
  online and bound to its screen, including after an app restart. Calls made before `start()`
  are held in memory (up to 256) and queued when `start()` runs. The queue keeps at most
  2,160 events, each for at most 72 hours; past either bound the oldest are dropped first.
- **Retries.** A network error, a 5xx, a 429 (honouring `Retry-After`), a 401 or a 404 keeps the
  event and retries with exponential backoff from 2 s to 5 minutes. A 400 or 403 drops it (the
  same event can never succeed; the reason is logged). A 409 means the server already received
  that request.
- **Idempotent.** Every retry resends the same body, and the server keeps one play per `playId`,
  one meter event per (`tripId`, `eventSeq`) and one interaction per `interactionId`. To retry
  your own call, reuse the id; for a new event, use a new id.
- **`impressionId` is only for ads Trillboards served** (for example through the Trillboards VAST
  tag): pass that ad's Trillboards impression id so the play is counted once. Leave it `null` for
  every ad your app sold or scheduled itself.

## Step 7 — Seatbelt reminders (optional, agent-core 1.24+)

The SDK tells your app when the rear riders are unbuckled while the cab moves, so your app
can show a reminder. Set a listener; nothing is delivered without one.

```kotlin
import com.trillboards.sdk.HostInteractionType
import com.trillboards.sdk.TrillboardsSensingSdk

TrillboardsSensingSdk.setSafetyEventListener { reminder ->
    showSeatbeltReminder(reminder.seatSide)            // your UI
    TrillboardsSensingSdk.reportInteraction(
        reminder.eventId, HostInteractionType.SEATBELT_REMINDER_SHOWN, System.currentTimeMillis(),
    )
}
```

From Java: `TrillboardsSensingSdk.setSafetyEventListener(reminder -> { ... });`. Pass `null` to
remove the listener.

How it behaves:
- **When a reminder fires.** Trillboards switches the seatbelt check and its reminders on per
  screen, from the server. A reminder fires once the rear riders have been unbuckled for 20 seconds
  while the cab moves, at most 3 times per trip and at least 5 minutes apart (server settings).
- **`SeatbeltReminder`** carries `tripId` (your id while a trip you opened with
  `setTripState(…, meterOn = true, …)` is open; otherwise the SDK's camera trip, `cab:<start epoch ms>`),
  `seatSide` (the rear seat, facing forward in the vehicle: `left`, `right`, `center`, `multiple` when
  riders on different sides are unbuckled, or `unknown`) and `eventId` (unique per reminder, starting `<tripId>:`).
- **Report each reminder you show**, with its `eventId` as the interaction id. A retry with the same
  id is recorded once. Report only reminders that were on screen: the reported count is how the
  reminder's effect is measured.
- **Trips.** Call `setTripState` (Step 6) with `meterOn = true` when a passenger boards and
  `meterOn = false` when the trip ends. Reminders then count per your trip; without it, the SDK
  finds trips from the camera. Keep a `tripId` to 112 characters, so the reminder's
  `eventId` (`<tripId>:` and up to 11 more) fits the 128-character interaction id.
- The callback runs on the main thread, before or after `start()`. An exception thrown in it is
  logged under `TrillboardsSafety` and ignored.
- `SeatbeltReminder` has a public constructor: to test your UI, call your listener with
  `SeatbeltReminder("trip-test", "left", "trip-test:1")`.

## On-device speech LLM (FunctionGemma 270M)
- ASR (Moonshine) runs by default once the sherpa-onnx dep (Step 1) is present; it transcribes **on-device**. From agent-core 1.21 the transcript text and its segment times are sent to Trillboards and stored; no audio recording leaves the box.
- The transcript feeds **FunctionGemma 270M** (271 MB `.litert-lm`, CPU-only, ~216 MB resident) which emits structured conversation insights. It **OTA-downloads** on first run when the device is known to have ≥ 2 GB RAM — which the co-installed Measurement SDK reports (Step 5). On a 3.5 GB box it runs comfortably.

## Performance notes (low-/mid-tier boxes, e.g. Snapdragon 695 / 3.5 GB)
- Expect ~3 fps sensing, ~175 MB native heap, stable — sufficient (the backend aggregates over 10s windows).
- The on-device **vision** VLM (8 GB+) stays **off** by design; the **audio** FunctionGemma 270M (~216 MB) runs on ≥ 2 GB boxes.

## Troubleshooting
- **Logcat shows `No screen bound to fingerprint yet`** → `deviceId` doesn't match a registered `external_id`. Verify the box is registered (Appendix A) and the `external_id` matches exactly.
- **Data in PG but `screen_mongo_id` null / not in the portal** → you're on an SDK older than `1.1.2`. Pin `1.1.2`.
- **App crashes on launch with `MobileAdsInitProvider` / "Missing application ID"** → you're on an SDK older than `1.1.2` (ads were decoupled in this line). Pin `1.1.2`.
- **No demographics** → the ~178 MB age/gender model is still downloading; everything else works meanwhile.
- **No audio/speech insights** → confirm the `sherpa-onnx` dep (Step 1) is present (logcat `hasSpeechModel=true`, ASR transcribing). FunctionGemma 270M also requires the device to report **≥ 2 GB RAM** — co-install the Measurement SDK (Step 5) so its heartbeat reports hardware; without a known RAM tier the model isn't served.
- **No proximity / co-viewing** → that's the Measurement SDK (Step 5), not this SDK. Confirm it's co-installed with the **same `deviceId`**.

---

## Appendix A — register a box (only if not already registered)
```bash
curl -X POST https://api.trillboards.com/v1/partner/device \
  -H "Authorization: Bearer trb_partner_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"device_id":"DD-H80F55","name":"Store #123 — Front Counter","location":"123 Main St, Dallas, TX"}'
```
The response binds the box to a screen+venue. Send the registration `device_id` and use that **same identifier** as `deviceId` in Step 3. The stored binding remains `external_id`. (Bulk: loop your CSV of boxes.)

## Done criteria (stop here when all true)
- [ ] App builds with `com.trillboards:agent-core:1.14.0` from the anonymous public Maven repository, minSdk 26 / AGP 8+ / JDK 17.
- [ ] Manifest has camera/mic/Wi-Fi/BLE perms (+ FGS if backgrounded); runtime perms granted.
- [ ] `TrillboardsSensingSdk.start(...)` is called once with `deviceId = this box's external_id`.
- [ ] No Partner API key is embedded in the runtime app; registered-device heartbeat and identity POSTs succeed without one.
- [ ] Logcat shows `Resolved screen binding: screenId=…` and POSTs with a non-null `screenId`.
- [ ] The box's screen shows Moments/chips in the Venue portal.
- [ ] **(Speech)** `sherpa-onnx` dep present → logcat shows ASR transcribing + FunctionGemma 270M loaded after OTA; audio insight chips appear.
- [ ] **(Proximity)** Measurement SDK (Step 5) co-installed with the **same `deviceId`** → BLE/Wi-Fi co-viewing appears for the screen.

---

# CTV Measurement SDK quickstart
# Source: https://api.trillboards.com/docs/guides/integrations/ctv-measurement-quickstart.md

# Trillboards CTV Measurement SDK Quickstart

Use the Android SDK for native Android TV, Fire TV, and tablet players. It is
built from `agent-core-lite`, the same heartbeat, identity, and proximity code
used by Trillboards-managed players.

The Android heartbeat is deliberately simple:

```text
POST /openrtb/v1/heartbeat
```

Register the device once, then initialize the SDK with that same stable device
identifier. Heartbeat liveness, MAID, HEM, and UID2 ingestion do not require a
Partner API key. The registered device/screen binding is the trust boundary.

The separate `@trillboards/ctv-measurement` web package still accepts a Partner
API key because it also calls authenticated `/v2/sdk/*` enrichment and
attribution endpoints.

## 1. Register each device

Registration is an authenticated provisioning action:

```bash
curl -X POST https://api.trillboards.com/v1/partner/device \
  -H "Authorization: Bearer trb_partner_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "device_id": "store-123-player-1",
    "name": "Store 123 front screen"
  }'
```

Keep the registration `device_id` stable for the physical player; the stored
binding remains `external_id`. The app bundle and screen
binding belong to that registered device; do not substitute a screen UUID for a
platform advertising identifier.

## 2. Install the Android SDK

```kotlin
dependencyResolutionManagement {
  repositories {
    google()
    mavenCentral()
    maven { url = uri("https://maven.trillboards.com") }
  }
}
```

```kotlin
dependencies {
  implementation("com.trillboards:ctv-measurement:1.3.2")
}
```

Requires Android API 24+ and JDK 17 for the build.

## 3. Initialize with the registered device ID

```kotlin
import com.trillboards.measurement.MeasurementConfig
import com.trillboards.measurement.TrillboardsMeasurement

val config = MeasurementConfig.Builder(
  deviceId = "store-123-player-1",
)
  .scanIntervalMs(30_000)
  .build()

TrillboardsMeasurement.initialize(applicationContext, config)
TrillboardsMeasurement.setConsentStatus(true)
TrillboardsMeasurement.startScheduledScans()
```

No API key is needed for this heartbeat flow. The legacy
`MeasurementConfig.Builder(apiKey, deviceId)` overload remains available for
apps that also call authenticated Partner API operations.

The AAR declares its own networking, Bluetooth, Wi-Fi, and Android advertising
ID permissions. Request the runtime Bluetooth/Wi-Fi permissions appropriate to
the device OS.

## 4. Send targeting identities

The built-in collector sends the actual platform advertising identifier
(GAID/AAID) when the platform exposes one. It never fabricates a screen ID as
`device.ifa`.

For audience IDs owned by the host, provide typed extended identities:

```kotlin
import com.trillboards.ctv.core.identity.ExtendedIdentity
import com.trillboards.ctv.core.identity.ExtendedIdentityProvider

val identityProvider = ExtendedIdentityProvider {
  listOf(
    ExtendedIdentity.hemSha256(
      digest = existingSha256EmailDigest,
      source = "your-identity-domain.example",
      observedAt = observedAtIso8601,
    ),
    ExtendedIdentity.uid2Token(
      token = currentUid2AdvertisingToken,
      source = "uidapi.com",
      observedAt = observedAtIso8601,
      expiresAt = uid2ExpiryIso8601,
    ),
  )
}

val config = MeasurementConfig.Builder("store-123-player-1")
  .extendedIdentityProvider(identityProvider)
  .build()
```

Value semantics are exact:

- MAID/GAID is persisted raw and emitted as OpenRTB `device.ifa`.
- `hem_sha256` must already be one SHA-256 digest. The server lowercases the
  hexadecimal representation once and does not hash it again.
- `uid2_token` is opaque and case-sensitive. Send it exactly as issued, with
  its expiration time so the host can refresh it.
- HEM and UID2 are emitted under OpenRTB 2.6 `user.eids`.

## 5. Verify ingress and egress

Heartbeat success proves only that the registered-device contract accepted the
request. For revenue readiness, verify the full chain:

1. PostgreSQL `earner_screen_devices` has the raw MAID state.
2. PostgreSQL `device_extended_identities` has the exact active HEM/UID2 rows.
3. Redis `dtwin:{screenId}` contains the same active identity projection.
4. A real outbound OpenRTB request contains `device.ifa` and/or `user.eids`.
5. A buyer response produces a VAST render and a canonical
   `completed_impressions` row.

Never use request volume or a VAST tracker alone as revenue proof. Canonical
revenue is a completed impression tied to the actual demand source and creative.

## Endpoint authentication

| Endpoint | Authentication |
|---|---|
| `POST /v1/partner/device` | Partner API key; provisioning |
| `POST /v1/partner/device/{deviceId}/heartbeat` | None after device registration |
| `POST /openrtb/v1/heartbeat` | None after device/screen registration |
| `GET /v1/partner/device/{deviceId}/heartbeat` | Partner API key; readback |
| `/v2/sdk/*` enrichment and attribution | Partner API key |

Full OpenAPI:
<https://api.trillboards.com/docs/openapi/partner-api.yaml>.

Deep integration guide:
<https://api.trillboards.com/docs/integrations/ctv-measurement-partner-integration.md>.

---

# CTV Measurement SDK — full partner integration
# Source: https://api.trillboards.com/docs/guides/integrations/ctv-measurement-partner-integration.md

# CTV Measurement SDK — Partner Integration Guide

For CTV publishers integrating `@trillboards/ctv-measurement` (JavaScript) and
`trillboards-measurement-sdk` (Android AAR) into their Android TV / Fire TV apps.

## What you get

- **BLE co-viewing measurement** — Bluetooth proximity scanning. The Android
  library sends each nearby device's MAC address to Trillboards over TLS, and
  the SDK returns a normalized 0-1 proximity confidence score derived from RSSI.
- **Device fingerprinting** — Canvas, WebGL, and audio fingerprints combined into
  a stable per-device SHA-256 hash. No GAID dependency.
- **Census demographic enrichment** — IAB income/age segments and education tier
  derived from US Census ACS 2023 data at geohash-6 resolution. Server-side
  IP-based lookup.
- **CTV viewability** — MRC DOOH-compliant verdict (95% duration threshold) from
  IMA SDK lifecycle events.
- **QR attribution** — physical-to-digital attribution via IP co-location between
  the CTV screen and the mobile device that scanned the QR.
- **Connection quality signals** — `effectiveType`, `downlinkMbps`, `rttMs` from
  the Network Information API.
- **Frequency & reach** — server-side per-household-per-day counters and cached
  reach metrics returned in every impression response.
- **Buyer-addressable identity** — built-in MAID collection plus typed,
  exact HEM and UID2 heartbeat envelopes projected into OpenRTB.

## Getting an API key

The native Android heartbeat does **not** require an API key after the device
has been registered. Initialize it with the same stable device ID used during
registration; that device/screen binding is the heartbeat trust boundary.

The web SDK's `/v2/sdk/*` enrichment and attribution endpoints authenticate with your Trillboards
**Partner API key** (`trb_partner_*` / `tb_prt_*`) — the same key you use for
the rest of the Partner API. Register once via the self-serve
`POST /v1/partner/register` flow (or the web form at
[trillboards.com/partners/get-started](https://trillboards.com/partners/get-started))
and the key you get back already carries the `sdk:*` scope
(`sdk:enrich`, `sdk:qr`, `sdk:impression`), so it authenticates against
`/v2/sdk/*` immediately — no separate CTV key, no email round-trip to unlock
scopes.

See the [Quickstart](https://api.trillboards.com/docs/integrations/ctv-measurement-quickstart.md)
for the unauthenticated registered-device heartbeat contract.

## Architecture

```
┌──────────────────────────────────────────────┐
│  CTV Device (Fire TV / Android TV)           │
│                                              │
│  ┌────────────────────────┐                  │
│  │  Publisher Android App │                  │
│  │                        │                  │
│  │  ┌──────────────────┐  │                  │
│  │  │ trillboards-     │  │ ◄─── BLE scans   │
│  │  │ measurement-sdk  │  │                  │
│  │  │ (AAR, ~44KB)     │  │                  │
│  │  └────────┬─────────┘  │                  │
│  │           │  bridge    │                  │
│  │           ▼            │                  │
│  │  ┌──────────────────┐  │                  │
│  │  │     WebView      │  │                  │
│  │  │                  │  │                  │
│  │  │ @trillboards/    │  │ ◄── fingerprint  │
│  │  │ ctv-measurement  │  │ ◄── viewability  │
│  │  │ (JS, ~12KB IIFE) │──┼─►  POST /v2/sdk/*│
│  │  └──────────────────┘  │                  │
│  └────────────────────────┘                  │
└──────────────────────────────────────────────┘
                  │
                  ▼
       https://api.trillboards.com
```

The Android library scans BLE on the native side and pushes snapshots into the
WebView via `window.dispatchEvent(new CustomEvent('trillboards:measurement'))`.
The JS SDK listens for that event, combines BLE data with browser-side
fingerprint/viewability/connection signals, calls `/v2/sdk/enrich` for census
data, and sends the unified payload to `/v2/sdk/impression`.

## Step 1 — Add the Android library

In your CTV app's `build.gradle.kts`:

```kotlin
dependencies {
    implementation("com.trillboards:ctv-measurement:1.3.2")
}
```

The library declares its own permissions in `AndroidManifest.xml`, and manifest
merge pulls them into your app automatically — you do not copy them:

- `BLUETOOTH_SCAN` (Android 12+) with `usesPermissionFlags="neverForLocation"`
  — BLE scanning
- `BLUETOOTH_CONNECT` (Android 12+) — optional GATT device-info enrichment
- `ACCESS_FINE_LOCATION` (`maxSdkVersion="30"`) — the pre-Android-12 BLE gate.
  The cap is why WiFi scanning needs a manifest override from **you** on API 31+
  — see Step 1b
- `NEARBY_WIFI_DEVICES` (Android 13+) with `usesPermissionFlags="neverForLocation"`
  — required for WiFi scanning on API 33+, but **not sufficient on its own**
  (Step 1b)
- `ACCESS_WIFI_STATE`, `CHANGE_WIFI_STATE`, `CHANGE_WIFI_MULTICAST_STATE`,
  `INTERNET`, `ACCESS_NETWORK_STATE`, `AD_ID` — normal permissions, granted at
  install, nothing to request

## Step 1b — Runtime permissions: request BOTH, or you get half the signals

**Manifest merge is not a grant.** `BLUETOOTH_SCAN`, `NEARBY_WIFI_DEVICES` and
`ACCESS_FINE_LOCATION` are all runtime-**dangerous** permissions, so your host
app must request each one it needs at runtime. Skipping a request fails
silently: the radio you did grant keeps reporting normally and the other
returns nothing, forever. It does not look like a broken integration —
observations are arriving, just half of them. We see both halves of this on
live partner fleets today, which is why this section exists.

What each radio needs granted, by the API level of the **device**:

| Android version | BLE scan needs | WiFi scan needs |
|---|---|---|
| API 33+ (13+) | `BLUETOOTH_SCAN` | `NEARBY_WIFI_DEVICES` **and** `ACCESS_FINE_LOCATION` † |
| API 31–32 (12 / 12L) | `BLUETOOTH_SCAN` | `ACCESS_FINE_LOCATION` † |
| API 30 and below (Android 11 and older) | `ACCESS_FINE_LOCATION` | `ACCESS_FINE_LOCATION` |

**WiFi is the asymmetric one: on API 33+ it takes both permissions, because two
different gates have to open.**

1. *Our* gate — `WifiScanCollector` checks `NEARBY_WIFI_DEVICES` on API 33+ and
   `ACCESS_FINE_LOCATION` below it. Without the right one it logs
   `Missing WiFi scan permission — skipping` and never touches the radio.
2. *Android's* gate — the SDK collects via `WifiManager.startScan()` /
   `getScanResults()`, and those two methods still require
   `ACCESS_FINE_LOCATION` **at every API level, including 33+**. This is the
   documented carve-out in [Request permission to access nearby Wi-Fi
   devices](https://developer.android.com/develop/connectivity/wifi/wifi-permissions#previous-versions):
   *"Several Wi-Fi APIs require the `ACCESS_FINE_LOCATION` permission, even when
   your app targets Android 13 or higher."* `NEARBY_WIFI_DEVICES` replaces
   location for Wi-Fi Aware, Wi-Fi Direct, RTT and local-only hotspot — **not
   for scanning**, which is why holding it alone is not enough.

Hold only `NEARBY_WIFI_DEVICES` on API 33+ and you land between the two gates:
ours opens, Android's does not, and `getScanResults()` throws a
`SecurityException` the collector catches as `WiFi scan failed`. That reads as a
working integration reporting zero WiFi forever.

† Both rows need an uncapped `ACCESS_FINE_LOCATION` from **your** manifest,
because the AAR caps its own at `maxSdkVersion="30"` on purpose — an uncapped
location declaration would force a Google Play location-permission declaration
on every radio-only integration. So on **any** device at API 31 or above, if you
want WiFi scanning, add the uncapped declaration to your manifest (your app's
declaration wins the merge) and request it at runtime:

```xml
<!-- your <manifest> element needs xmlns:tools="http://schemas.android.com/tools" -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"
    tools:node="replace" />
```

Request both radios from your Activity before (or any time after) starting
scans — the SDK re-checks the grant on **every** scan, so a grant that lands
late is picked up on the next scan interval with no re-initialization:

```kotlin
import android.Manifest
import android.content.pm.PackageManager
import android.os.Build

private const val REQ_TRILLBOARDS_MEASUREMENT = 4711

/** Everything the measurement SDK needs a runtime grant for, per API level. */
private fun trillboardsMeasurementPermissions(): Array<String> {
    val perms = mutableListOf<String>()
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
        // API 31+ — BLE scanning. Declared neverForLocation, but still
        // dangerous-tier: no runtime grant means zero BLE observations.
        perms.add(Manifest.permission.BLUETOOTH_SCAN)
    }
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
        // API 33+ — WiFi scanning. This is the one that gets forgotten.
        perms.add(Manifest.permission.NEARBY_WIFI_DEVICES)
    }
    // ACCESS_FINE_LOCATION at EVERY level, and note this is not an `else`:
    //  - API 33+  — NEARBY_WIFI_DEVICES opens our gate, but startScan()/
    //               getScanResults() still require location. Both, or no WiFi.
    //  - API 31-32 — the WiFi scan gate.
    //  - API <=30  — the WiFi *and* BLE scan gate.
    // On API 31+ this ALSO needs the uncapped manifest override above, or the
    // request silently no-ops against the AAR's maxSdkVersion="30" declaration.
    perms.add(Manifest.permission.ACCESS_FINE_LOCATION)
    return perms.toTypedArray()
}

// In your Activity (e.g. onCreate, after your CMP returns granted=true):
val needed = trillboardsMeasurementPermissions()
    .filter { checkSelfPermission(it) != PackageManager.PERMISSION_GRANTED }
    .toTypedArray()
if (needed.isNotEmpty()) {
    requestPermissions(needed, REQ_TRILLBOARDS_MEASUREMENT)
}
```

On AndroidX you can use
`registerForActivityResult(ActivityResultContracts.RequestMultiplePermissions())`
instead — the permission list is identical.

### Verify it worked

Check both radios independently. **A lopsided result is a missing runtime
grant, not throttling and not a scan-interval problem** — the OS throttles WiFi
scans to a slower cadence, but throttling never produces a permanent zero on
one radio while the other reports normally.

```
adb logcat -s BleBeaconScanner:W WifiScanCollector:D
```

- `Missing BLUETOOTH_SCAN permission — skipping (no perm grant)` → you never
  requested `BLUETOOTH_SCAN` (or the user denied it).
- `Missing WiFi scan permission — skipping` → you never requested
  `NEARBY_WIFI_DEVICES` on API 33+ (or `ACCESS_FINE_LOCATION` below it).
- `WiFi scan failed: … SecurityException …` → **the two-gate miss.** On API 33+
  this is `NEARBY_WIFI_DEVICES` granted without `ACCESS_FINE_LOCATION`: our
  check passed, so the scan was attempted, and Android rejected it. Add the
  uncapped `ACCESS_FINE_LOCATION` declaration **and** request it at runtime. On
  API 31–32 the same line means the uncapped declaration is missing, so your
  runtime request had nothing to grant.

Server-side, the same tell shows up as a screen reporting a healthy stream of
BLE observations with zero WiFi observations (or the reverse) across every day
it has been live. If you see that on your fleet, fix the runtime request — no
backend change will recover the missing radio.

## Step 2 — Initialize the Android library

In your `Application.onCreate()` or main `Activity.onCreate()`:

```kotlin
import com.trillboards.measurement.TrillboardsMeasurement
import com.trillboards.measurement.MeasurementConfig

// Initialize once per app process
TrillboardsMeasurement.initialize(
    applicationContext,
    MeasurementConfig.Builder("your-registered-device-id")
        .scanIntervalMs(30_000)   // 30s between scans (default)
        .scanDurationMs(15_000)   // 15s scan window (default)
        .debugLogging(false)
        .build()
)

// After your CMP returns granted=true
TrillboardsMeasurement.setConsentStatus(true)

// Start periodic BLE scans
TrillboardsMeasurement.startScheduledScans()
```

**Critical**: `setConsentStatus(true)` must be called AFTER obtaining GDPR/CCPA
consent. The default consent state is `false` and `scan()` /
`startScheduledScans()` are no-ops until consent is granted. The library
caches no data and emits no events while consent is denied.

## Step 3 — Attach the bridge to your WebView

Before loading your ad creative URL:

```kotlin
val webView = findViewById<WebView>(R.id.ad_webview)
webView.settings.javaScriptEnabled = true

// Attach BEFORE loadUrl() so the JS bridge is available on first script execution
TrillboardsMeasurement.attachToWebView(webView)

webView.loadUrl("https://your-ad-creative.example.com")
```

The library exposes `window.TrillboardsMeasurement.getSnapshot()` (pull mode)
and dispatches `window.dispatchEvent(new CustomEvent('trillboards:measurement', { detail: ... }))`
on each scan (push mode). The JS SDK handles both automatically.

## Step 4 — Add the JavaScript SDK to your ad creative

### Option A: npm

```bash
npm install @trillboards/ctv-measurement
```

```typescript
import { CtvMeasurement } from '@trillboards/ctv-measurement';

const sdk = await CtvMeasurement.create({
  apiKey: 'trb_partner_your_api_key_here',
  screenId: 'screen-123',  // your internal screen identifier
  debug: false,
});

// After your CMP returns granted=true
sdk.setConsentStatus(true);
```

### Option B: `<script>` tag (IIFE bundle)

```html
<script src="https://cdn.trillboards.com/sdk/trillboards-ctv-measurement.global.js"></script>
<script>
  TrillboardsCtvMeasurement.create({
    apiKey: 'trb_partner_your_api_key_here',
    screenId: 'screen-123',
  }).then(sdk => {
    sdk.setConsentStatus(true);
    // ... use sdk
  });
</script>
```

The IIFE bundle is ~12 KB minified, zero runtime dependencies.

## Step 5 — Track ad lifecycle events

Hook the SDK into your IMA SDK / VAST player events:

```typescript
adsManager.addEventListener(google.ima.AdEvent.Type.IMPRESSION, () => {
  sdk.trackAdEvent('impression', {
    adId: currentAd.getAdId(),
    placementId: 'preroll-1',
    scheduledDurationMs: currentAd.getDuration() * 1000,
  });
});

adsManager.addEventListener(google.ima.AdEvent.Type.STARTED, () => {
  sdk.trackAdEvent('start', { adId, placementId: 'preroll-1' });
});

adsManager.addEventListener(google.ima.AdEvent.Type.FIRST_QUARTILE, () => {
  sdk.trackAdEvent('firstQuartile', { adId, placementId: 'preroll-1' });
});

adsManager.addEventListener(google.ima.AdEvent.Type.MIDPOINT, () => {
  sdk.trackAdEvent('midpoint', { adId, placementId: 'preroll-1' });
});

adsManager.addEventListener(google.ima.AdEvent.Type.THIRD_QUARTILE, () => {
  sdk.trackAdEvent('thirdQuartile', { adId, placementId: 'preroll-1' });
});

adsManager.addEventListener(google.ima.AdEvent.Type.COMPLETE, () => {
  sdk.trackAdEvent('complete', {
    adId,
    placementId: 'preroll-1',
    actualDurationMs: currentAd.getDuration() * 1000,
  });
});
```

## Step 6 — Measure and ingest the impression

After the ad completes (or at any point you want to record the impression):

```typescript
const payload = await sdk.measure();
// {
//   schema_version: '0.1',
//   sdk_version: '0.1.0',
//   sessionId: 'uuid',
//   impressionId: 'uuid',
//   timestamp: '2026-04-07T...',
//   bleDeviceCount: 3,
//   bleProximityConfidence: 0.78,
//   bleTopDeviceRssi: -55,
//   householdId: 'hashed-ip',
//   deviceFingerprint: 'sha256-hex',
//   canvasHash: 'sha256-hex',
//   webglRenderer: 'ANGLE...',
//   webglVendor: 'Google Inc.',
//   audioSampleRate: 48000,
//   iabIncomeSegmentId: '1002',
//   iabIncomeSegmentName: 'Upper-Middle Income ($100-150k)',
//   iabAgeSegmentId: '2003',
//   iabAgeSegmentName: 'Age 35-44',
//   educationTier: 'bachelors_plus',
//   connectionType: 'residential',
//   effectiveType: '4g',
//   downlinkMbps: 50.0,
//   rttMs: 25,
//   viewable: true,
//   viewabilityReason: 'ctv_full_completion',
//   completionRatio: 1.0,
//   imaImpressionConfirmed: true,
//   qrScanId: null,
//   qrBeaconSent: false
// }

// Send the payload to /v2/sdk/impression
const res = await fetch('https://api.trillboards.com/v2/sdk/impression', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'trb_partner_your_api_key_here',
  },
  body: JSON.stringify(payload),
});
const result = await res.json();
// {
//   received: true,
//   impressionId: 'uuid',
//   givtPassed: true,
//   frequency: 3,           // 3rd time this household has seen this ad today
//   householdReach: 1247,    // distinct households for this ad (cached, 5min TTL)
//   publisherReach: 15832    // distinct households across all your ads
// }
```

## QR attribution flow

To enable physical-to-digital attribution, render a QR code in your ad creative:

```typescript
// Generate a tracking URL pointing at your destination page
const qrUrl = sdk.getQrTrackingUrl(
  'https://shop.example.com/landing',
  'ad-1',
  'placement-1'
);
// => https://shop.example.com/landing?tb_sid=<scanId>&tb_aid=ad-1&tb_pid=placement-1

// Render the QR with your library of choice (e.g. qrcode-svg, qr.js)
renderQrCode(qrUrl, document.getElementById('qr-container'));
```

When a mobile user scans the QR, they land on your destination page. Your
landing page needs a small beacon script that:

1. Reads the `tb_sid`, `tb_aid`, `tb_pid` query parameters
2. Calls `POST /v2/sdk/qr/scan` to record the scan
3. Calls `POST /v2/sdk/qr/beacon` with browser fingerprint signals

The Trillboards backend then performs IP co-location matching: if the mobile
beacon's IP hash matches the CTV screen's recently observed IP hash, an
identity graph edge is created and `ipMatch: true` is returned.

The next `sdk.measure()` call after `getQrTrackingUrl()` automatically includes
the `tb_sid` value as `qrScanId` in the payload, so the impression can be
correlated with the scan event server-side.

## GDPR / CCPA consent

The SDK is **consent-first by default**:

- `setConsentStatus(false)` (the default) → `measure()` returns a zeroed payload,
  `trackAdEvent()` is a no-op, the BLE bridge listener stops storing snapshots,
  and any previously cached `lastPayload` is immediately zeroed (no privacy leak
  via `getPayload()`).
- `setConsentStatus(true)` → measurement resumes.

```typescript
// User denies consent
sdk.setConsentStatus(false);
// All subsequent measure() calls return zeroed payloads

// User grants consent
sdk.setConsentStatus(true);
// Measurement resumes
```

## Cleanup

```typescript
// On page unload or component unmount
sdk.destroy();
```

```kotlin
// On Application terminate (rare — usually you want the SDK to live
// for the entire app lifetime)
TrillboardsMeasurement.shutdown()
```

## Privacy & compliance

- **No camera, no microphone** — the SDK is fundamentally physical/network-based.
- **No GAID dependency** — works on devices with Limit Ad Tracking enabled.
- **Radio identifiers and IP addresses** — the Android library sends each
  nearby device's BLE MAC address and WiFi BSSID to Trillboards over TLS, and
  Trillboards stores them as received and as keyed hashes. Impression records
  store the request IP as an HMAC-SHA256 hash; a QR scan stores the scanning
  phone's IP address, and a phone whose IP matches the screen's is linked to
  that screen in the identity graph.
- **Location** — the heartbeat response turns the Android library's GPS
  capture on for every fleet by default (`locationEnabled: true`) unless the
  app sets `allowRemoteConfig(false)`. Capture runs wherever the app holds the
  location permission, and Trillboards stores the screen's GPS positions as a
  trail.
- **Census data is fully auditable** — IAB segments derive deterministically
  from US Census ACS 2023 block-group data, not from probabilistic modeling.
- **Consent gating is enforced in code, not policy** — when consent is `false`,
  the SDK is provably inert (verified by 110 unit tests + 60 Android unit tests).

## Reference

- **OpenAPI spec**: `trillboard-api/docs/openapi/ctv-measurement-api.yaml`
- **JavaScript SDK source**: `trillboards-ctv-measurement/`
- **Android library source**: `trillboard-ctv/trillboards-measurement-sdk/`
- **Server route source**: `trillboard-api/routes/v2/sdk.js`
- **Migration**: `trillboard-api/postgres/migrations/20260407014944_create_sdk_impressions.sql`
- **Publish workflow**: `.github/workflows/publish-ctv-measurement.yml`

## Support

- Email: developers@trillboards.com

---

# OpenRTB 2.6 Trillboards extensions
# Source: https://api.trillboards.com/docs/guides/openrtb-extensions.md

# Trillboards OpenRTB 2.6 Extension Schema Reference

`version 2026-03-v1`


Schema reference for Trillboards' proprietary OpenRTB 2.6 bid request extensions.
This is NOT a bid endpoint specification — it documents the SIGNALS injected
into every bid request sent to DSPs so engineers can build bidding algorithms
that leverage Trillboards' unique audience intelligence.

## How to Use This Document

When Trillboards sends a bid request to your DSP, it includes standard OpenRTB 2.6
fields plus the proprietary extensions documented here. Your bidding algorithm can
use these signals to bid higher on high-value inventory.

## Extension Namespaces

| Namespace | What It Contains | Freshness |
|-----------|-----------------|-----------|
| `ext.trillboards` | Real-time audience signals from FEIN edge AI | 10-30 seconds |
| `ext.trb.vas` | Verified Attention Seconds (historical quality) | 7-day rolling |
| `ext.trb.intent` | Purchase intent from speech analysis | 10-30 seconds |
| `ext.trb.weather` | Contextual weather conditions | 60-minute cache |
| `ext.trb.foot_traffic` | Venue occupancy and traffic | 10-30 seconds |
| `ext.trillboards_contract` | Signal quality assurance | Per-request |
| `user.data[]` | IAB Audience Taxonomy 1.1 segments + seller-defined | 10-30 seconds |

## Signal Sources

- **FEIN Edge AI**: On-device ML Kit (face detection, gaze tracking) + YAMNet TFLite (audio classification) on the tablet, which sends Trillboards a record for each detected person and sends selected camera frames to a cloud model.
- **VAS Engine**: Verified Attention Seconds computed from historical FEIN measurements, stored in PostgreSQL attention_ledger.
- **Intent Graph**: Speech-derived purchase intent from YAMNet audio scene classification + keyword detection on the tablet. The tablet also sends Trillboards the speech transcript, which a cloud model reads for purchase intent and brands mentioned.
- **Weather Service**: WeatherAPI.com data cached in Redis with 60-minute TTL.
- **Census ACS**: US Census American Community Survey neighborhood demographics by geohash.

## Data behind the signals

- Bid requests carry the screen's IP address, its location (its live GPS position where the screen reports one) and its live audience measurements.
- The tablet keeps a record for each person its camera detects: estimated age range, gender, dominant emotion, dwell time and the time spent looking at the screen. On tablets running the full sensing profile it also computes a face-identity template, which Trillboards uses to recognise the same person across screens and days.
- Selected camera frames go to a cloud model (Google Vertex AI) that estimates ethnicity, age band, gender, social composition, purchase-intent stage, activity, attire, carried items, lifestyle segments and mood. Trillboards keeps those frames for 400 days; the frames captured between 5 May and 21 June 2026 are kept as a model-evaluation set with no scheduled deletion.
- Audio: the tablet classifies ambient sound and transcribes speech on the device, and Trillboards stores the transcript. No audio recording is stored or transmitted.
- Radio: the tablet sends Trillboards the Bluetooth, Wi-Fi and local-network identifiers nearby phones broadcast. Trillboards stores them and links device keys to the person seen with them and to mobile advertising IDs.
- Trillboards sells and shares this audience measurement and location data with its data partners, including 375ai and Intuizi. Each category of data partner and what it receives: https://trillboards.com/legal/data-partners



---

## Schemas

30 schemas. 
Every one is derived from `docs/openapi/openrtb-extensions.yaml` at request time.


[`AudienceAttentionPrediction`](#audienceattentionprediction) · [`AudienceSocialAttention`](#audiencesocialattention) · [`BidRequestExt`](#bidrequestext) · [`CompletedImpressions`](#completedimpressions) · [`ContractExt`](#contractext) · [`DOOHBidRequest`](#doohbidrequest) · [`DOOHObject`](#doohobject) · [`DemandPartners`](#demandpartners) · [`Device`](#device) · [`EarnerScreens`](#earnerscreens) · [`EventExt`](#eventext) · [`FootTrafficExt`](#foottrafficext) · [`IABSegmentReference`](#iabsegmentreference) · [`Impression`](#impression) · [`IntentExt`](#intentext) · [`OpenrtbRevenueScreenHourly`](#openrtbrevenuescreenhourly) · [`PartnerReconciliationReports`](#partnerreconciliationreports) · [`PartnerVariants`](#partnervariants) · [`PartnerZoneCpmDaily`](#partnerzonecpmdaily) · [`Regs`](#regs) · [`Segment`](#segment) · [`SellerDefinedSegmentReference`](#sellerdefinedsegmentreference) · [`Source`](#source) · [`TrbNamespace`](#trbnamespace) · [`TrillboardsAudienceExt`](#trillboardsaudienceext) · [`User`](#user) · [`UserData`](#userdata) · [`VASExt`](#vasext) · [`VenueExt`](#venueext) · [`WeatherExt`](#weatherext)


### AudienceAttentionPrediction


Backend-derived predictive attention signal + buyer-grade attentive-seconds. 1:1 with audience_metrics. Never null by contract; placeholder on row 1.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `predicted_attention_next_30s` | `string` — one of `high`, `medium`, `low`, `none` | yes | predicted_attention_next_30s enum {high,medium,low,none}. 'none' is below 'low'; fires when rolling history converges to zero or on a trend down from 'low'. |
| `predicted_disengagement_imminent` | `boolean` | yes | predicted_disengagement_imminent needs elevated dwell AND a falling trend, so it is unreachable whenever the history vector is empty. A 0% fire rate is a HISTORY-PLUMBING alarm, not a quiet fleet. |
| `prediction_evidence` | `string` | yes |  |
| `attentive_seconds_observed` | `number` | yes | attentive_seconds_observed = SUM(per_face[].gaze_seconds >= 1.0), OpenOOH 2024 4.2. NEVER NULL by DDL, so 0.000 means 'no viewer met threshold' ONLY when per_face_observations[] was present. NUMERIC(6,3). |
| `attentive_face_count` | `integer` | yes | attentive_face_count SMALLINT: distinct viewers meeting the >=1s threshold; the buyer-side CPMA denominator. NEVER NULL. |
| `attentive_seconds_predicted_15s` | `number` | yes | attentive_seconds_predicted_15s: expected next-15s attentive seconds from per-screen history x attention-weight; bootstrap = linear extrapolation. No global tau. NUMERIC(6,3). |
| `next_state_attention_forecast` | `number`, nullable |  |  |
| `next_state_confidence` | `number`, nullable |  |  |
| `next_state_method` | `string`, nullable |  |  |
| `next_state_horizon_minutes` | `integer`, nullable |  |  |
| `next_state_sample_size` | `integer`, nullable |  |  |
| `next_state_forecast_at` | `string`, nullable |  |  |
| `next_state_attention_realized` | `number`, nullable |  |  |
| `next_state_abs_error` | `number`, nullable |  |  |
| `next_state_graded_at` | `string`, nullable |  |  |
| `next_state_persist_abs_error` | `number`, nullable |  |  |
| `next_state_xscreen_abs_error` | `number`, nullable |  |  |
| `next_state_xscreen_sample_size` | `integer`, nullable |  |  |
| `next_state_xscreen_method` | `string`, nullable |  |  |
| `next_state_xsv_abs_error` | `number`, nullable |  |  |
| `next_state_xsv_sample_size` | `integer`, nullable |  |  |


### AudienceSocialAttention


Buyer-grade social amplification signal (5 typed columns). Cloud Vertex Gemini producer. 1 row per audience observation when cascade is observable.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `social_amplification_factor` | `number` | yes | NUMERIC(4,3). |
| `cascade_depth` | `integer` | yes |  |
| `viral_attention_score` | `number` | yes | viral_attention_score is the headline number Viant/T-Vision license. Composite of social_amplification_factor × cascade_depth × emotional engagement. NUMERIC(4,3). |
| `primary_attention_anchor_face_index` | `integer`, nullable |  | All 5 columns NOT NULL except primary_attention_anchor_face_index (only legit NULL: no anchor or solo scene). |
| `amplification_evidence` | `string` | yes |  |
| `data_projection_version` | `integer` | yes |  |
| `data_projection_xid` | `string` | yes |  |


### BidRequestExt


Top-level bid request extensions.

## ⚠️ Both Trillboards namespaces are STRIPPED on curated (registered-audience) deals

When a bid request is served under a curation plan with
`registeredAudienceOnly` — the shape behind our curated PMP / registered
audience deals — the server **deletes `ext.trillboards` and `ext.trb`
outright** before the request leaves us
(`services/programmatic/bidstreamSignalCuration.js`). If `ext` is left with
no other keys, `ext` itself is removed.

This is deliberate: on a curated deal the audience is carried by the
registered segment in `user.data`, and the raw sensing signals are withheld.

**The consequence for a bidder is the trap worth stating plainly:** every
signal described on this page disappears on exactly the deals we most want
you buying. A bidder whose valuation depends on `ext.trb.vas`,
`ext.trillboards.attention_score`, or any other field here will price
curated inventory as though the screen had no audience at all.

Build for this explicitly:

- Treat **both** namespaces as absent-by-default and gate every read on
  their presence. Do not assume a partially-populated `ext`.
- Do not infer "no audience" or a zero-valued audience from their absence.
- On a curated deal, read the audience from `user.data` (the registered
  segment) instead. That is where the targeting signal lives for these deals.
- The stripping is all-or-nothing per request: you will never see
  `ext.trb` survive while `ext.trillboards` is removed, or vice versa.



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `protocol` | `string` |  |  |
| `trillboards` | [`TrillboardsAudienceExt`](#trillboardsaudienceext) |  |  |
| `trb` | [`TrbNamespace`](#trbnamespace) |  |  |
| `trillboards_contract` | [`ContractExt`](#contractext) |  |  |


### CompletedImpressions


Completed-play observations from VAST complete and proof-of-play paths. Deduped by issued request/impression key for live revenue and daily earnings.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `integer`, nullable |  | JustBaat dedupes issued request keys; Adipolo/VidVerto/others use rendered impression_id with request fallback. Readers/rollups dedupe overlapping vast_event, proof_of_play and approved partner_sdk. |
| `completed_at` | `string` | yes |  |
| `screen_mongo_id` | `string` | yes |  |
| `device_id` | `string`, nullable |  |  |
| `ad_id` | `string` | yes |  |
| `creative_id` | `string`, nullable |  |  |
| `impression_id` | `string`, nullable |  |  |
| `source_provider` | `string` | yes | ImpressionController drops rows with unknown source_provider (PR #2924); earnings use partner billing policy, not raw counts. Exclude pi_e2e_*, admin-allocation and is_demo_data from revenue. |
| `variant_name` | `string`, nullable |  |  |
| `actual_cpm` | `number`, nullable |  | NUMERIC(18,6). |
| `actual_gross_revenue` | `number`, nullable |  | NUMERIC(18,6). |
| `pricing_source` | `string` | yes | PG is the canonical completion write; completed_impressions_dist is its CH reporting mirror. pricing_source: 'placement_purchase'=ad_price/goal per play; '*_overdelivered'/'*_zero'=$0; 'config_defa... |
| `currency` | `string` | yes |  |
| `ingestion_path` | `string` | yes |  |
| `request_id` | `string`, nullable |  | owned_direct = signed src or verified SDK. VAST impid, request_id and SDK suffix share one nonce/PG row; completion, exact debit and eligible billing commit together. First authorized write owns CH... |
| `bid_request_id` | `string`, nullable |  |  |
| `play_id` | `string`, nullable |  |  |
| `duration_seconds` | `number`, nullable |  | NUMERIC(10,2). |
| `givt_passed` | `boolean`, nullable |  |  |
| `signature` | `string`, nullable |  |  |
| `display_mode` | `string`, nullable |  |  |
| `display_area_ratio` | `number`, nullable |  | NUMERIC(5,4). |
| `metadata` | `object` | yes | SDK missing-price is server-pending until signed native pricing; directbillable_ is not authority. Client debit/mirror/pending claims are stripped. Legacy finalization: recorded/native nonnull zero... |
| `created_at` | `string` | yes | chEventParityCron: exact-key repair; created_at/oldest authorized floor; original completed_at CH key; same writer/DLQ before ACK; no delivery debit. All leaf pending indexes must be valid; failed/... |
| `screen_id` | `integer`, nullable |  |  |
| `demand_partner_id` | `integer`, nullable |  |  |
| `variant_id` | `integer`, nullable |  |  |
| `content_sha256` | `string`, nullable |  | content_sha256 is DECLARED to propagate from vast_requests via request_id but lands on ~1% of rows: PG vast_requests is empty (vastRequestsWriteBuffer defaultDisabled since 2026-06-26), so that lin... |
| `serving_tenant_id` | `integer`, nullable |  |  |
| `impression_multiplier` | `number` | yes | NUMERIC(12,6). |
| `quantity_source` | `string`, nullable |  |  |
| `quantity_source_type` | `integer`, nullable |  |  |
| `quantity_vendor` | `string`, nullable |  |  |
| `quantity_measured_at` | `string`, nullable |  |  |
| `earnings_source` | `string`, nullable |  |  |
| `earnings_deal_id` | `string`, nullable |  |  |
| `earnings_deal_type` | `string`, nullable |  |  |
| `advertiser_domain` | `string`, nullable |  |  |
| `buyer_seat` | `string`, nullable |  |  |
| `zone_id` | `string`, nullable |  |  |
| `raw_client_timestamp` | `string`, nullable |  |  |
| `normalized_event_timestamp` | `string`, nullable |  |  |
| `event_clock_skew_seconds` | `number`, nullable |  |  |
| `event_timestamp_clamped` | `boolean`, nullable |  |  |
| `billable_key` | `string`, nullable |  |  |


### ContractExt


Signal quality assurance contract. Tells DSPs how complete and
reliable the signals in this bid request are. If valid=false,
some required fields are missing (but the request is still valid OpenRTB).



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `version` | `string` |  | Contract schema version |
| `valid` | `boolean` |  | Whether all required fields passed validation |
| `required_field_coverage_pct` | `number` |  | Percentage of required fields that are present and valid |
| `error_count` | `integer` |  | Number of validation errors (missing required fields) |
| `warning_count` | `integer` |  | Number of validation warnings (recommended fields missing) |
| `errors` | array of `object` |  |  |
| `warnings` | array of `object` |  |  |


```json
{
  "version": "2026-03-v1",
  "valid": true,
  "required_field_coverage_pct": 100,
  "error_count": 0,
  "warning_count": 0,
  "errors": [],
  "warnings": []
}
```


### DOOHBidRequest


Full OpenRTB 2.6 DOOH bid request with all Trillboards extensions


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Unique bid request ID |
| `imp` | array of [`Impression`](#impression) |  |  |
| `dooh` | [`DOOHObject`](#doohobject) |  |  |
| `device` | [`Device`](#device) |  |  |
| `user` | [`User`](#user) |  |  |
| `source` | [`Source`](#source) |  |  |
| `regs` | [`Regs`](#regs) |  |  |
| `at` | `integer` — one of `1` |  | Auction type. Always 1 (first price) |
| `tmax` | `integer` |  | Maximum response time in milliseconds |
| `cur` | array of `string` |  |  |
| `ext` | [`BidRequestExt`](#bidrequestext) |  |  |


```json
{
  "id": "691fced1-040c-4354-b861-ef2496f44f29",
  "imp": [
    {
      "id": "imp_507f1f77bcf86cd799439011",
      "tagid": "507f1f77bcf86cd799439011",
      "bidfloor": 2,
      "bidfloorcur": "USD",
      "secure": 1,
      "dt": 1788279423607,
      "qty": {
        "multiplier": 2,
        "sourcetype": 2
      },
      "banner": {
        "w": 1920,
        "h": 1080,
        "format": [
          {
            "w": 1920,
            "h": 1080
          }
        ],
        "pos": 1
      },
      "video": {
        "mimes": [
          "video/mp4",
          "video/webm"
        ],
        "minduration": 5,
        "maxduration": 30,
        "protocols": [
          2,
          3,
          5,
          6
        ],
        "w": 1920,
        "h": 1080,
        "startdelay": 0,
        "linearity": 1,
        "skip": 0,
        "placement": 4
      }
    }
  ],
  "dooh": {
    "id": "507f1f77bcf86cd799439011",
    "name": "Test Screen",
    "venuetype": [
      2,
      202
    ],
    "venuetypetax": 5,
    "publisher": {
      "id": "trillboards",
      "name": "Trillboards",
      "domain": "trillboards.com",
      "cat": [
        "IAB24"
      ]
    },
    "domain": "trillboards.com",
    "keywords": "Retail,Shopping Mall,New York,NY",
    "content": {
      "genre": "Entertainment",
      "cattax": 1,
      "cat": [
        "IAB1"
      ],
      "prodq": 1,
      "context": 1,
      "contentrating": "TV-PG",
      "livestream": 1,
      "language": "EN",
      "channel": {
        "name": "Entertainment"
      }
    }
  },
  "device": {
    "devicetype": 8,
    "connectiontype": 2,
    "w": 1920,
    "h": 1080,
    "geo": {
      "lat": 40.7128,
      "lon": -74.006,
      "type": 1,
      "country": "US",
      "region": "NY",
      "city": "New York",
      "zip": "10001"
    }
  },
  "source": {
    "fd": 0,
    "tid": "691fced1-040c-4354-b861-ef2496f44f29",
    "schain": {
      "complete": 1,
      "nodes": [
        {
          "asi": "trillboards.com",
          "sid": "trillboards",
          "rid": "691fced1-040c-4354-b861-ef2496f44f29",
          "name": "Trillboards",
          "domain": "trillboards.com",
          "hp": 1
        }
      ],
      "ver": "1.0"
    }
  },
  "at": 1,
  "tmax": 500,
  "cur": [
    "USD"
  ],
  "test": 0,
  "regs": {
    "coppa": 0,
    "gdpr": 0
  },
  "ext": {
    "protocol": "OpenRTB 2.6",
    "trillboards_contract": {
      "version": "2026-03-v1",
      "valid": true,
      "required_field_coverage_pct": 100,
      "error_count": 0,
      "warning_count": 0,
      "errors": [],
      "warnings": []
    },
    "trillboards": {
      "attention_score": 0.87,
      "audience_count": 8,
      "crowd_density": 12,
      "ad_receptivity": 0.75,
      "emotional_engagement": 0.82,
      "mood": "happy",
      "estimated_occupancy": 25,
      "avg_dwell_ms": 4500,
      "group_composition": {
        "solo": 3
      },
      "screen_engagement": "active",
      "audience_reaction": "positive",
      "signals_age_ms": 12480
    },
    "trb": {
      "weather": {
        "temp_f": 85,
        "feels_like_f": 88,
        "humidity": 75,
        "condition": "Partly cloudy",
        "uv_index": 8,
        "wind_mph": 12,
        "is_raining": false,
        "temp_segment": "hot"
      },
      "foot_traffic": {
        "current_audience": 25,
        "estimated_occupancy": 50,
        "avg_dwell_seconds": 6,
        "traffic_tier": "very_high",
        "estimated_hourly_impressions": 15000
      }
    }
  }
}
```


### DOOHObject


OpenRTB 2.6 DOOH object (top-level, replaces site/app)


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `name` | `string` |  |  |
| `venuetype` | array of `integer` |  | OpenOOH venue-type ids, as INTEGERS, projected down to taxonomy **1.1** — the version `venuetypetax` declares. Corrected 2026-09-01 against `openrtbRequestBuilder.js`, which has always emitted integers. This declared `string` items and "v1.2 IDs"; both were wrong. Our tables implement OpenOOH 1.2, but AdCOM's taxonomy enumeration stops at 5 (= OpenOOH 1.1), so 1.2 cannot be signalled on the wire at all and the ids are projected. The projection is lossless in MEANING, only in specificity — see the WIRE PROJECTION block in `config/openoohTaxonomy.js`. The array is OMITTED rather than sent empty when classification yields nothing: `venuetype: []` would assert "we classified this screen as belonging to no venue type", which is a different and false claim. |
| `venuetypetax` | `integer` — one of `5` |  | AdCOM venue-taxonomy identifier. **5 = OpenOOH 1.1**, and 5 is what we send. Corrected 2026-09-01. This declared `enum: [1]` described as "1 = OpenOOH Venue Taxonomy". AdCOM value 1 is OpenOOH **1.0**, so the published contract named the oldest taxonomy in the list while the ids alongside it were not that taxonomy. The builder itself carried the same bug and was fixed; this document was not updated with it, so a DSP resolving our `venuetype` ids against OpenOOH 1.0 would have mapped them against the wrong version. |
| `publisher` | `object` |  |  |
| `domain` | `string` |  |  |
| `keywords` | `string` |  |  |


### DemandPartners


Canonical INT-PK identity table for demand-side partners (DSPs/SSPs that Trillboards routes ad requests to). Wave 2 of pristine-state refactor. Replaces partner_key TEXT joins across the billing path.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `demand_partner_id` | `string`, nullable |  | demand_partner_id INT is the canonical FK going forward; partner_key TEXT is kept as the wire-format alternate-key FOREVER (external partner-API auth + admin UI rely on it). Never propose dropping ... |
| `partner_key` | `string` | yes |  |
| `public_alias` | `string` | yes | public_alias UNIQUE: this is the obfuscated external alias partner-API consumers see. partnerAlias.js will read from this table after Wave 2 cutover. |
| `display_name` | `string` | yes |  |
| `partner_type` | `string` | yes |  |
| `archived` | `boolean` | yes |  |
| `created_at` | `string` | yes |  |
| `updated_at` | `string` | yes |  |


### Device


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `devicetype` | `integer` — one of `8` |  | 8 = Digital Out of Home (DOOH) per OpenRTB 2.6 |
| `ua` | `string` |  |  |
| `make` | `string` |  |  |
| `model` | `string` |  |  |
| `os` | `string` |  |  |
| `osv` | `string` |  |  |
| `connectiontype` | `integer` |  |  |
| `w` | `integer` |  |  |
| `h` | `integer` |  |  |
| `ifa` | `string` |  | OS-sanctioned resettable advertising ID in the clear; omitted when unavailable or limited |
| `ifa_type` | `string` — one of `aaid`, `rida`, `afai`, `idfa`, `tifa`, `msai`, `dpid`, `ppid`, … (10 total) |  | Legacy compatibility copy; canonical DSP-compatible placement is device.ext.ifa_type |
| `ext` | `object` |  |  |
| `geo` | `object` |  |  |
| `eids` | array of `object` |  | Extended device identifiers (IAB recommended for DOOH) |


### EarnerScreens


User-owned ad screens. Each row is a logical screen that can display ads. Links user to device. PG primary with Mongo legacy mirror.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `taxonomy_spec_version` | `string`, nullable |  |  |
| `taxonomy_migrated_at` | `string`, nullable |  |  |
| `auction_mode` | `string`, nullable |  |  |
| `auction_type` | `string`, nullable |  |  |
| `auction_enabled_at` | `string`, nullable |  |  |
| `auction_cohort` | `string`, nullable |  |  |
| `sync_is_master` | `boolean`, nullable |  |  |
| `sync_master_screen_id` | `string`, nullable |  |  |
| `sync_enabled` | `boolean`, nullable |  |  |
| `sync_last_sync_at` | `string`, nullable |  |  |
| `sync_group_name` | `string`, nullable |  |  |
| `registration_source` | `string`, nullable |  |  |
| `last_offline_transition_at` | `string`, nullable |  |  |
| `is_standby` | `boolean` | yes |  |
| `blocked_iab_categories` | array of `string` |  |  |
| `blocked_advertisers` | array of `string` |  |  |
| `pref_allow_tobacco` | `boolean`, nullable |  |  |
| `pref_allow_religious` | `boolean`, nullable |  |  |
| `pref_auto_approve_known_brands` | `boolean`, nullable |  |  |
| `pref_blocked_subjects` | array of `string` |  |  |
| `pref_allowed_subjects` | array of `string` |  |  |
| `pref_blocked_keywords` | array of `string` |  |  |
| `pref_allowed_keywords` | array of `string` |  |  |
| `geocode_source` | `string`, nullable |  |  |
| `venue_parent` | `string`, nullable |  |  |
| `venue_child` | `string`, nullable |  |  |
| `venue_grandchild` | `string`, nullable |  |  |
| `environment_type` | `string`, nullable |  |  |
| `placement_type` | `string`, nullable |  |  |
| `venue_state` | `string`, nullable |  |  |
| `venue_city` | `string`, nullable |  |  |
| `display_mode` | `string`, nullable |  |  |
| `ad_interval_seconds` | `integer`, nullable |  |  |
| `sound_enabled` | `boolean`, nullable |  |  |
| `advertisement_sizing` | `string`, nullable |  |  |
| `avg_dwell_time_seconds` | `integer`, nullable |  |  |
| `peak_hours` | array of `string` |  |  |
| `delivery_mode` | `string` | yes |  |
| `loop_plan_id` | `integer`, nullable |  |  |
| `ntp_sync_required` | `boolean` | yes |  |
| `venue_classification_source` | `string`, nullable |  | enrichment_status: PG GENERATED from (venue_classification_source, enrichment_failed_at); a real classification DOMINATES a stale failure stamp (success wins). Never written directly. Values: pendi... |
| `device_platform_override` | `string`, nullable |  |  |
| `hb_vast_tag_url` | `string`, nullable |  |  |
| `hb_min_interval_seconds` | `integer`, nullable |  |  |
| `hb_last_sync_at` | `string`, nullable |  |  |
| `waterfall_partners` | array of `string` | yes | waterfall_partners is the ONLY pin store (order + whitelist; screen_partner_settings was never built). Serving reads it only with a screen_header_bidding_config row and ignores it once waterfall_op... |
| `waterfall_total_timeout_ms` | `integer`, nullable |  |  |
| `waterfall_optimized_at` | `string`, nullable |  |  |
| `programmatic_enabled` | `boolean` | yes |  |
| `prog_currency` | `string` | yes |  |
| `preferred_deal_ids` | array of `string` | yes |  |
| `last_programmatic_sync_at` | `string`, nullable |  |  |
| `mediation_priority` | `integer`, nullable |  |  |
| `hive_stack_screen_id` | `string`, nullable |  |  |
| `hive_stack_site_id` | `string`, nullable |  |  |
| `hive_stack_unit_id` | `string`, nullable |  |  |
| `hive_stack_unit_uuid` | `string`, nullable |  |  |
| `hive_stack_synced_at` | `string`, nullable |  |  |
| `hive_stack_sync_status` | `string`, nullable |  |  |
| `taggify_screen_id` | `string`, nullable |  |  |
| `gam_ad_unit_id` | `string`, nullable |  |  |
| `gam_ad_unit_code` | `string`, nullable |  |  |
| `gam_synced_at` | `string`, nullable |  |  |
| `gam_sync_status` | `string`, nullable |  |  |
| `branding_overlay_enabled` | `boolean` | yes |  |
| `branding_overlay_logo_url` | `string` | yes |  |
| `branding_overlay_logo_transformed_url` | `string` | yes |  |
| `branding_overlay_position` | `string` | yes |  |
| `branding_overlay_size_ratio` | `number` | yes | NUMERIC(5,4). |
| `branding_overlay_padding_ratio` | `number` | yes | NUMERIC(5,4). |
| `branding_overlay_opacity` | `number` | yes | NUMERIC(5,4). |
| `branding_overlay_hide_on_ads` | `boolean` | yes |  |
| `region` | `string` | yes |  |
| `physical_size_set_by` | `string`, nullable |  |  |
| `physical_size_set_at` | `string`, nullable |  |  |
| `offline_alert_sent_at` | `string`, nullable |  |  |
| `back_online_alert_sent_at` | `string`, nullable |  |  |
| `enrichment_failed_at` | `string`, nullable |  |  |
| `operating_hours` | `object`, nullable |  |  |
| `slot_duration_seconds` | `integer`, nullable |  |  |
| `state_iso_3166_2` | `string`, nullable |  |  |
| `geocoding_raw_response` | `object`, nullable |  |  |
| `geocoded_at` | `string`, nullable |  |  |
| `photo_flagged` | `boolean` | yes |  |
| `photo_flagged_at` | `string`, nullable |  |  |
| `photo_flagged_by_mongo_id` | `string`, nullable |  |  |
| `photo_flag_reason` | `string`, nullable |  |  |
| `photo_flag_notes` | `string`, nullable |  |  |
| `photo_notification_sent_at` | `string`, nullable |  |  |
| `photo_notification_count` | `integer` | yes |  |
| `photo_quality_sent_at` | `string`, nullable |  |  |
| `l_bar_position` | `string`, nullable |  |  |
| `block_group_geoid` | `string`, nullable |  |  |
| `dma_code` | `string`, nullable |  |  |
| `dma_name` | `string`, nullable |  |  |
| `place_name` | `string`, nullable |  |  |
| `neighborhood` | `string`, nullable |  |  |
| `branding_overlay_placement` | `string` | yes |  |
| `archetype_photo_url` | `string`, nullable |  |  |
| `archetype_photo_key` | `string`, nullable |  |  |
| `archetype_photo_synced_at` | `string`, nullable |  |  |
| `offline_push_alert_sent_at` | `string`, nullable |  |  |
| `is_demo_data` | `boolean` | yes |  |
| `deleted_at` | `string`, nullable |  | deleted_at IS NULL required — soft-delete nulls earnerscreen_device_id for partial unique index |
| `partner_mongo_id` | `string`, nullable |  |  |
| `photos` | `object`, nullable |  |  |
| `photo_review_status` | `string`, nullable |  |  |
| `venue_category` | `string`, nullable |  |  |
| `venue_subcategory` | `string`, nullable |  |  |
| `venue_child_id` | `string`, nullable |  |  |
| `places_rating` | `number`, nullable |  |  |
| `places_review_count` | `integer`, nullable |  |  |
| `commercial_value_score` | `number`, nullable |  |  |
| `foot_traffic_multiplier` | `number`, nullable |  |  |
| `floor_price_cpm` | `number`, nullable |  | NUMERIC(12,6). |
| `distributor_id` | `integer`, nullable |  |  |
| `billing_mode` | `string` | yes |  |
| `ads_disabled_reasons` | array of `string` | yes |  |
| `cms_payment_status` | `string` | yes |  |
| `ssp_enabled` | `boolean`, nullable |  |  |
| `gam_ad_unit_path` | `string`, nullable |  |  |
| `l_bar_ads_enabled` | `boolean`, nullable |  |  |
| `width_inches` | `number`, nullable |  | Physical width_inches/height_inches/diagonal_inches are inches. Pixels live on earner_screen_devices; the raw screen has no resolution_width/resolution_height columns. |
| `height_inches` | `number`, nullable |  |  |
| `diagonal_inches` | `number`, nullable |  |  |
| `dynamic_floor_pricing` | `boolean`, nullable |  |  |
| `prog_allocation_pct` | `number`, nullable |  |  |
| `hb_provider` | `string`, nullable |  |  |
| `hb_timeout_ms` | `integer`, nullable |  |  |
| `hb_enabled` | `boolean`, nullable |  |  |
| `hb_allocation` | `number`, nullable |  |  |
| `hb_request_mode` | `string`, nullable |  |  |
| `hb_force_request` | `boolean`, nullable |  |  |
| `pref_blocked_categories` | array of `string` |  |  |
| `pref_allowed_categories` | array of `string` |  |  |
| `content_filtering_enabled` | `boolean`, nullable |  |  |
| `pref_level` | `string`, nullable |  |  |
| `pref_max_age_rating` | `string`, nullable |  |  |
| `mobile_distance_threshold_m` | `integer`, nullable |  |  |
| `mobile_update_interval_s` | `integer`, nullable |  |  |
| `mobile_vehicle_type` | `string`, nullable |  |  |
| `latitude` | `number`, nullable |  |  |
| `longitude` | `number`, nullable |  |  |
| `brand_substitution_mode` | `string` | yes |  |
| `brand_substitution_consent_at` | `string`, nullable |  |  |
| `brand_substitution_consent_by` | `string`, nullable |  |  |
| `serving_tenant_id` | `integer`, nullable |  |  |
| `enrichment_attempts` | `integer` | yes |  |
| `last_enrichment_attempt_at` | `string`, nullable |  |  |
| `media_capability` | `string` — one of `image_video`, `image_only`, `video_only` |  |  |
| `screen_placement` | `string`, nullable |  |  |


### EventExt


Large-event proximity for the screen. The whole `event` sub-namespace is
present ONLY when a nearby event was detected — its absence means "no
nearby event", so `nearby` is always `true` when the object exists.



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `nearby` | `boolean` |  | Always `true` when this object is present. |
| `count` | `integer` |  | Number of nearby events detected |
| `max_capacity` | `integer` |  | Attendee capacity of the largest nearby event |
| `category` | `string` |  | Dominant category across the nearby events |
| `audience_spike` | `boolean` |  | Whether an audience spike is expected from these events |


### FootTrafficExt


Real-time venue foot traffic metrics derived from FEIN audience sensing.
Higher traffic = more impressions = higher value for advertisers.



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `current_audience` | `integer` |  | Current number of people detected (face count, rounded) |
| `estimated_occupancy` | `integer` |  | Estimated total venue occupancy (extrapolated) |
| `avg_dwell_seconds` | `integer` |  | Average dwell time in seconds |
| `traffic_tier` | `string` — one of `very_low`, `low`, `medium`, `high`, `very_high` |  | Traffic classification for easy targeting: - very_high: >= 50 people - high: 20-49 people - medium: 8-19 people - low: 3-7 people - very_low: < 3 people |
| `estimated_hourly_impressions` | `integer` |  | Projected impressions per hour based on face turnover rate |


```json
{
  "current_audience": 25,
  "estimated_occupancy": 50,
  "avg_dwell_seconds": 6,
  "traffic_tier": "very_high",
  "estimated_hourly_impressions": 15000
}
```


### IABSegmentReference


Reference table of IAB Audience Taxonomy 1.1 segment IDs used by Trillboards.

### Income Segments
| ID | Name |
|-----|------|
| 1001 | High Income |
| 1002 | Upper-Middle Income |
| 1003 | Middle Income |
| 1004 | Lower-Middle Income |
| 1005 | Low Income |

### Lifestyle Segments
| ID | Name |
|-----|------|
| 2001 | Business Professional |
| 2002 | Student |
| 2003 | Fitness Enthusiast |
| 2004 | Luxury Shopper |
| 2005 | Tech Savvy |
| 2006 | Outdoor Active |
| 2007 | Foodie |
| 2008 | Health Conscious |
| 2009 | Parent |
| 2010 | Commuter |
| 2011 | Tourist |
| 2012 | Nightlife |
| 2013 | Pet Owner |
| 2014 | Gamer |
| 2015 | Reader |
| 2016 | Eco-Conscious |
| 2017 | Fashion Forward |
| 2018 | DIY/Home Improvement |
| 2019 | Music Lover |
| 2020 | Sports Fan |

### Purchase Intent Segments
| ID | Name |
|-----|------|
| 3001 | High Purchase Intent |
| 3002 | Medium Purchase Intent |
| 3003 | Low Purchase Intent |



Type: `object`


### Impression


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` |  |  |
| `tagid` | `string` |  | Screen MongoDB ID |
| `bidfloor` | `number` |  | Floor price in CPM |
| `bidfloorcur` | `string` |  |  |
| `secure` | `integer` |  |  |
| `dt` | `integer` |  | Estimated fulfillment timestamp (epoch seconds) |
| `qty` | `object` |  | DOOH impression quantity/multiplier (OpenRTB 2.6) |
| `banner` | `object` |  |  |
| `video` | `object` |  |  |


### IntentExt


Purchase intent signals derived from ambient audio classification.
YAMNet TFLite classifies audio SCENES (not speech content) on-device.
Combined with visual shopping signals (bag detection) and demographic
context to compute a composite intent score.

Higher intent_score = audience is more likely to make a purchase.
DSPs can bid higher when purchase_stage is READY_TO_BUY or COMPARING.



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `score` | `number` |  | Composite purchase intent score (0-1). Weighted combination of verbal intent, brand mentions, price inquiry, shopping activity, bag detection, income match, emotion, and engagement. |
| `purchase_stage` | `string` — one of `READY_TO_BUY`, `COMPARING`, `CONSIDERING`, `BROWSING`, `NONE` |  | Classified purchase funnel stage based on behavioral signals. - READY_TO_BUY: High intent + brand mentions + price inquiry (score >= 0.7) - COMPARING: Active comparison shopping (score 0.5-0.7) - CONSIDERING: Interest shown but no purchase signals (score 0.3-0.5) - BROWSING: Casual browsing, low intent (score 0.1-0.3) - NONE: No purchase intent detected (score < 0.1) |
| `categories` | array of `object` |  | Detected product/service interest categories |
| `brand_mentions` | `boolean` |  | Whether brand names were detected in ambient audio |
| `brand_count` | `integer` |  | Number of distinct brand mentions detected |
| `audience_size` | `integer` |  | Current audience size (face count) when intent was measured |
| `should_trigger` | `boolean` |  | Whether intent score is high enough to trigger premium ad swap |


### OpenrtbRevenueScreenHourly


Revenue per screen per hour. Aggregates gross revenue from completed impressions. Refreshed from CH via clickhouseRollupSource. PG only.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `hour_bucket` | `string` | yes |  |
| `screen_mongo_id` | `string` | yes |  |
| `impressions` | `integer` | yes |  |
| `priced_impressions` | `integer` | yes |  |
| `estimated_impressions` | `integer` | yes |  |
| `actual_gross_revenue` | `number` | yes |  |
| `estimated_gross_revenue` | `number` | yes |  |
| `gross_revenue` | `number` | yes |  |
| `updated_at` | `string` | yes |  |


### PartnerReconciliationReports


Partner-reported impression and revenue counts for reconciliation against deduped completed_impressions. Ingested from VidVerto SSP API and Adipolo API / JustBaat CSV reports. PG only.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `their_requests` | `integer`, nullable |  |  |
| `our_requests` | `integer`, nullable |  |  |
| `request_variance` | `number`, nullable |  | NUMERIC(10,4). |
| `demand_partner_id` | `integer`, nullable |  | Wave 2 B added demand_partner_id INT + variant_id INT FKs. Legacy partner_key TEXT kept as wire-format alternate-key. Backfill via follow-up Wave 2 B-backfill PR. |
| `variant_id` | `integer`, nullable |  |  |
| `id` | `integer`, nullable |  | VidVerto synced daily via vidvertoRevenueSync before programmatic earnings aggregation. |
| `provider_name` | `string` | yes |  |
| `report_date` | `string` | yes |  |
| `report_type` | `string` — one of `partner_api`, `manual_upload`, `email_extract`, `dashboard_snapshot` | yes |  |
| `their_impressions` | `integer`, nullable |  |  |
| `their_revenue` | `number`, nullable |  | NUMERIC(14,6). |
| `their_ecpm` | `number`, nullable |  | NUMERIC(10,4). |
| `their_fill_rate` | `number`, nullable |  | NUMERIC(6,4). |
| `our_impressions` | `integer`, nullable |  |  |
| `our_revenue` | `number`, nullable |  | NUMERIC(14,6). |
| `our_ecpm` | `number`, nullable |  | NUMERIC(10,4). |
| `impression_variance` | `number`, nullable |  | NUMERIC(8,4). |
| `revenue_variance` | `number`, nullable |  | NUMERIC(8,4). |
| `status` | `string` — one of `pending`, `matched`, `flagged`, `disputed`, `resolved`, `accepted` | yes |  |
| `resolution_notes` | `string`, nullable |  |  |
| `adjustment_id` | `integer`, nullable |  |  |
| `raw_data` | `object`, nullable |  | Adipolo publisher revenue requires a completed vast_requests lifecycle plus latest screens_live source='owned'. ID shape/event alone is insufficient; shared, external, and unjoined bundles are excl... |
| `imported_by` | `string`, nullable |  |  |
| `reviewed_by` | `string`, nullable |  |  |
| `reviewed_at` | `string`, nullable |  |  |
| `created_at` | `string` | yes |  |
| `updated_at` | `string` | yes |  |
| `applied_report_hash` | `string`, nullable |  | applied_report_hash/applied_at (mig 449) gate the hourly pricing re-apply: syncs skip the CI re-stamp + PED rebuild when the applied tuple is unchanged. Written ONLY by partnerPricingApplyGate.reco... |
| `applied_at` | `string`, nullable |  |  |


### PartnerVariants


Canonical INT-PK identity for partner variants (e.g. adipolo_lower_floor_tablet). Wave 2 of pristine-state refactor. variant_name TEXT remains as the wire-format alternate-key indefinitely.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `variant_id` | `string`, nullable |  | feeds_into lists tables that will gain a nullable variant_id INT FK in Wave 2 Stream B. Each is a separate PR — this PR mints the dimension only. |
| `demand_partner_id` | `integer` | yes | Backfill is 1:N from demand_partner_config.variant_names[]. Rows with NULL demand_partner_id at apply time are silently skipped — deploy-controller previous-tick guard ensures Wave 2 A1 has populat... |
| `variant_name` | `string` | yes | variant_name TEXT is the wire-format alternate-key (kept forever) — internal logs and partner integrations rely on it. Never propose dropping variant_name. |
| `public_alias` | `string` | yes | public_alias is the obfuscation alias for partner-API responses (matches partnerAlias.encodeAlias pattern: 'var_' \|\| sha256(variant_name)[0..5]). |
| `display_name` | `string`, nullable |  | vast_tag_variants JSONB on demand_partner_config still co-exists during transition. Backfill UPDATE pulls display_name from the JSONB if present (no-op today; forward-compatible). |
| `archived` | `boolean` | yes |  |
| `created_at` | `string` | yes |  |
| `updated_at` | `string` | yes |  |
| `daily_impression_cap` | `integer`, nullable |  |  |
| `daily_request_cap` | `integer`, nullable |  |  |
| `daily_budget_cap` | `number`, nullable |  | NUMERIC(10,2). |
| `request_pressure_enabled` | `boolean`, nullable |  | request_pressure_enabled=false fails open for pressure shaping only. It must not be treated as demand-source enablement. |
| `request_pressure_base_interval_seconds` | `integer`, nullable |  |  |
| `request_pressure_probe_interval_seconds` | `integer`, nullable |  |  |
| `request_pressure_defer_seconds` | `integer`, nullable |  |  |
| `request_pressure_probe_modulo` | `integer`, nullable |  |  |
| `request_pressure_probe_target_per_minute` | `number`, nullable |  | NUMERIC(10,4). |
| `request_pressure_min_pair_requests` | `integer`, nullable |  |  |
| `request_pressure_min_source_requests` | `integer`, nullable |  |  |
| `request_pressure_completion_rate_floor` | `number`, nullable |  | NUMERIC(12,8). |
| `request_pressure_confidence_level` | `number`, nullable |  | NUMERIC(6,3). |
| `request_pressure_max_multiplier` | `integer`, nullable |  |  |


### PartnerZoneCpmDaily


Per-zone per-day CPM rates from partner APIs. Used for revenue estimation and settled partner-truth allocation when partner_reconciliation_reports does not provide a newer manual/API row. PG only.


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `demand_partner_id` | `integer`, nullable |  | Wave 2 B added demand_partner_id INT + variant_id INT FKs. Legacy partner_key TEXT kept as wire-format alternate-key. Backfill via follow-up Wave 2 B-backfill PR. |
| `variant_id` | `integer`, nullable |  |  |
| `id` | `string`, nullable |  |  |
| `partner_key` | `string` | yes |  |
| `zone_id` | `string` | yes |  |
| `zone_label` | `string`, nullable |  |  |
| `period_date` | `string` | yes |  |
| `ecpm` | `number` | yes | NUMERIC(10,4). |
| `gross_revenue` | `number`, nullable |  | NUMERIC(14,6). |
| `impressions` | `integer`, nullable |  |  |
| `requests` | `integer`, nullable |  |  |
| `fill_rate` | `number`, nullable |  | NUMERIC(6,4). |
| `source` | `string` | yes | Daily earnings aggregation may use these rows to settle gross revenue, but completed_impressions remains the event-count source for programmatic_earnings_daily.impressions_count. |
| `fetched_at` | `string` | yes |  |
| `created_at` | `string` | yes |  |
| `updated_at` | `string` | yes |  |


### Regs


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `coppa` | `integer` |  |  |
| `gdpr` | `integer` |  | Set to 0 by the Trillboards request builder. On demand rails with wire hygiene enabled, the field carries the value from the authenticated publisher or device privacy context and is omitted when that context has none. |


### Segment


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` |  | Segment identifier (IAB taxonomy ID or seller-defined) |
| `name` | `string` |  | Human-readable segment name |
| `value` | `string` |  |  |


### SellerDefinedSegmentReference


Seller-defined context segments in the `trillboards-seller-defined` data object.
These are included in `user.data[]` with `ext.segtax` omitted (seller-defined taxonomy).

### Venue Segments (trb_vn_*)
| ID | Name | Matches |
|-----|------|---------|
| trb_vn_001 | venue:fitness_gym | gym, fitness, workout, crossfit |
| trb_vn_002 | venue:restaurant_casual | casual restaurant, diner |
| trb_vn_003 | venue:restaurant_quick_service | QSR, fast food, takeout |
| trb_vn_004 | venue:bar_nightlife | bar, nightlife, club, pub, lounge |
| trb_vn_005 | venue:salon_beauty | salon, beauty, spa |
| trb_vn_006 | venue:barber_shop | barber |
| trb_vn_007 | venue:retail_general | retail, shopping, mall |
| trb_vn_008 | venue:retail_convenience | convenience, gas station |
| trb_vn_009 | venue:office_lobby | office, cowork, business |
| trb_vn_010 | venue:healthcare_waiting_room | clinic, medical, hospital, pharmacy |
| trb_vn_011 | venue:education_campus | campus, college, university, school |
| trb_vn_012 | venue:hotel_hospitality | hotel, hospitality, resort |
| trb_vn_013 | venue:transit_hub | transit, station, airport, terminal |
| trb_vn_014 | venue:entertainment | cinema, theater, arcade, event |
| trb_vn_015 | venue:residential_common | residential, apartment, condo, lobby |

### Geo Segments (trb_geo_*)
| ID | Name |
|-----|------|
| trb_geo_001 | geo:country_us |
| trb_geo_002 | geo:state_ca |
| trb_geo_003 | geo:state_ny |
| trb_geo_004 | geo:state_tx |
| trb_geo_005 | geo:city_tier_1 |

### Traffic Tier Segments (trb_trf_*)
| ID | Name | Threshold |
|-----|------|-----------|
| trb_trf_001 | traffic:very_low | < 3 people |
| trb_trf_002 | traffic:low | 3-7 people |
| trb_trf_003 | traffic:medium | 8-19 people |
| trb_trf_004 | traffic:high | 20-49 people |
| trb_trf_005 | traffic:very_high | >= 50 people |

### Dwell Time Segments (trb_dwl_*)
| ID | Name | Threshold |
|-----|------|-----------|
| trb_dwl_001 | dwell:very_short | < 3 seconds |
| trb_dwl_002 | dwell:short | 3-7 seconds |
| trb_dwl_003 | dwell:medium | 7-15 seconds |
| trb_dwl_004 | dwell:long | > 15 seconds |

### Daypart Segments (trb_dpt_*)
| ID | Name | Hours (UTC) |
|-----|------|-------------|
| trb_dpt_001 | daypart:morning | 05:00-10:59 |
| trb_dpt_002 | daypart:midday | 11:00-13:59 |
| trb_dpt_003 | daypart:afternoon | 14:00-17:59 |
| trb_dpt_004 | daypart:evening | 18:00-22:59 |
| trb_dpt_005 | daypart:late_night | 23:00-04:59 |

### Quality Flags (trb_qly_*)
| ID | Name | Meaning |
|-----|------|---------|
| trb_qly_001 | quality:geo_verified | Screen has GPS coordinates |
| trb_qly_002 | quality:edge_sensed_audience | Real-time FEIN audience data present |
| trb_qly_003 | quality:floor_defined | Publisher floor price is set |



Type: `object`


### Source


| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `fd` | `integer` |  | 1 = exchange is final decision maker |
| `tid` | `string` |  | Transaction/request ID |
| `schain` | `object` |  | Supply chain transparency |


### TrbNamespace


Trillboards extension sub-namespaces. Every sub-namespace is OPTIONAL and
is omitted entirely when the underlying signal is unavailable for that
screen — treat an absent key as "no signal", never as a zero.

This object is pinned to the request builder by
`tests/unit/openrtbExtNamespaceSpecParity.test.js`, which derives the
emitted key set from the source and fails on drift in either direction.



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `vas` | [`VASExt`](#vasext) |  |  |
| `intent` | [`IntentExt`](#intentext) |  |  |
| `weather` | [`WeatherExt`](#weatherext) |  |  |
| `foot_traffic` | [`FootTrafficExt`](#foottrafficext) |  |  |
| `venue` | [`VenueExt`](#venueext) |  |  |
| `event` | [`EventExt`](#eventext) |  |  |


### TrillboardsAudienceExt


Real-time audience intelligence from FEIN edge AI sensors.
Updated every 10-30 seconds. These signals are MEASURED, not estimated.
Unlike CTV viewability which uses probabilistic models, Trillboards uses
on-device computer vision (ML Kit) and audio classification (YAMNet TFLite)
to provide deterministic audience data.



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `attention_score` | `number` |  | Fraction of detected faces actively looking at the screen. 0.0 = nobody looking, 1.0 = everyone looking. Measured via gaze detection, NOT self-reported or probabilistic. |
| `audience_count` | `number` |  | Average number of faces detected during current measurement window. **Parse `audience_count`, not `live_face_count`.** A previous revision of this spec documented this field as `live_face_count` and stated that `audience_count` "was never actually emitted by the server". That was exactly backwards, and it was a confusion of two different surfaces: - **This surface** — the outbound bid request's `ext.trillboards` —   has always emitted `audience_count`. - The **inventory discovery** response (`GET /openrtb/v2/adslots`)   emits `live_face_count` inside its `fein` object. Both names are live; they belong to different documents. `live_face_count` never appears in a bid request. |
| `crowd_density` | `integer` |  | Peak face count observed in current window (max concurrent viewers) |
| `ad_receptivity` | `number` |  | Audio-derived venue receptivity score. Quiet/focused environments score higher. Based on YAMNet ambient sound classification. |
| `emotional_engagement` | `number` |  | Composite emotional engagement score from facial expression analysis. Higher = more engaged (positive or negative reaction to content). Computed from each detected person's facial expression, classified on the device. |
| `mood` | `string` — one of `happy`, `neutral`, `focused`, `calm`, `energetic`, `social`, `surprised`, `sad` |  | Dominant venue emotional state derived from facial expression analysis. **Parse `mood`, not `dominant_emotion`.** Same surface confusion as `audience_count` above: the bid request emits `mood`; the `GET /openrtb/v2/adslots` discovery response emits `dominant_emotion`. |
| `estimated_occupancy` | `integer` |  | Estimated venue occupancy (extrapolated from visible faces + venue capacity) |
| `avg_dwell_ms` | `number` |  | Average time (milliseconds) a face stays in the camera's field of view |
| `group_composition` | `object` |  | Audience composition breakdown by demographic bucket. Derived from each detected person's estimated age range and gender. |
| `screen_engagement` | `string` |  | Categorical engagement label passed through from the edge reading (e.g. `active`), NOT a score. Corrected 2026-09-01. This declared `type: number` with `minimum: 0`, `maximum: 1` and `example: 0.65`, but `_buildTrillboardsExt` assigns `audience.screenEngagement` unchanged and that value is a string everywhere it is produced. A bidder doing arithmetic on this field was getting `NaN`. The combined 0-1 metrics are `emotional_engagement` and `ad_receptivity`. |
| `audience_reaction` | `string` — one of `positive`, `neutral`, `negative`, `mixed` |  | Dominant audience reaction to current content |
| `signals_age_ms` | `integer` |  | Milliseconds since last FEIN measurement update. Lower = fresher signals. Typical: 10,000-30,000ms. If > 120,000ms, signals may be stale (screen offline or camera occluded). |
| `reliability_score` | `number` |  | Screen reliability score from unified telemetry. Factors: uptime, heartbeat regularity, GPS accuracy, FEIN measurement frequency. |
| `audience_quality` | `number` |  | Audience data quality score. High = rich FEIN signals with high confidence. Low = limited or stale audience data. |
| `screen_quality_composite` | `number` |  | Composite quality score combining reliability + audience quality + geo accuracy |
| `speech_contexts` | array of `string` |  | Shopping contexts inferred from on-device speech classification. The bid request carries the context labels; Trillboards stores the speech transcripts they come from. Omitted entirely when no context was inferred. |
| `purchase_journey_stage` | `string` |  | Where the observed audience sits in a purchase journey, derived from speech context. Omitted when no stage was inferred. |
| `purchase_journey_urgency` | `string` |  | Urgency signal accompanying `purchase_journey_stage`. Omitted when no stage was inferred. |
| `canonical_brand_matches` | array of `string` |  | De-duplicated canonical brand names matched from speech evidence. Presence of a competitor brand is a conquesting opportunity. Omitted when no brand was matched. |
| `signal_derived` | `object` |  | Camera-less derived audience signals, carried alongside the IAB and Trillboards segment sets. Present only when derived signals exist for the screen AND the request is not a clean curated-wire request. |
| `agent_endpoint` | `string` |  | AI-agent discovery: the Trillboards MCP endpoint, so a DSP's agent can negotiate directly from the bid stream. Constant for all requests. |
| `adcp_discovery` | `string` |  | AI-agent discovery: the AdCP `adagents.json` document. Constant for all requests. |


```json
{
  "attention_score": 0.87,
  "audience_count": 8,
  "crowd_density": 12,
  "ad_receptivity": 0.75,
  "emotional_engagement": 0.82,
  "mood": "happy",
  "estimated_occupancy": 25,
  "avg_dwell_ms": 4500,
  "group_composition": {
    "solo": 3
  },
  "screen_engagement": "active",
  "audience_reaction": "positive",
  "signals_age_ms": 12480
}
```


### User


User object carrying the screen's audience segments. The
trillboards-audience segments are read from the per-person records the
screen keeps for the people its camera detects. Trillboards recognises
the same person across screens and days and links people to device
keys and mobile advertising IDs.



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `data` | array of [`UserData`](#userdata) |  |  |


### UserData


IAB Audience Taxonomy 1.1 segments and seller-defined context segments.
Three data sources may be present in user.data[]:

1. **trillboards-audience**: Real-time audience segments from FEIN edge AI
2. **trillboards-census**: US Census ACS neighborhood demographics
3. **trillboards-seller-defined**: Seller-defined context segments (venue, traffic, dwell, daypart)



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | `string` — one of `trillboards-audience`, `trillboards-census`, `trillboards-seller-defined` |  | Data provider identifier |
| `name` | `string` |  | Human-readable data source name |
| `segment` | array of [`Segment`](#segment) |  |  |
| `ext` | `object` |  |  |


### VASExt


Verified Attention Seconds — historical attention quality metrics
for this screen. Based on 7-day rolling data from the attention_ledger.

VAS = face_count * attention_score * dwell_seconds. It captures the TOTAL
attention delivered, not just whether someone was present. A screen with
3 attentive viewers for 10 seconds scores higher than 10 distracted
viewers for 1 second.



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `pricing_model` | `string` — one of `vas` |  | Always "vas" — indicates attention-based pricing is available |
| `predicted_vas` | `number` |  | Predicted VAS for the next impression based on historical patterns |
| `vas_7d` | `number` |  | Average VAS (Viewable Attention Score) over the past 7 days. (Field renamed 2026-05 from `historical_vas_avg` to align with the buyer-facing field name on /adslots — partners migrating from a stale spec should rename their parser key.) |
| `median_vas` | `number` |  | Median VAS (more robust to outliers than mean) |
| `p90_vas` | `number` |  | 90th percentile VAS — the quality floor for top 10% of measurements |
| `vas_floor` | `number` |  | Minimum VAS threshold for quality-gated pricing |
| `vas_measurements_7d` | `integer` |  | Number of VAS measurements in the past 7 days (data density) |
| `avg_face_count` | `number` |  | Average face count across measurements |
| `avg_attention_score` | `number` |  | Average attention score across measurements |
| `last_measurement` | `string` |  | Timestamp of most recent VAS measurement |


### VenueExt


Venue quality and neighborhood context for the screen's location.

Every field is omitted unless it carries positive value — a zero or
`unknown` is dropped rather than broadcast, because a zero on the bid
stream reads as "worthless" and suppresses bids. An absent field means
"not known", not "scored zero".



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `price_level` | `integer` |  | Venue price tier (0 = cheapest, 4 = most expensive) |
| `rating` | `number` |  | Venue rating on a 5-point scale |
| `quality_score` | `number` |  | Composite venue quality score. Omitted when not positive. |
| `neighborhood_class` | `string` |  | Neighborhood classification for the surrounding area. Omitted when unknown (the literal `unknown` is never sent). |
| `amenity_density` | `number` |  | Density of nearby amenities (retail, dining, transit) around the screen. Omitted when not positive. |


### WeatherExt


Contextual weather data for the screen's location.
Cached in Redis with 60-minute TTL from WeatherAPI.com.
DSPs use weather for contextual targeting (e.g., ice cream ads when hot,
umbrella ads when raining).



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `temp_f` | `number` |  | Current temperature in Fahrenheit |
| `feels_like_f` | `number` |  | Feels-like temperature accounting for humidity and wind chill |
| `humidity` | `number` |  | Relative humidity percentage (0-100) |
| `condition` | `string` |  | Weather condition description |
| `uv_index` | `number` |  | UV index (0-11+) |
| `wind_mph` | `number` |  | Wind speed in miles per hour |
| `is_raining` | `boolean` |  | Whether it is currently raining at the screen location |
| `temp_segment` | `string` — one of `hot`, `warm`, `cool`, `cold` |  | Temperature classification for easy targeting: - hot: >= 85F - warm: 65-84F - cool: 45-64F - cold: < 45F |


```json
{
  "temp_f": 85,
  "feels_like_f": 88,
  "humidity": 75,
  "condition": "Partly cloudy",
  "uv_index": 8,
  "wind_mph": 12,
  "is_raining": false,
  "temp_segment": "hot"
}
```

---

# Attribution data models
# Source: https://api.trillboards.com/docs/guides/attribution-data-models.md

# Trillboards Attribution Data Model Ontology

`version 1.0.0`


Machine-readable schema definitions for the 6-layer DOOH attribution data model.
These schemas map directly to PostgreSQL tables created in migrations 092-096.

## Data Flow: From Signal to Insight

```
Layer 1: Signal Ingestion
  device_signals (Intuizi mobile pings) + poi_reference (brand locations)
      |
Layer 2: Exposure Matching
  exposure_device_matches (PostGIS ST_DWithin: device near screen during ad play)
      |
Layer 3: Attention Enrichment
  attention_exposure_matches (FEIN edge AI: face count, gaze, emotion per exposure)
      |
Layer 4: Identity Resolution
  identity_nodes + identity_edges + household_clusters (cross-device graph)
      |
Layer 5: Attribution
  touchpoint_events + attribution_chains (multi-touch credit across channels)
      |
Layer 6: Measurement
  incrementality_experiments + incrementality_results (Bayesian uplift)
  creative_attribution_performance (creative x outcome correlation)
  campaign_attribution_summary (daily rollup)
```

## Data Handling

- Attribution tables key each mobile device by a hash of its MAID (`maid_hash`). The identity graph links MAIDs to the device keys sensed at screens and, through them, to the person identifiers built from face-identity templates
- FEIN inference runs on the device. The screen sends Trillboards a record for each detected person, speech transcripts, the radio identifiers of nearby devices and its GPS position, and sends selected camera frames for cloud analysis
- Attribution tables join hashed MAIDs, with each device's location at the time of the match, to screen exposures
- Partitioned tables with 90-400 day retention and automatic partition pruning; Trillboards' encrypted archive keeps the data with no scheduled deletion

## Partitioning Strategy

Three tables are range-partitioned by timestamp for performance:
- `device_signals` — partitioned by `observed_at` (monthly, 90-day hot)
- `device_visitation` — partitioned by `visited_at` (monthly, 90-day hot)
- `exposure_device_matches` — partitioned by `matched_at` (monthly, 400-day)
- `attention_exposure_matches` — partitioned by `matched_at` (monthly)
- `touchpoint_events` — partitioned by `occurred_at` (monthly)



---

## Schemas

16 schemas. 
Every one is derived from `docs/openapi/attribution-data-models.yaml` at request time.


[`AttentionCampaignMetrics`](#attentioncampaignmetrics) · [`AttentionExposureMatch`](#attentionexposurematch) · [`AttributionChain`](#attributionchain) · [`CampaignAttributionSummary`](#campaignattributionsummary) · [`CreativeAttributionPerformanceRecord`](#creativeattributionperformancerecord) · [`DataProviderIngestionLog`](#dataprovideringestionlog) · [`DeviceSignal`](#devicesignal) · [`DeviceVisitation`](#devicevisitation) · [`ExposureDeviceMatch`](#exposuredevicematch) · [`HouseholdCluster`](#householdcluster) · [`IdentityEdge`](#identityedge) · [`IdentityNode`](#identitynode) · [`IncrementalityExperiment`](#incrementalityexperiment) · [`IncrementalityResultRecord`](#incrementalityresultrecord) · [`POIReference`](#poireference) · [`TouchpointEvent`](#touchpointevent)


### AttentionCampaignMetrics


Daily rollup of attention-weighted campaign metrics.
One row per campaign + creative + date. Used for aCPM calculations
and attention timeseries visualizations.

**Table**: `attention_campaign_metrics`
**Migration**: `243_create_attention_attribution_tables.sql`



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `metric_id` | `integer` |  |  |
| `campaign_id` | `string` |  |  |
| `creative_id` | `string`, nullable |  |  |
| `advertiser_id` | `string`, nullable |  |  |
| `metric_date` | `string` |  |  |
| `total_impressions` | `integer` |  |  |
| `unique_devices` | `integer` |  |  |
| `total_attention_seconds` | `number` |  | Sum of (attention_score * dwell_seconds * face_count) across all impressions |
| `avg_attention_score` | `number` |  |  |
| `median_attention_score` | `number` |  |  |
| `p90_attention_score` | `number` |  |  |
| `avg_dwell_seconds` | `number` |  |  |
| `avg_face_count` | `number` |  |  |
| `standard_cpm` | `number` |  | Traditional CPM (cost / impressions * 1000) |
| `attention_cpm` | `number` |  | aCPM = cost / (total_attention_seconds / 1000) |
| `cost_per_attentive_reach` | `number` |  |  |
| `cost_per_attentive_visit` | `number` |  |  |
| `avg_emotion_engagement` | `number` |  |  |
| `positive_emotion_pct` | `number` |  | Percentage of impressions with happy/surprised/interested emotions |
| `attention_qualified_pct` | `number` |  | Percentage of impressions with attention_score >= 0.5 |
| `daypart_breakdown` | `object` |  |  |
| `emotion_breakdown` | `object` |  |  |
| `venue_type_breakdown` | `object` |  |  |


### AttentionExposureMatch


Exposure match enriched with FEIN edge AI inference signals.
Joins exposure_device_matches with inference_outcomes to attach
attention, emotion, and demographic data to each exposure.

What the row MODELS, stated precisely: a device-to-play match from
`exposure_device_matches`, carrying the edge-AI inference recorded for
that play — face count, gaze, emotion classification and dwell. It is a
join, not an independent observation: the exposure leg and the attention
leg are produced by different subsystems, and a row exists only where
both fired for the same play.

Population is a property of the deployment, not of the schema. Before
building on any field here, count the table for your own environment and
check `matched_at` freshness — a schema contract cannot tell you whether
the pipeline that fills it is running.

**Table**: `attention_exposure_matches` (partitioned monthly by `matched_at`)
**Migration**: `243_create_attention_attribution_tables.sql`



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `match_id` | `integer` |  |  |
| `play_id` | `string` |  |  |
| `maid_hash` | `string` |  |  |
| `campaign_id` | `string`, nullable |  |  |
| `creative_id` | `string`, nullable |  |  |
| `screen_mongo_id` | `string` |  |  |
| `face_count` | `integer`, nullable |  | Number of faces detected during this ad play |
| `attention_score` | `number`, nullable |  | Fraction of faces looking at screen (0.0-1.0) |
| `emotion_score` | `number`, nullable |  | Emotional engagement intensity (0.0-1.0) |
| `dominant_emotion` | `string`, nullable |  | Most common emotion detected (happy, surprised, neutral, etc.) |
| `dwell_seconds` | `number`, nullable |  | How long faces were visible in the camera FOV |
| `engagement_score` | `number`, nullable |  | Body engagement from FEIN (posture, orientation) |
| `demographics_age` | `string`, nullable |  | Age bucket estimate (e.g., '25-34'). |
| `demographics_gender` | `string`, nullable |  | Gender estimate (male/female/unknown). |
| `base_confidence` | `number` |  | Original confidence from exposure_device_matches |
| `attention_weight` | `number` |  | Attention weight factor (0-1). Derived from attention_score, face_count, and dwell_seconds. Used to compute weighted_confidence. |
| `weighted_confidence` | `number` |  | base_confidence * (1 + attention_weight). This is the DEFINITIVE confidence score for this exposure. Higher = more certain the person saw AND paid attention to the ad. |
| `venue_type` | `string`, nullable |  |  |
| `daypart` | `string`, nullable |  |  |
| `weather` | `string`, nullable |  |  |
| `ambient_lux` | `number`, nullable |  | Ambient light level at the screen location |
| `matched_at` | `string` |  |  |


### AttributionChain


Complete user journey from DOOH exposure to conversion.
Links multiple touchpoint_events into a sequence with
multi-touch credit allocation.

**Table**: `attribution_chains`
**Migration**: 096



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `chain_id` | `string` |  |  |
| `campaign_id` | `string` |  |  |
| `advertiser_id` | `string` |  |  |
| `maid_hash` | `string`, nullable |  |  |
| `household_id` | `string`, nullable |  |  |
| `touchpoint_count` | `integer` |  | Number of touchpoints in this journey |
| `channels` | array of `string` |  | Ordered list of channels in the journey |
| `first_touch_at` | `string` |  |  |
| `last_touch_at` | `string` |  |  |
| `conversion_at` | `string`, nullable |  | When conversion occurred (store visit, purchase, etc.) |
| `conversion_type` | `string`, nullable |  |  |
| `dooh_credit` | `number` |  | Fraction of conversion credit attributed to DOOH (0-1) |
| `mobile_credit` | `number` |  |  |
| `web_credit` | `number` |  |  |
| `store_credit` | `number` |  |  |
| `attribution_model` | `string` — one of `time_decay`, `position_based`, `attention_weighted`, `shapley` |  |  |
| `conversion_value_cents` | `integer`, nullable |  |  |
| `attributed_revenue_cents` | `integer`, nullable |  |  |
| `total_confidence` | `number`, nullable |  |  |
| `is_deterministic` | `boolean` |  | Whether all identity links are deterministic (vs probabilistic) |


### CampaignAttributionSummary


Daily rollup of campaign-level attribution metrics.
This is the aggregate view consumed by the campaign summary endpoint.

**Table**: `campaign_attribution_summary`
**Migration**: 093



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `summary_id` | `integer` |  |  |
| `campaign_id` | `string` |  |  |
| `advertiser_id` | `string` |  |  |
| `summary_date` | `string` |  |  |
| `cohort_id` | `string`, nullable |  |  |
| `unique_devices_exposed` | `integer` |  |  |
| `total_exposures` | `integer` |  |  |
| `avg_frequency` | `number` |  |  |
| `total_media_cost` | `number` |  |  |
| `cost_per_unique_reach` | `number` |  |  |
| `exposed_visitors` | `integer` |  |  |
| `control_visitors` | `integer` |  |  |
| `exposed_visit_rate` | `number` |  |  |
| `control_visit_rate` | `number` |  |  |
| `incremental_lift_pct` | `number` |  |  |
| `incremental_visits` | `integer` |  |  |
| `cost_per_incremental_visit` | `number` |  |  |
| `control_group_size` | `integer` |  |  |
| `avg_match_confidence` | `number` |  |  |
| `statistical_significance` | `number` |  |  |
| `avg_time_to_visit_h` | `number` |  |  |
| `venue_breakdown` | `object` |  |  |
| `daypart_breakdown` | `object` |  |  |
| `attribution_window_days` | `integer` |  |  |


### CreativeAttributionPerformanceRecord


Links creative execution to attribution outcomes.
One row per campaign + creative + variant + date.

Answers: "Which creative x venue x daypart x weather combination
drives the most store visits at the lowest cost?"

**Table**: `creative_attribution_performance`
**Migration**: 096



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `perf_id` | `integer` |  |  |
| `campaign_id` | `string` |  |  |
| `creative_id` | `string` |  |  |
| `variant` | `string`, nullable |  |  |
| `metric_date` | `string` |  |  |
| `avg_attention_score` | `number` |  |  |
| `avg_dwell_seconds` | `number` |  |  |
| `avg_emotion_engagement` | `number` |  |  |
| `dominant_emotion` | `string`, nullable |  |  |
| `store_visits` | `integer` |  |  |
| `visit_rate` | `number` |  |  |
| `incremental_lift_pct` | `number` |  |  |
| `cost_per_visit` | `number` |  |  |
| `best_venue_type` | `string`, nullable |  |  |
| `best_daypart` | `string`, nullable |  |  |
| `best_weather` | `string`, nullable |  |  |
| `context_performance` | `object` |  | Detailed breakdown by context interaction |


### DataProviderIngestionLog


Audit trail for batch data ingestion runs.
Tracks file processing status, row counts, and rejection reasons.

**Table**: `data_provider_ingestion_log`
**Migration**: 092



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `log_id` | `integer` |  |  |
| `provider` | `string` |  |  |
| `file_type` | `string` |  |  |
| `s3_bucket` | `string` |  |  |
| `s3_key` | `string` |  |  |
| `file_size_bytes` | `integer` |  |  |
| `rows_total` | `integer` |  |  |
| `rows_inserted` | `integer` |  |  |
| `rows_rejected` | `integer` |  |  |
| `rejection_reasons` | `object` |  |  |
| `status` | `string` — one of `pending`, `processing`, `completed`, `failed` |  |  |
| `error_message` | `string`, nullable |  |  |
| `started_at` | `string`, nullable |  |  |
| `completed_at` | `string`, nullable |  |  |


### DeviceSignal


Mobile device location observation from Intuizi.
Each row = one device location ping (MAID + lat/lng + timestamp).
MAIDs are stored as SHA-256 hashes (`maid_hash`).

**Table**: `device_signals` (partitioned monthly by `observed_at`)
**Migration**: 092



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `signal_id` | `integer` |  | Auto-incrementing primary key |
| `maid_hash` | `string` |  | SHA-256 hash of the mobile advertising ID (IDFA/GAID) |
| `location` | `string` |  | PostGIS GEOGRAPHY(POINT, 4326) — used for ST_DWithin spatial joins |
| `latitude` | `number` |  |  |
| `longitude` | `number` |  |  |
| `accuracy_m` | `number` |  | GPS accuracy in meters (lower = more precise) |
| `geohash_6` | `string` |  | Geohash-6 cell for fast spatial pruning before PostGIS join |
| `observed_at` | `string` |  | When the device was observed at this location (partition key) |
| `provider` | `string` |  | Data provider name |
| `signal_type` | `string` — one of `location`, `visitation`, `beacon` |  |  |
| `device_os` | `string` — one of `ios`, `android`, `unknown` |  |  |
| `dma_code` | `string`, nullable |  | Nielsen DMA code for geo-holdout experiments |
| `ingested_at` | `string` |  |  |
| `batch_id` | `string`, nullable |  | Ingestion batch identifier for audit trail |


### DeviceVisitation


Observed visit to a POI by a mobile device (from Intuizi visitation data).

**This table holds TWO different attribution legs and `visit_role` is the
discriminator. Always filter by it.** `conversion_poi` rows are the
*outcome* leg — the device visited the advertiser's location.
`screen_exposure` rows are the *exposure* leg — the device was near one
of our screens. They answer opposite halves of the question, and a query
that omits the predicate silently mixes them.

The column is `NOT NULL DEFAULT 'conversion_poi'` with a CHECK constraint
(migration `20260618061000_add_device_visitation_visit_role.sql`), and the
table carries a dedicated partial index per role, which is the clearest
statement that both are expected to be queried separately.

`visit_role` was absent from this schema entirely until 2026-09-01, so the
document described the whole table as the outcome leg.

**Table**: `device_visitation` (partitioned monthly by `visited_at`)
**Migration**: 092 (`visit_role` added in
`20260618061000_add_device_visitation_visit_role.sql`)



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `visit_role` | `string` — one of `conversion_poi`, `screen_exposure` |  | Which attribution leg this row belongs to. `NOT NULL`, defaulting to `conversion_poi`. Filter on it in every query — see the schema description above. |
| `visitation_id` | `integer` |  |  |
| `maid_hash` | `string` |  |  |
| `poi_id` | `string` |  | References poi_reference.poi_id |
| `external_poi_id` | `string` |  |  |
| `distance_m` | `number` |  | Distance from device to POI centroid in meters |
| `dwell_seconds` | `integer` |  | How long the device stayed at the POI |
| `visited_at` | `string` |  | When the visit occurred (partition key) |
| `provider` | `string` |  |  |
| `confidence` | `number` |  | Visit confidence score (0-1) |
| `ingested_at` | `string` |  |  |
| `batch_id` | `string`, nullable |  |  |


### ExposureDeviceMatch


Core truth table: device X was near screen Y during ad play Z.
Created by the exposure matching service using PostGIS ST_DWithin
to join device_signals with play_logs based on spatial and temporal proximity.

**Table**: `exposure_device_matches` (partitioned monthly by `matched_at`)
**Migration**: 093



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `match_id` | `integer` |  |  |
| `play_id` | `string` |  | References play_logs — which ad was playing |
| `maid_hash` | `string` |  | SHA-256 hashed MAID of the device |
| `screen_mongo_id` | `string` |  | Screen identifier |
| `campaign_id` | `string`, nullable |  |  |
| `creative_id` | `string`, nullable |  |  |
| `advertiser_id` | `string`, nullable |  |  |
| `distance_m` | `number` |  | Distance between device and screen in meters |
| `time_delta_s` | `integer` |  | Seconds between device observation and ad play |
| `device_accuracy_m` | `number`, nullable |  |  |
| `screen_latitude` | `number` |  |  |
| `screen_longitude` | `number` |  |  |
| `device_latitude` | `number` |  |  |
| `device_longitude` | `number` |  |  |
| `confidence_score` | `number` |  | Match confidence (0-1). Based on inverse distance and time delta. Closer + more simultaneous = higher confidence. |
| `match_method` | `string` |  | Matching algorithm used |
| `venue_type` | `string`, nullable |  |  |
| `screen_type` | `string`, nullable |  |  |
| `matched_at` | `string` |  | Timestamp of the match (partition key) |


### HouseholdCluster


Pre-computed household grouping from co-location analysis.
Multiple MAIDs that consistently appear at the same location
(same geohash, same time windows) are clustered into households.

**Table**: `household_clusters`
**Migration**: `243_create_attention_attribution_tables.sql`



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `cluster_id` | `string` |  |  |
| `household_node_id` | `string` |  | References identity_nodes (node_type = 'household') |
| `maid_hash` | `string` |  |  |
| `cluster_confidence` | `number` |  | Confidence that this MAID belongs to this household (0-1) |
| `colocation_count` | `integer` |  | Number of times this MAID was co-located with household members |
| `colocation_days` | `integer` |  | Number of distinct days with co-location observations |
| `device_os` | `string`, nullable |  |  |
| `dma_code` | `string`, nullable |  |  |
| `first_colocated` | `string`, nullable |  |  |
| `last_colocated` | `string`, nullable |  |  |


### IdentityEdge


Relationship between two identity nodes in the graph.

**Table**: `identity_edges`
**Migration**: `243_create_attention_attribution_tables.sql`



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `edge_id` | `string` |  |  |
| `source_node_id` | `string` |  |  |
| `target_node_id` | `string` |  |  |
| `edge_type` | `string` — one of `household_member`, `fein_observation`, `cross_channel_link`, `ip_colocation`, `device_graph_partner`, `wifi_colocation`, `device_signal`, `pixel_ip_bridge`, … (18 total) |  | Relationship type. This list is the FULL `identity_edges_edge_type_check` constraint as of migration `20260621000800_add_maid_bridge_edge_type.sql`. It previously declared five values; thirteen were missing, and the omitted set includes the edge types that carry the overwhelming majority of the table. - household_member: Devices in the same household (co-location evidence) - fein_observation: Devices seen together by FEIN cameras - cross_channel_link: MAID matched to pixel visitor or transaction - ip_colocation: Devices sharing the same IP address - device_graph_partner: Third-party device graph match - wifi_colocation: Devices seen on the same Wi-Fi BSSID - device_signal: Link asserted by a device-reported signal - pixel_ip_bridge: Pixel visitor joined to a device by IP - temporal_fingerprint: Devices linked by co-occurrence in time - email_hash_link: Link through a hashed email address - uid2_token: Link through a UID2 token - qr_scan: Link established by a QR scan - ble_proximity: Bluetooth-LE proximity between devices - network_device: Devices on the same network - pixel_match: Direct pixel-to-identity match - csi_proximity: Proximity from the Wi-Fi CSI radio path - maid_bridge: PROBABILISTIC bridge between co-present MAIDs - face_device: Face cluster linked to a device `confidence` is not comparable across edge types. `maid_bridge` in particular is derived as 1/N over co-present MAIDs and capped at 0.5, so a 0.5 there is the CEILING of a probabilistic inference, not the same quantity as a 0.5 on a deterministic edge. |
| `confidence` | `number` |  | Edge confidence (0-1). Higher = stronger evidence of relationship. |
| `evidence_count` | `integer` |  | Number of independent observations supporting this edge |
| `evidence_type` | `string`, nullable |  |  |
| `first_linked_at` | `string` |  |  |
| `last_linked_at` | `string` |  |  |
| `metadata` | `object` |  |  |


### IdentityNode


Vertex in the identity graph. Each node represents a device, household,
FEIN cluster, pixel visitor, or other identity type.

**Table**: `identity_nodes`
**Migration**: `243_create_attention_attribution_tables.sql`



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `node_id` | `string` |  |  |
| `node_type` | `string` — one of `maid`, `household`, `fein_cluster`, `ip_hash`, `wifi_bssid`, `fingerprint`, `pixel_id`, `transaction_id`, … (15 total) |  | Type of identity. This list is the FULL `identity_nodes_node_type_check` constraint as of migration `20260727191655_canonical_device_extended_identities.sql`. It previously declared six values; nine were missing, including the three that carry most of the table. - maid: Mobile advertising ID (hashed) - household: Inferred household from co-location analysis - fein_cluster: Group of devices observed together by FEIN cameras - ip_hash: Hashed IP for coarse identity linking - wifi_bssid: Hashed Wi-Fi BSSID observed near a screen - fingerprint: Browser/device fingerprint - pixel_id: Web conversion pixel visitor - transaction_id: Purchase event identifier - email_hash: Hashed email address - qr_fingerprint: Fingerprint derived from a QR scan - csi_device: Device sensed by the Wi-Fi CSI radio path - screen: A Trillboards screen, as a node in the graph - canonical_visitor: The resolved visitor a cluster collapses to - face_cluster: Camera-derived face cluster - uid2_token: UID2 token `identifier_hash` is an HMAC-SHA256 keyed by `pepper_kid`, not a bare SHA-256 — you cannot reproduce it from the raw identifier alone. |
| `identifier_hash` | `string` |  | SHA-256 hash of the actual identifier |
| `device_os` | `string` — one of `ios`, `android`, `unknown` |  |  |
| `dma_code` | `string`, nullable |  |  |
| `geohash_6` | `string`, nullable |  |  |
| `first_seen_at` | `string` |  |  |
| `last_seen_at` | `string` |  |  |
| `signal_count` | `integer` |  | Number of times this identity has been observed |
| `metadata` | `object` |  |  |


### IncrementalityExperiment


Experiment definition for causal incrementality measurement.
Supports geo-holdout, ghost ads, PSA control, and matched market designs.

**Table**: `incrementality_experiments`
**Migration**: 096



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `experiment_id` | `string` |  |  |
| `campaign_id` | `string` |  |  |
| `advertiser_id` | `string` |  |  |
| `experiment_type` | `string` — one of `geo_holdout`, `ghost_ad`, `psa_control`, `matched_market` |  |  |
| `status` | `string` — one of `draft`, `active`, `measuring`, `completed`, `cancelled` |  |  |
| `treatment_dmas` | array of `string` |  | DMA codes where ads are shown |
| `control_dmas` | array of `string` |  | DMA codes where ads are withheld |
| `holdout_pct` | `number` |  |  |
| `required_sample_size` | `integer`, nullable |  |  |
| `target_mde` | `number` |  | Minimum detectable effect (10% = can detect a 10% lift) |
| `target_power` | `number` |  |  |
| `target_alpha` | `number` |  |  |
| `matching_covariates` | `object` |  | Covariates used for propensity score matching |
| `caliper_width` | `number` |  |  |
| `started_at` | `string`, nullable |  |  |
| `ended_at` | `string`, nullable |  |  |


### IncrementalityResultRecord


Daily measurement result for an incrementality experiment.
Contains both Bayesian and frequentist statistical results.

**Table**: `incrementality_results`
**Migration**: 096



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `result_id` | `integer` |  |  |
| `experiment_id` | `string` |  |  |
| `measurement_date` | `string` |  |  |
| `treatment_devices` | `integer` |  |  |
| `treatment_visitors` | `integer` |  |  |
| `treatment_visit_rate` | `number` |  |  |
| `control_devices` | `integer` |  |  |
| `control_visitors` | `integer` |  |  |
| `control_visit_rate` | `number` |  |  |
| `absolute_lift` | `number` |  |  |
| `relative_lift_pct` | `number` |  |  |
| `incremental_visits` | `integer` |  |  |
| `chi_square` | `number` |  |  |
| `p_value` | `number` |  |  |
| `confidence_interval_lower` | `number` |  |  |
| `confidence_interval_upper` | `number` |  |  |
| `posterior_prob_positive` | `number` |  | Bayesian P(lift > 0) |
| `expected_uplift` | `number` |  |  |
| `credible_interval_lower` | `number` |  |  |
| `credible_interval_upper` | `number` |  |  |
| `avg_propensity_treatment` | `number` |  |  |
| `avg_propensity_control` | `number` |  |  |
| `standardized_mean_diff` | `number` |  | Should be < 0.1 for good covariate balance |


### POIReference


Advertiser/brand point-of-interest location from Intuizi.
Used as the "destination" in footfall attribution — did an exposed device
later visit one of these POIs?

The catalogue is scoped to the brands under active measurement, not to
Intuizi's whole POI universe. A volume figure is deliberately not quoted
here: this document is a schema contract, and the previous "~500K
locations" parenthetical overstated the live table by more than an order
of magnitude. Count `poi_reference` if you need the current size.

**Table**: `poi_reference`
**Migration**: 092



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `poi_id` | `string` |  |  |
| `external_id` | `string` |  | Provider's unique identifier |
| `name` | `string` |  | Location name (e.g., "Starbucks - 42nd & Broadway") |
| `brand` | `string`, nullable |  | Brand name (e.g., "Starbucks") |
| `category` | `string` |  | Business category (e.g., "coffee_shop", "gym", "retail") |
| `subcategory` | `string`, nullable |  |  |
| `address` | `string`, nullable |  |  |
| `city` | `string`, nullable |  |  |
| `state` | `string`, nullable |  |  |
| `zip` | `string`, nullable |  |  |
| `dma_code` | `string`, nullable |  |  |
| `location` | `string` |  | PostGIS GEOGRAPHY(POINT, 4326) |
| `latitude` | `number` |  |  |
| `longitude` | `number` |  |  |
| `geohash_6` | `string` |  |  |
| `provider` | `string` |  |  |
| `status` | `string` |  |  |
| `metadata` | `object` |  | Flexible JSON metadata |


### TouchpointEvent


Normalized cross-channel event from any attribution source.
All channels (DOOH, mobile, web, app, store, purchase) are
represented in a single table for unified multi-touch attribution.

**Table**: `touchpoint_events` (partitioned monthly by `occurred_at`)
**Migration**: 096



| Property | Type | Required | Description |
| --- | --- | --- | --- |
| `touchpoint_id` | `string` |  |  |
| `maid_hash` | `string`, nullable |  |  |
| `household_id` | `string`, nullable |  |  |
| `pixel_visitor_id` | `string`, nullable |  | SHA-256(IP+UA) for web pixel visitors |
| `channel` | `string` — one of `dooh`, `mobile_ad`, `web_visit`, `app_install`, `store_visit`, `purchase` |  |  |
| `event_type` | `string` |  | Event subtype (impression, click, pixel_fire, transaction, etc.) |
| `play_id` | `string`, nullable |  | DOOH-specific — which ad play triggered this event |
| `screen_mongo_id` | `string`, nullable |  |  |
| `campaign_id` | `string`, nullable |  |  |
| `creative_id` | `string`, nullable |  |  |
| `advertiser_id` | `string`, nullable |  |  |
| `confidence_score` | `number`, nullable |  |  |
| `dsp_partner` | `string`, nullable |  | DSP name for mobile/digital events |
| `placement_id` | `string`, nullable |  |  |
| `click_url` | `string`, nullable |  |  |
| `poi_id` | `string`, nullable |  |  |
| `transaction_amount_cents` | `integer`, nullable |  |  |
| `basket_items` | array of `object` |  |  |
| `latitude` | `number`, nullable |  |  |
| `longitude` | `number`, nullable |  |  |
| `dma_code` | `string`, nullable |  |  |
| `occurred_at` | `string` |  | When the event happened (partition key) |
| `attributed` | `boolean` |  | Whether this event has been assigned to an attribution chain |
| `attribution_chain_id` | `string`, nullable |  |  |

---

# curl
# Source: https://api.trillboards.com/docs/guides/examples/curl.md

# curl example

End-to-end partner flow as a shell script.

Source: `trillboard-api/docs/examples/curl/quick-start.sh`

```bash
#!/bin/bash
#
# Trillboards Partner API - curl Quick Start
#
# This script demonstrates the 3-step integration:
# 1. Get VAST configuration (cache for 1 hour)
# 2. Fetch VAST from Google Ad Manager (Trillboards not in critical path)
# 3. Report impressions after ad completion
#
# Usage:
#   export TRILLBOARDS_API_KEY=trb_partner_xxx
#   ./quick-start.sh
#

set -e

API_BASE="${TRILLBOARDS_API_URL:-https://api.trillboards.com}"
API_KEY="${TRILLBOARDS_API_KEY}"

if [ -z "$API_KEY" ]; then
    echo "Error: Set TRILLBOARDS_API_KEY environment variable"
    exit 1
fi

echo "=========================================="
echo "Trillboards Partner API - Quick Start"
echo "=========================================="
echo ""

# Step 1: Get VAST configuration
echo "1. Fetching VAST configuration..."
echo ""
CONFIG=$(curl -s -H "Authorization: Bearer $API_KEY" \
    "$API_BASE/v1/partner/vast/config")

echo "Response:"
echo "$CONFIG" | jq '.' 2>/dev/null || echo "$CONFIG"
echo ""

# Extract VAST tag URL (requires jq)
if command -v jq &> /dev/null; then
    VAST_URL=$(echo "$CONFIG" | jq -r '.data.vast_tag_template // "N/A"')
    echo "VAST Tag URL: $VAST_URL"
fi
echo ""

# Step 2: In production, your player fetches VAST directly from Google
echo "2. Your player fetches VAST directly from Google Ad Manager"
echo "   (Google IMA SDK handles this - Trillboards not in critical path)"
echo ""

# Step 3: Report impression
echo "3. Reporting impression after ad completion..."
echo ""
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")

RESULT=$(curl -s -X POST \
    -H "Authorization: Bearer $API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
        \"impressions\": [{
            \"device_id\": \"demo-device-001\",
            \"ad_id\": \"ima_demo_ad_123\",
            \"event\": \"complete\",
            \"timestamp\": \"$TIMESTAMP\",
            \"duration_ms\": 15000
        }]
    }" \
    "$API_BASE/v1/partner/tracking/batch")

echo "Response:"
echo "$RESULT" | jq '.' 2>/dev/null || echo "$RESULT"
echo ""

echo "=========================================="
echo "Integration complete!"
echo "=========================================="
```

---

# Node.js
# Source: https://api.trillboards.com/docs/guides/examples/node.md

# Node.js example

End-to-end partner flow with the built-in fetch.

Source: `trillboard-api/docs/examples/node/quick-start.js`

```javascript
/**
 * Trillboards Partner API - Node.js Quick Start
 *
 * This example demonstrates the 3-step integration:
 * 1. Get VAST configuration (cache for 1 hour)
 * 2. Fetch VAST from Google Ad Manager (Trillboards not in critical path)
 * 3. Report impressions after ad completion
 *
 * Usage:
 *   TRILLBOARDS_API_KEY=trb_partner_xxx node quick-start.js
 */

const TRILLBOARDS_API = process.env.TRILLBOARDS_API_URL || 'https://api.trillboards.com';
const API_KEY = process.env.TRILLBOARDS_API_KEY;

if (!API_KEY) {
  console.error('Error: Set TRILLBOARDS_API_KEY environment variable');
  process.exit(1);
}

const headers = {
  'Authorization': `Bearer ${API_KEY}`,
  'Content-Type': 'application/json'
};

async function main() {
  try {
    // Step 1: Get VAST configuration (cache this for 1 hour)
    console.log('1. Fetching VAST configuration...');
    const configResponse = await fetch(`${TRILLBOARDS_API}/v1/partner/vast/config`, {
      headers
    });
    const config = await configResponse.json();

    if (!config.success) {
      throw new Error(`Config failed: ${config.message}`);
    }

    console.log('   VAST tag URL:', config.data.vast_tag_template);
    console.log('   Fill rate:', config.data.estimated_fill_rate);

    // Step 2: In production, your player fetches VAST directly from Google
    // This keeps Trillboards out of the critical ad serving path
    const vastUrl = config.data.vast_tag_template
      .replace('[DEVICE_ID]', 'demo-device-001')
      .replace('[TIMESTAMP]', Date.now());

    console.log('\n2. Your player would fetch VAST from:', vastUrl);
    console.log('   (Google IMA SDK handles this automatically)');

    // Step 3: After ad completes, report the impression
    console.log('\n3. Reporting impression after ad completion...');
    const trackingResponse = await fetch(`${TRILLBOARDS_API}/v1/partner/tracking/batch`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        impressions: [{
          device_id: 'demo-device-001',
          ad_id: 'ima_demo_ad_123',
          event: 'complete',
          timestamp: new Date().toISOString(),
          duration_ms: 15000
        }]
      })
    });
    const result = await trackingResponse.json();

    console.log('   Processed:', result.data?.processed || 0);
    console.log('   Proofs:', result.data?.proofs?.length || 0, 'Ed25519 signatures');

    console.log('\nIntegration complete! Your screens are now monetized.');

  } catch (error) {
    console.error('Error:', error.message);
    process.exit(1);
  }
}

main();
```

---

# Python
# Source: https://api.trillboards.com/docs/guides/examples/python.md

# Python example

End-to-end partner flow with requests.

Source: `trillboard-api/docs/examples/python/quick_start.py`

```python
#!/usr/bin/env python3
"""
Trillboards Partner API - Python Quick Start

This example demonstrates the 3-step integration:
1. Get VAST configuration (cache for 1 hour)
2. Fetch VAST from Google Ad Manager (Trillboards not in critical path)
3. Report impressions after ad completion

Usage:
    TRILLBOARDS_API_KEY=trb_partner_xxx python quick_start.py
"""

import os
import sys
from datetime import datetime

try:
    import requests
except ImportError:
    print("Error: Install requests library: pip install requests")
    sys.exit(1)

TRILLBOARDS_API = os.environ.get('TRILLBOARDS_API_URL', 'https://api.trillboards.com')
API_KEY = os.environ.get('TRILLBOARDS_API_KEY')

if not API_KEY:
    print('Error: Set TRILLBOARDS_API_KEY environment variable')
    sys.exit(1)

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}


def main():
    # Step 1: Get VAST configuration (cache this for 1 hour)
    print('1. Fetching VAST configuration...')
    config_response = requests.get(
        f'{TRILLBOARDS_API}/v1/partner/vast/config',
        headers=headers
    )
    config = config_response.json()

    if not config.get('success'):
        raise Exception(f"Config failed: {config.get('message')}")

    print(f"   VAST tag URL: {config['data']['vast_tag_template']}")
    print(f"   Fill rate: {config['data'].get('estimated_fill_rate', 'N/A')}")

    # Step 2: In production, your player fetches VAST directly from Google
    # This keeps Trillboards out of the critical ad serving path
    vast_url = config['data']['vast_tag_template'] \
        .replace('[DEVICE_ID]', 'demo-device-001') \
        .replace('[TIMESTAMP]', str(int(datetime.now().timestamp() * 1000)))

    print(f'\n2. Your player would fetch VAST from: {vast_url}')
    print('   (Google IMA SDK handles this automatically)')

    # Step 3: After ad completes, report the impression
    print('\n3. Reporting impression after ad completion...')
    tracking_response = requests.post(
        f'{TRILLBOARDS_API}/v1/partner/tracking/batch',
        headers=headers,
        json={
            'impressions': [{
                'device_id': 'demo-device-001',
                'ad_id': 'ima_demo_ad_123',
                'event': 'complete',
                'timestamp': datetime.utcnow().isoformat() + 'Z',
                'duration_ms': 15000
            }]
        }
    )
    result = tracking_response.json()

    processed = result.get('data', {}).get('processed', 0)
    proofs = len(result.get('data', {}).get('proofs', []))
    print(f'   Processed: {processed}')
    print(f'   Proofs: {proofs} Ed25519 signatures')

    print('\nIntegration complete! Your screens are now monetized.')


if __name__ == '__main__':
    main()
```

---

# PHP
# Source: https://api.trillboards.com/docs/guides/examples/php.md

# PHP example

A small partner client class.

Source: `trillboard-api/docs/examples/php/TrillboardsPartner.php`

```php
<?php
/**
 * Trillboards Partner API - PHP SDK
 *
 * Lightweight PHP client for Trillboards Partner API.
 * Designed for server-to-server integrations (Tier 1).
 *
 * Usage:
 *   $client = new TrillboardsPartner('trb_partner_xxx');
 *   $config = $client->getVastConfig();
 *   // ... play ad ...
 *   $client->reportImpressions([...]);
 */

class TrillboardsPartner {
    private string $apiKey;
    private string $baseUrl;
    private int $timeout;

    public function __construct(
        string $apiKey,
        string $baseUrl = 'https://api.trillboards.com',
        int $timeout = 30
    ) {
        $this->apiKey = $apiKey;
        $this->baseUrl = rtrim($baseUrl, '/');
        $this->timeout = $timeout;
    }

    /**
     * Get VAST configuration.
     * Cache this response for 1 hour to reduce API calls.
     *
     * @param string|null $deviceId Optional device ID for device-specific config
     * @return array API response with VAST tag URL template
     * @throws Exception On API error
     */
    public function getVastConfig(?string $deviceId = null): array {
        $query = $deviceId ? "?device_id=" . urlencode($deviceId) : "";
        return $this->request('GET', "/v1/partner/vast/config{$query}");
    }

    /**
     * Report batch impressions with cryptographic proofs.
     *
     * @param array $impressions Array of impression objects
     * @return array API response with proofs
     * @throws Exception On API error
     */
    public function reportImpressions(array $impressions): array {
        return $this->request('POST', '/v1/partner/tracking/batch', [
            'impressions' => $impressions
        ]);
    }

    /**
     * Register a new device.
     *
     * @param string $deviceId Unique device identifier
     * @param array $data Optional device data (name, location, etc.)
     * @return array API response with device details
     * @throws Exception On API error
     */
    public function registerDevice(string $deviceId, array $data = []): array {
        return $this->request('POST', '/v1/partner/device', array_merge(
            ['device_id' => $deviceId],
            $data
        ));
    }

    /**
     * Get partner info and stats.
     *
     * @return array API response with partner details
     * @throws Exception On API error
     */
    public function getInfo(): array {
        return $this->request('GET', '/v1/partner/info');
    }

    /**
     * Rotate API key with 24-hour grace period.
     * WARNING: Save the new key immediately - it's only shown once.
     *
     * @return array API response with new API key
     * @throws Exception On API error
     */
    public function rotateApiKey(): array {
        return $this->request('POST', '/v1/partner/api-key/rotate');
    }

    /**
     * Make HTTP request to Trillboards API.
     *
     * @param string $method HTTP method
     * @param string $endpoint API endpoint
     * @param array|null $body Request body for POST/PUT
     * @return array Decoded JSON response
     * @throws Exception On HTTP or API error
     */
    private function request(string $method, string $endpoint, ?array $body = null): array {
        $url = $this->baseUrl . $endpoint;

        $ch = curl_init();
        curl_setopt_array($ch, [
            CURLOPT_URL => $url,
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_TIMEOUT => $this->timeout,
            CURLOPT_HTTPHEADER => [
                'Authorization: Bearer ' . $this->apiKey,
                'Content-Type: application/json',
                'Accept: application/json'
            ]
        ]);

        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            if ($body !== null) {
                curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body));
            }
        }

        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        $error = curl_error($ch);
        curl_close($ch);

        if ($error) {
            throw new Exception("HTTP request failed: {$error}");
        }

        $data = json_decode($response, true);
        if (json_last_error() !== JSON_ERROR_NONE) {
            throw new Exception("Invalid JSON response: " . json_last_error_msg());
        }

        if ($httpCode >= 400) {
            $message = $data['message'] ?? $data['error']['message'] ?? 'Unknown error';
            throw new Exception("API error ({$httpCode}): {$message}");
        }

        return $data;
    }
}

// ==========================================
// Quick Start Example
// ==========================================

if (php_sapi_name() === 'cli' && basename(__FILE__) === basename($argv[0])) {
    $apiKey = getenv('TRILLBOARDS_API_KEY');
    if (!$apiKey) {
        echo "Error: Set TRILLBOARDS_API_KEY environment variable\n";
        exit(1);
    }

    $client = new TrillboardsPartner($apiKey);

    echo "1. Fetching VAST configuration...\n";
    $config = $client->getVastConfig();
    echo "   VAST URL: " . ($config['data']['vast_tag_template'] ?? 'N/A') . "\n\n";

    echo "2. Your player fetches VAST directly from Google\n";
    echo "   (Trillboards not in critical ad serving path)\n\n";

    echo "3. Reporting impression after ad completion...\n";
    $result = $client->reportImpressions([
        [
            'device_id' => 'demo-device-001',
            'ad_id' => 'ima_demo_ad_123',
            'event' => 'complete',
            'timestamp' => gmdate('Y-m-d\TH:i:s\Z'),
            'duration_ms' => 15000
        ]
    ]);
    $processed = $result['data']['processed'] ?? 0;
    $proofs = count($result['data']['proofs'] ?? []);
    echo "   Processed: {$processed}\n";
    echo "   Proofs: {$proofs} Ed25519 signatures\n\n";

    echo "Integration complete! Your screens are now monetized.\n";
}
```