# CTV Parameters

Source: https://docs.ezoic.com/docs/ctv/parameters/


Complete reference for `GET https://g.ezoic.net/ezoic/videoad/vast`. Parameters are URL query parameters and values must be URL-encoded. The reference is current with the tag's behaviour as of 2026-07-31.

General behaviour:

- **Unknown parameters are ignored.** Cache busters and vendor extras are safe.
- Responses are never cached (`Cache-Control: no-store`). Still send a cache buster (`cb`) so intermediate infrastructure cannot cache either.
- The endpoint supports CORS, so browser players can fetch it with XHR, and it answers `OPTIONS` preflights.
- A parameter that is present but empty, or a number that is zero or negative, falls back to its default.
- A value that is entirely a macro literal (for example `[IFA]`, `{{BUNDLE}}`, `%%US_PRIVACY%%`, or the text `null` or `undefined`) is dropped. See [Testing and troubleshooting](/docs/ctv/testing/#unexpanded-macros).

## Property identity

Send exactly one identity lane. `url` wins over `d`, and the app lane is used only when neither is present.

| Parameter | Description |
|---|---|
| `url` | Full page URL (website lane). Takes precedence over everything else. |
| `d` | Bare domain, for example `example.com`. Expanded to `https://example.com/`. |
| `bundle` (aliases `app_bundle`, `roku_app_id`) | App identifier (app lane). Roku: numeric Channel Store ID. Android and Fire TV: package name. Apple: numeric App Store ID. Must resolve to a domain registered with Ezoic. |
| `app_domain` | The Ezoic-registered domain your app maps to. Send it with `bundle`. |
| `app_name` (aliases `appname`, `name`) | Human-readable app name. |
| `storeurl` (aliases `appstoreurl`, `app_store_url`) | App store listing URL. |
| `app_cat` | CSV of IAB content category codes for the app as a whole, for example `IAB1,IAB1-7`. Include at least one parent-level category. |
| `inventorypartnerdomain` | Domain of the inventory partner on whose behalf the request is made. Required by some large buyers on reseller arrangements. |

## Placement and auction

| Parameter | Default | Description |
|---|---|---|
| `adunit` | `ezoic_vast_tag` | Your normal video ad unit name. Send the name your publisher setup uses, not a separate CTV unit. It also seeds the placement ID. Only the exact name `adunit` is read. `ad_unit` is silently ignored. |
| `gpid` | `<adunit>_plcmt_<N>` | Explicit global placement ID. When you send it, it is used exactly as given. |
| `w` / `h` | 640 / 360 | Player width and height in pixels. Send your real size, for example `1920` and `1080` for full-screen TV. |
| `floor` | none | Bid floor in USD, for example `floor=2.50`. Applied only when greater than zero. |
| `tmax` | 3500 | Auction time budget in milliseconds. The tag keeps a 50 ms network buffer and never runs the auction with less than 200 ms of budget, so very small values are raised to that minimum. Set it to the time your stitcher or ad server actually allows. |
| `plcmt` | 1 | OpenRTB 2.6 placement type. `1` is in-stream, the CTV standard. Out-of-range values become `1`. |
| `secure` | 1 | Whether creatives must be served over HTTPS. Send `secure=0` only if you have a real need. Any value other than `0` is treated as `1`. |

## Video

| Parameter | Default | Description |
|---|---|---|
| `v` | 4.2 | VAST version to negotiate: `2` or `2.0`, `3` or `3.0`, `4` or `4.x`. **Roku's ad framework parses only 2.0 and 3.0, so always send `v=3` for Roku.** When `v` is absent, the ceiling comes from `protocols`. |
| `protocols` | from `v` | CSV of OpenRTB protocol IDs. When absent, the response is limited to the negotiated VAST version. |
| `mimes` | `video/mp4` | CSV of MIME types. Send more only if your player plays them. |
| `api` | platform-aware | CSV of API frameworks, for example `7` for OMID-1. On CTV requests without this parameter, Roku-identified requests declare none, because Roku does not run an in-player measurement SDK. Other CTV requests declare `7`. An explicit value always wins. |
| `playbackmethod` | none | CSV of OpenRTB playback methods, for example `1` for autoplay with sound. |
| `minduration` / `maxduration` | 5 / 120 | Accepted creative duration bounds in seconds. Explicit values always win. For dynamic pods these are per-ad limits. |
| `placement` | 1 when `plcmt=1` | Legacy OpenRTB 2.5 placement field. Sent for in-stream. |
| `pos` | 7 on CTV | Ad position, AdCOM 0 to 7. CTV requests default to `7` (full screen). Other device types have no default. An explicit `pos=0` is treated as absent. |
| `skip` | 0 | `1` if your player supports skippable ads. The tag always declares a value to buyers: yours when you send it, otherwise `0`. |
| `linearity` | none | `1` for linear, in-stream. |
| `startdelay` | none | `0` for pre-roll, `-1` for generic mid-roll, `-2` for post-roll, or a positive number of seconds. No default, so always send it. |
| `minbitrate` / `maxbitrate` | none | Bitrate bounds in kbps. |
| `pod` / `slot` | none | Ad pod ID and 1-based slot position. Send both when you request pod slots as separate calls. |
| `poddur` / `maxseq` / `podseq` / `mincpmpersec` | none | Dynamic-pod fields for one request that asks for a whole ad break. `poddur` is the total break length in seconds. `maxseq` is the most ads in the pod. `podseq` is the AdCOM pod sequence. `mincpmpersec` is a minimum CPM per second. Each is passed through only when valid. |

## Device

| Parameter | Description |
|---|---|
| `devicetype` | OpenRTB device type. **Hardcode `3` (Connected TV).** Types `6` (Connected Device) and `7` (Set Top Box) also classify as CTV, and a TV user agent is treated as CTV when this is absent. |
| `ifa` | Device advertising identifier as the platform provides it. |
| `ifa_type` | Source of the `ifa`. One of `rida`, `afai`, `tifa`, `vida`, `msai`, `idfa`, `aaid`, `sspid`. **Always send it with `ifa`.** CTV buyers discount an IFA with no type. |
| `lmt` / `dnt` | `1` or `0`. Send `lmt=1` when the viewer has limited ad tracking. |
| `ua` / `ip` / `ipv6` | The device's user agent and IP address. Server-side callers must send the viewer's values, not their own. Direct device calls may omit them, and the tag then uses the request's own headers. |
| `language` / `make` / `model` / `os` / `osv` / `carrier` | Passed through to the device object. For Roku, send `make=Roku`, `os=Roku OS` and `osv` with the OS version. |
| `connectiontype` | OpenRTB connection type, `1` to `7`. |
| `lat` / `lon` / `region` / `city` / `zip` | Geo values, passed through as given. |
| `country` | Country code, ISO-3166-1 alpha-2 (`US`) or alpha-3 (`USA`). Normalized to alpha-3. If you omit it, or the value does not normalize, the tag fills it from the request IP. |

## Content

All optional and all recommended. See [Content metadata](/docs/ctv/content-metadata/) for guidance.

| Parameter | Description |
|---|---|
| `content_id` | Your stable content identifier. |
| `content_title` | Title of the content. |
| `content_series` | Series name, if the content is episodic. |
| `content_episode` / `content_season` | Episode and season numbers. |
| `content_genre` | Genre, for example `Comedy`. |
| `content_cat` | CSV of IAB content category codes, for example `IAB1-7`. Brand-safety filters key on it. |
| `content_len` | Content duration in seconds. Brand-safety filters key on it. |
| `content_language` | Content language, ISO-639-1. |
| `content_url` | Public URL of the content, if one exists. |
| `content_rating` | Content rating, for example `TV-PG`. Some large buyers require it. |
| `content_prodq` | Production quality: `1` professional, `2` prosumer, `3` user-generated. |
| `content_channel` / `content_channel_domain` | Channel name and its domain. |
| `content_network` / `content_network_domain` | Network name and its domain. |
| `livestream` | `1` only when the content is live at the moment of the impression. Video on demand, including replays, is `0`. |

## Privacy and regulatory

Send only the signals you have. Never fabricate a value.

| Parameter | Description |
|---|---|
| `gdpr` | `1` when GDPR applies to the request, otherwise `0`. |
| `consent` | IAB TCF consent string. |
| `us_privacy` | IAB US Privacy (CCPA) string, for example `1YNN`. |
| `gpp` / `gpp_sid` | IAB GPP consent string and the CSV of applicable section IDs. |
| `coppa` | `1` when the content is directed to children. |

## Blocklists and supply chain

| Parameter | Description |
|---|---|
| `badv` | CSV of blocked advertiser domains. |
| `bcat` | CSV of blocked IAB categories. |
| `bapp` | CSV of blocked app bundles. |
| `schain` | Supply chain serialized per the IAB spec. A malformed chain is dropped entirely, so validate it before you send it. Direct integrations with no intermediary can omit it. |

## Identity enrichment

| Parameter | Description |
|---|---|
| `eids` | URL-encoded JSON array of OpenRTB extended IDs. Limits: 4 KB raw and 8 entries. Each entry needs a string `source` and `uids[].id`. Malformed input drops the whole parameter, and a single bad entry is skipped. Example before encoding: `[{"source":"uidapi.com","uids":[{"id":"...","atype":3}]}]` |
| `ssai` | Server-side ad insertion level, see the table below. Send it only when you know the value. |
| `omidpn` / `omidpv` | Open Measurement partner name and version. Send them only when your player runs its own OM SDK session, and pair them with `api=7`. |
| `displaymanager` / `displaymanagerver` | Name and version of the rendering SDK. The defaults are `ezoic-vast-tag` and `1.0`. |

### SSAI level

| `ssai` | Meaning |
|---|---|
| `1` | All client-side. Not server-side at all. |
| `2` | Assets stitched server-side, tracking pixels fired client-side. |
| `3` | All server-side, stitching and tracking. |

Omit `ssai` if you are not stitched or are unsure. Some buyers gate SSAI demand on this field, so a wrong value costs more than no value.

## Google

- `givn` carries a Google PAL SDK nonce. A valid nonce, from an app Google has approved for this lane, lets Google demand compete for the impression. Partner tags do not need it. Contact your Ezoic representative before you send it.

## Responses

| Shape | HTTP | Meaning |
|---|---|---|
| 302 redirect to a VAST document | 302, then 200 | Filled. Standard players follow the redirect. |
| Inline VAST XML with `<Ad>` elements | 200 | Filled, served directly. Extra `<Ad>` elements are same-request fallbacks, not a pod. |
| Empty VAST document | 200 | No fill. Never an error page. |

One ad per request, with no VMAP. For multi-ad breaks, request each slot with `pod` and `slot`.