Record beacon

Most integrations should use the hosted renderer first. Hosted renderer beacons are sent automatically to /public/wrapper/v1/beacons after placement.render is mounted.

For clip placements, the hosted renderer emits play_started and play_completed. Direct server integrations can send play_started and play_completed to /v1/beacons when they own a custom clip renderer.

For native and banner placements, render/click/visibility beacons use the same issued asset_token; native click handling is attached to the hosted native frame overlay.

Use direct /v1/beacons only for advanced server-rendered, custom-rendered, or QA flows. Direct server beacons should not be used to fake or duplicate renderer events except for explicit idempotency or QA testing.

Direct server beacons always require the issued asset_token from placement.asset_token or decision.asset_token.

Direct server beacons are diagnostic/non-billable by default unless a trusted measurement policy explicitly allows them.

Accepted renderer diagnostics do not automatically mean proof eligible or billable. Check proof_eligible and billable separately.

INSUFFICIENT_VISIBLE_AREA means the declared creative exists but the measured visible/intersection area was too small, for example because the slot was clipped, cropped, masked, or mostly outside the viewport.

HIDDEN_OR_NOT_VIEWABLE means the renderer evidence indicates display:none, visibility:hidden/collapse, zero/effective opacity, or a hidden/zero-viewable state.

OFFSCREEN means the renderer evidence indicates the slot is outside the viewport. RENDERED_SIZE_TOO_SMALL means the rendered container itself is below the paid-size contract without a clearer clipping signal.

NO_RENDERER_GEOMETRY_PROOF means proof-required geometry was missing. Sandbox/test traffic remains non-billable even when diagnostics are accepted.

renderer_diagnostic_case is a safe derived label that helps identify the exact renderer row during QA without exposing raw tokens, prompts, or private advertiser policy.

Production dry-run is explicitly non-billable. Create a Server Production Dry-run Key in Dashboard API Keys or use an operator-issued sk_dry_... server key as WAVEBIRD_SECRET_KEY.

Production dry-run is selected by credential class, not by request fields. Do not send production_dry_run, production_billing_dry_run, billing_suppressed, or production_live_approved in request bodies; those names are response, log, or dashboard diagnostics only.

A qualifying renderer proof row can expose mode=production-dry-run, PRODUCTION_DRY_RUN_NON_BILLABLE, production_dry_run=true, production_live_approved=false, billing_suppressed=true, dry_run_billable_suppressed=true, and proof_would_be_eligible=true.

No payout setup is required for production dry-run, and production-live-approved is not used. If no active SSP demand is available, the safe blocker is 409 ssp_not_ready with mode=production-dry-run, production_dry_run=true, production_billing_dry_run=true, billing_suppressed=true, production_live_approved=false, live_billing=false, and billable=false.

occurred_at must be close to the real event time. Do not copy old static timestamps from examples.

Generate a fresh timestamp at runtime for every direct server beacon call.

BEACON_TOO_LATE means the event timestamp is too old to be accepted. This commonly happens when testing with copied sample timestamps; use current timestamps for direct server beacon calls.

asset_token is required for direct server /v1/beacons. It is issued with the placement response and is usually available as placement.asset_token or decision.asset_token.

Treat asset_token as sensitive proof material. Redact it from logs, screenshots, reports, support tickets, terminal output, external evidence, and client-visible debug output.

Do not commit asset_token, do not confuse it with WAVEBIRD_SECRET_KEY/server secret key or publishable key, and do not expose it unnecessarily to frontend code unless required by the hosted renderer flow.