Hosted renderer script
/v1/render.jsLoad this script in the customer frontend for the default Server API render path. Use window.wavebird.renderPlacement for REST placement responses. startTurn and withTurn remain optional Script Tag lifecycle helpers.
AUTH
CONTENT TYPE
STATUS
Request parameters
| Name | Type | Required | Description |
|---|
Returns
- window.wavebird.renderPlacement(options)
- function
- Renders a decision or placement into a target element using placement.render.frame_url.
- window.wavebird.withTurn(input, work)
- function
- Optional Script Tag lifecycle helper. It is not required for the Server API REST path, and data-wavebird-request is not read.
- renderer diagnostics
- beacon metadata
- Hosted renderer beacons include safe geometry and dry-run diagnostics such as proof_source, proof_eligible, billable, non_billable_reason, geometry_reason, renderer_diagnostic_case, production_dry_run, production_live_approved, contract_exists, and renderer_geometry_summary for dashboard debugging.
| Name | Type | Description |
|---|---|---|
| window.wavebird.renderPlacement(options) | function | Renders a decision or placement into a target element using placement.render.frame_url. |
| window.wavebird.withTurn(input, work) | function | Optional Script Tag lifecycle helper. It is not required for the Server API REST path, and data-wavebird-request is not read. |
| renderer diagnostics | beacon metadata | Hosted renderer beacons include safe geometry and dry-run diagnostics such as proof_source, proof_eligible, billable, non_billable_reason, geometry_reason, renderer_diagnostic_case, production_dry_run, production_live_approved, contract_exists, and renderer_geometry_summary for dashboard debugging. |
Integration guidance
Renderer proof diagnostics
The hosted renderer sends diagnostic beacons automatically. A renderer beacon can be accepted for logging while still being proof-ineligible and non-billable.
Dashboard logs may show proof_source=public_wrapper_renderer, proof_eligible=false, billable=false, non_billable_reason, geometry_reason, renderer_diagnostic_case, production_dry_run, production_live_approved, contract_exists, and renderer_geometry_summary.
Common geometry reasons are INSUFFICIENT_VISIBLE_AREA, HIDDEN_OR_NOT_VIEWABLE, OFFSCREEN, RENDERED_SIZE_TOO_SMALL, and NO_RENDERER_GEOMETRY_PROOF.
Test traffic remains non-billable. Production dry-run is also 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.
Qualifying renderer proof can show proof_eligible=true and proof_would_be_eligible=true while billable=false, billing_suppressed=true, dry_run_billable_suppressed=true, and non_billable_reason=PRODUCTION_DRY_RUN_NON_BILLABLE.
Production dry-run requires no payout setup and does not use production-live-approved. Dashboard rows should expose mode=production-dry-run and production_live_approved=false during dry-run QA. If no active SSP demand is available, placement creation returns 409 ssp_not_ready with production_dry_run=true, production_billing_dry_run=true, billing_suppressed=true, production_live_approved=false, live_billing=false, and billable=false.
Errors
not_found404Renderer script route is unavailable.