Overview
Equativ provides an OpenRTB API for suppliers which is able to receive OpenRTB bid requests. Equativ then runs an auction for each request so Equativ’s demand partners can bid on the opportunity. This article contains the bid request specification (part 2).
Related articles
Geo object
| OpenRTB field | Data type | Necessity | Description |
|---|
| country | STRING | OPTIONAL | The country code following ISO-3166-1 Alpha-3. |
| zip | STRING | OPTIONAL | The zip/postal code. |
| type | INTEGER | OPTIONAL | The type of geo data source (GPS, IP address, user provided), to be provided when lat / lon is provided. Potential values available here. |
| lat | FLOAT | OPTIONAL | The latitude from -90 to 90, where negative is south. The parameter should be passed only if it is known to be accurate. |
| lon | FLOAT | OPTIONAL | The longitude from -180 to 180, where west is negative. The parameter should be passed only if it is known to be accurate. |
Banner object
Banner MIME types
Bid responses take into account and respond with the
bid.adm attribute, which is formatted according to the
imp.banner.mimes received in the bid request on which the bid is being made. If not specified, the default value is
"text/javascript". It is recommended to use the same MIME type for all banner objects in the same bid request.
Example
bid.adm attribute for a request MIMEs list including the MIME type
"text/javascript" (the
adm is an HTML snippet including Equativ’s JavaScript
<script> tags; it is intended to be inserted into the DOM):
"adm": "<script>document.write("<DIV/>");<script><!-- more creative HTML -->"
Example
bid.adm attribute for a request MIMEs list including the MIME type
"text/html" (the
adm is an HTML snippet excluding all of Equativ’s JavaScript
<script> tags; it is intended to be inserted into the DOM):
"adm": "<img src='…'><!-- more creative HTML -->""
Other MIMEs (or no MIMEs at all) received via
imp.banner.mimes are not supported and responses will default in the manner of
"text/javascript".
| OpenRTB field | Data type | Necessity | Description |
|---|
| format | OBJECT ARRAY | RECOMMENDED | An array of format objects (section 3.2.10 in the OpenRTB specification) representing the banner sizes permitted. If none are specified, then use of the h and w fields is highly recommended. |
| w | INTEGER | OPTIONAL | The width of the impression in pixels. For each size in the format array, an impression object is created. If the format array is empty, the w/h fields are used to create an impression object. |
| h | INTEGER | OPTIONAL | The height of the impression in pixels. For each size in the format array, an impression object is created. If the format array is empty, the w/h fields are used to create an impression object. |
| pos | INTEGER | OPTIONAL | The ad position (possible values in section 5.4 in the OpenRTB specification). |
| api | INTEGER ARRAY | RECOMMENDED | A list of supported API frameworks for the given impression. If an API is not explicitly listed, it is assumed not to be supported. |
Video object
| OpenRTB field | Data type | Necessity | Description |
|---|
| mimes | STRING ARRAY | REQUIRED | The supported content MIME types. Popular MIME types:
- video/x-ms-wmv for Windows Media
- video/x-flv for Flash Video
|
| linearity | INTEGER | OPTIONAL | A field indicating if the ad impression is linear or non-linear. |
| minduration | INTEGER | RECOMMENDED | The minimum video ad duration in seconds. |
| maxduration | INTEGER | RECOMMENDED | The maximum video ad duration in seconds. |
| w | INTEGER | RECOMMENDED | The width of the player in pixels; strongly recommended. |
| h | INTEGER | RECOMMENDED | The height of the player in pixels; strongly recommended. |
| placement | INTEGER | REQUIRED | The placement type for the impression (In-Stream, In-Banner, In-Article, In-Feed, Interstitial/Slider/Floating). |
| plcmt | INTEGER | REQUIRED | The placement type for the impression. Refer to Plcmt Subtypes - Video in the AdCOM 1.0 specification. |
| skip | INTEGER | RECOMMENDED | A field indicating if the player will allow the video to be skipped.
- 1 - skipping is allowed
- 0 - skipping is not allowed
|
| startdelay | INTEGER | RECOMMENDED | A field indicating the start delay in seconds for preroll, midroll or postroll ad placement. |
| pos | INTEGER | OPTIONAL | The ad position. |
| playbackmethod | INTEGER | OPTIONAL | The playback methods that may be in use. If none are specified, any method may be used. In practice, only the first method is used. |
| battr | INTEGER ARRAY | OPTIONAL | The blocked creative attributes. If blank, it is assumed that all types are allowed. |
| api | INTEGER ARRAY | OPTIONAL | A list of supported API frameworks for the given impression. If an API is not explicitly listed, it is assumed not to be supported. |
| ext.rewarded | INTEGER | OPTIONAL | A custom field for rewarded videos used prior to OpenRTB 2.6. This field is obsolete - using imp.rwdd (as specified in OpenRTB 2.6) instead is strongly recommended. |
Audio object
If a demand partner of Equativ is not capable of reading an audio object, the audio object will be converted into a video object with audio mime types.
| OpenRTB field | Data type | Necessity | Description |
|---|
| mimes | STRING ARRAY | REQUIRED | The supported content MIME types (e.g. “audio/mp4”). |
| minduration | INTEGER | RECOMMENDED | The minimum audio ad duration in seconds. |
| maxduration | INTEGER | RECOMMENDED | The maximum audio ad duration in seconds. |
| protocols | INTEGER ARRAY | RECOMMENDED | An array of supported audio protocols. |
| startdelay | INTEGER | RECOMMENDED | A field indicating the start delay in seconds for pre-roll, mid-roll or post-roll ad placements. |
| maxextended | INTEGER | OPTIONAL | The maximum extended ad duration if extension is allowed.
- -1 - the extension is allowed and there is no time limit imposed
- 0 or blank - the extension is not allowed
- > 0 - the value represents the number of seconds of extended play supported beyond the maxduration value
|
| minbitrate | INTEGER | OPTIONAL | The minimum bit rate in Kbps. |
| maxbitrate | INTEGER | OPTIONAL | The maximum bit rate in Kbps. |
| delivery | INTEGER ARRAY | OPTIONAL | The supported delivery methods (e.g. streaming, progressive). If none are specified, support of all delivery methods is assumed. |
| api | INTEGER ARRAY | OPTIONAL | A list of supported API frameworks for the given impression. If an API is not explicitly listed, it is assumed not to be supported. |
Native object
Equativ supports the
OpenRTB Dynamic Native Ads API Specification v 1.2 and strongly recommends compliance with this specification.
Native requests and creatives are both serialized as strings (See Native bid request sample / Native bid response sample
here).
To reach maximum demand, compatibility with the main campaign types used by the main native demand DSPs is strongly recommended.
For native
display campaigns, min. 4 assets should be supported:
- main image (img)
- title or description (title or data)
- icon or CTA (img or data)
- sponsored (data)
For native
display app install campaigns, min. 6 assets should be supported:
- main image or icon (image or data)
- title
- description (data)
- CTA (data)
- price and/or rating (data and/or data)
- sponsored (data)
The following fields (all requiring Native Ads v 1.2) are
required for all campaign types in addition to the asset/elements mentioned above:
- native.privacy (privacy field)
- plcmttype (placement type)
- native.eventtrackers requiring support for at least
- event = 1 (impression) and method = 1 (img) - and
- event = 1 (impression) and method = 2 (js)
The field
context is recommended.
As stated in Native Ads v 1.2, it is strongly recommended to use minimum values for the width/height (wmin/hmin) of image assets (e.g. for main image, asset type 3), as demand campaigns may use the same ratio but higher resolution assets and may not bid on fixed measurements (w/h) that would otherwise be compatible. This and other required/recommended elements above may cumulatively impact the majority of monetization.
Native video is not supported at this time.
Publisher object
| OpenRTB field | Data type | Necessity | Description |
|---|
| id | INTEGER | REQUIRED | The publisher ID on the exchange; ⚠️ must be the Network ID of the account at Equativ. See "Authentication" here for an alternative method to pass the Network ID. |
Format object
| OpenRTB field | Data type | Necessity | Description |
|---|
| w | INTEGER | REQUIRED | The width in device independent pixels (DIPS). |
| h | INTEGER | REQUIRED | The height in device independent pixels (DIPS). |
Content object
| OpenRTB field | Data type | Necessity | Description |
|---|
| id | STRING | OPTIONAL | An ID uniquely identifying the content. |
| episode | INTEGER | OPTIONAL | The episode number. |
| title | STRING | OPTIONAL | The content title.
Video examples: “Search Committee” (television), “A New
Hope” (movie), or “Endgame” (made for web).
Non-video example: “Why an Antarctic Glacier Is Melting So
Quickly” (Time magazine article). |
| series | STRING | OPTIONAL | A content series.
Video examples: “The Office” (television), “Star Wars” (movie),
or “Arby ‘N’ The Chief” (made for web).
Non-video Example: “Ecocentric” (Time Magazine blog). |
| season | STRING | OPTIONAL | The content season (e.g.: “Season 3”). |
| artist | STRING | OPTIONAL | The artist credited with the content. |
| genre | STRING | OPTIONAL | The genre that best describes the content (e.g., rock, pop, etc). |
| album | STRING | OPTIONAL | The album the content belongs; typically for audio. |
| isr | STRING | OPTIONAL | The International Standard Recording Code conforming to ISO3901. |
| url | STRING | OPTIONAL | The URL of the content, for buy-side contextualization or review. |
| cat | STRING ARRAY | OPTIONAL | An array of IAB content categories that describe the content producer. |
| prodq | INTEGER | OPTIONAL | The production quality. |
| context | INTEGER | OPTIONAL | The type of content (game, video, text, etc.). |
| contentrating | STRING | OPTIONAL | The content rating (e.g.: MPAA). |
| userrating | STRING | OPTIONAL | The user rating of the content (e.g.: number of stars, likes, etc.). |
| qagmediarating | INTEGER | OPTIONAL | The media rating per IQG guidelines. |
| keywords | STRING | OPTIONAL | A comma-separated list of keywords describing the content. |
| livestream | INTEGER | OPTIONAL | A field indicating if the given content is live content.
- 1 - content is live (e.g.: stream, live blog)
- 0 - content is not live
|
| sourcerelationship | INTEGER | OPTIONAL | The relationship to the content source.
- 1 - relation is direct
- 0 - relation is indirect
|
| len | INTEGER | OPTIONAL | The length of the content in seconds; appropriate for video or audio. |
| language | STRING | OPTIONAL | The content language using ISO-639-1-alpha-2. |
| embeddable | INTEGER | OPTIONAL | A field indicating if the content is embeddable (e.g.: an embeddable video player).
- 1 - content is embeddable
- 0 - content is not embeddable
|
| data | OBJECT ARRAY | OPTIONAL | Additional content data. Each Data object represents a different data source. |
| cattax | INTEGER | OPTIONAL | The taxonomy in use. Default is 1. |
| kwarray | STRING ARRAY | OPTIONAL | A comma separated list of keywords describing the content. Only one of keywords or kwarray may be present. |
| langb | STRING | OPTIONAL | The content language using IETF BCP 47. Only one of language or langb may be present. |
| network | OBJECT | OPTIONAL | The network of the content in which the ad will be shown. |
| channel | OBJECT | OPTIONAL | The channel of the content in which the ad will be shown. |
| producer | OBJECT | OPTIONAL | The producer of the content in which the ad will be shown. |
Data object
| OpenRTB field | Data type | Necessity | Description |
|---|
| id | STRING | OPTIONAL | An exchange-specific ID for the data provider. |
| name | STRING | OPTIONAL | An exchange-specific name for the data provider. |
| segment | OBJECT ARRAY | OPTIONAL | An array of Segment objects that contain the actual data values. |
Segment object
| OpenRTB field | Data type | Necessity | Description |
|---|
| id | STRING | OPTIONAL | The ID of the data segment specific to the data provider. |
| name | STRING | OPTIONAL | The name of the data segment specific to the data provider. |
| value | STRING | OPTIONAL | The string representation of the data segment value. |
Producer object
| OpenRTB field | Data type | Necessity | Description |
|---|
| id | STRING | OPTIONAL | The content producer or originator ID. Useful if content is syndicated and may be posted on a site using embed tags. |
| name | STRING | OPTIONAL | The ID of the bidder seat on whose behalf this bid is made. |
| cattx | INTEGER | OPTIONAL | The taxonomy in use. Default is 1. |
| cat | STRING ARRAY | OPTIONAL | An array of IAB content categories that describe the content producer. |
| domain | STRING | OPTIONAL | The highest level domain of the content producer (e.g. “producer.com”). |
| ext | OBJECT | OPTIONAL | A placeholder for exchange-specific extensions to OpenRTB. |
Channel object
| OpenRTB field | Data type | Description |
|---|
| id | STRING | A unique identifier assigned by the publisher. This may not be a unique identifier across all supply sources. |
| name | STRING | The channel the content is on (e.g. a local channel like “WABC-TV"). |
| domain | STRING | The primary domain of the channel (e.g. "https://abc7ny.com" in case of the local channel WABC-TV). It is recommended to include the top private domain (PSL+1) for DSP targeting normalization purposes. |
| ext | OBJECT | A placeholder for exchange-specific extensions to OpenRTB. |
Network object
| OpenRTB field | Data type | Description |
|---|
| id | STRING | A unique identifier assigned by the publisher. This may not be a unique identifier across all supply sources. |
| name | STRING | The network the content is on (e.g. a TV network like “ABC"). |
| domain | STRING | The primary domain of the network (e.g. “abc.com” in case of the network ABC). It is recommended to include the top private domain (PSL+1) for DSP targeting normalization purposes. |
| ext | OBJECT | A placeholder for exchange-specific extensions to OpenRTB. |
