Specification | Version | Last Update Date | Notes | |
---|---|---|---|---|
OpenRTB | v2.5 with oRTB 2.6 Dynamic Podding support** |
|
| |
IAB Content Category Taxonomy | v1 |
| IAB Content Categories are mapped to FreeWheel Global Industries |
Guide Version | Date | Author | Description |
---|---|---|---|
v2.9 |
| Admin |
|
|
|
The FreeWheel OpenRTB Supply Integration API (oRTB-S) has been created in order to make it possible to deploy and maintain an effective OpenRTB supply integration with Freewheel to pass inventory to downstream demand sources to obtain incremental demand. ORTB is a standard that was created by the IAB for the purpose of creating a universal language that all entities participating in an auction can speak in order to conduct business. Auctions are the backbone of programmatic advertising and ensure that publishers are earning the highest possible price for their ad space. You can find more information on the ORTB 2.5 specification here.
The FreeWheel oRTB-S integration has been implemented using the oRTB 2.5 Standard with support for oRTB 2.6 dynamic podding. To further clarify, not all attributes from the 2.5 and 2.6 specs are supported, to assure which ones are supported please see the individual object tables below. This ensures compliance with the common data structure and communication layers of ORTB. For a complete list of mandatory, recommended and optional fields available within the Freewheel API, please refer to the Bid Request section of this guide.
The FreeWheel OpenRTB Supply API supports the below key features:
Feature | Note(s) |
---|---|
Dynamic Ad Podding |
|
Multi-Bid |
|
Multi-Imp (Structured Podding) |
|
Prior to the start of the integration, publishers must provide to their account team the following:
Following approval from the Freewheel account team, FreeWheel resources will enable the oRTB-S integration on your network and provide you the necessary key values for operation.
The Freewheel ORTB servers cover three geographical zones:
Publishers will be provided with a unique endpoint for which to send requests. This is known as the Endpoint Prefix ID which is the Network ID (see Glossary) in hexadecimal format. This Endpoint Prefix ID will need to be added as a prefix within the URL.
Format :
https://prefix.v.fwmrm.net/ortb/ssp
Example with a custom prefix included :
https://83b96.v.fwmrm.net/ortb/ssp
If you have not supplied us with your pingable server IP addresses, you can run a test against the custom end-point with the following command and provide us with the results :
|
The oRTB-S API will respond with a status code. For successful auctions, creative information and CPM will be included in the response. See Bid Response section for more information.
For in-app and OTT environments, we use the device IFA which does not need to be synced between the publisher and Freewheel. These can be passed directly in the bid request.
*This section is only necessary for web inventory
User Syncing, also known as Cookie Syncing, is the process of sharing and matching HTTP cookies between various partners. The concept of Cookie Tracking is restrictive in the amount of information that can be collected and actioned upon for advertisers. This is because cookies are limited to domain and have varying expiration dates. In order for Freewheel to be able to identify, target and frequency cap across various digital properties in accordance with campaign KPI's, Freewheel needs to know how to distinguish one user from another that are sent to us in the publisher's bid request.
To be supported in future development
*This section is only necessary for web inventory
To be supported in future development
4.5 Request 'tmax'
In order to avoid timeouts and to accommodate downstream hops, we highly recommend that a tmax of at least 500m/s is passed in the bid request. In cases where this not possible to change, please inform your Freewheel point of contact in order to assess how we can best manage this and avoid any technical implications.
This section covers the Freewheel-specific core fields that need to be passed in order for the request to be processed successfully.
5.1.1 Site Section ID
Site Section ID is a placement identifier that is used as the most granular way to segment ad retrieval. Requests must contain a Site Section ID.
|
5.1.2 Network ID
Distributor's FreeWheel network ID. Requests must contain a Network ID.
|
5.1.3 Profile ID
Profile name indicating configurations such as creative restrictions and compliance related settings. If no value is passed, the Network Profile will be used
|
For app and CTV inventory, the user ID to pass in the bid request is the Device ID in device.ifa.
For web inventory, the ID to pass in the bid request is the Freewheel User ID that has previously been synced (see Section 4.4 above). It must be passed in user.buyeruid.
The top-level bid request object contains a globally unique bid request ID. This id attribute is required alongside at least one impression object. Some other subordinate objects are also required: Site or App, depending on whether the content is browser-based or originating from a non-browser application such as mobile app or CTV app. Other required subordinate objects are Device and User.
|
Within the main BidRequest object, the Imp object describes an ad placement or impression being auctioned. A single bid request can include multiple Imp objects. Each Imp object has a required ID so that bids can reference them individually. The Video subordinate object is required, as is the Secure object
|
Within the main BidRequest object, the Site object should be included if the ad supported content is a website as opposed to a non-browser application. You should pass the ID of the Site Section for web inventory as site.id if possible.
|
Within the main BidRequest object, the App object should be included if the ad supported content is a non-browser application (mobile app or CTV app) as opposed to a website. You should pass the ID of the Site Section for app inventory as app.id if possible.
|
|
Within the main BidRequest object, the device object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set top box, or other digital device.
|
Within the main BidRequest object, the User object contains information known or derived about the human user of the device (i.e., the audience for advertising).
|
Within the main BidRequest object, the Source object describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange.
|
Within the BidRequest Object, the Regs (Regulations) object contains any legal, governmental, or industry regulations that apply to the request. See Regs Object Example below
5.11.1 Regs Object Example
|
Within the Imp object(s), the Video object represents an in-stream or outstream video impression. Video in OpenRTB generally assumes compliance with the VAST standard, and is a required object.
oRTB 2.6 Dynamic Podding is supported, however, not all attributes are supported. See the table for what attributes are supported.
|
Within the Device object, this object indicates the location of the device, which can also be interpreted as the user's current location.
|
Within the App or Site object, the content object describes the content in which the impression will appear, which may be direct or syndicated content.
|
Optional extensions and customised fields. These are also listed in their respective parent objects above.
|
Within the Extension object in the main BidRequest, this object can be used to pass through custom fields and additional value-enhancing information. It can also be used to pass through Freewheel-specific ad request key-values which can be found here
|
Attribute | Type | Description | Example |
---|---|---|---|
id | string | Unique ID of the bid request to which this is a response. | "id": "22945_1680294581308005-305_1" |
seatbid | object array | Array of seatbid objects | see Seatbid object |
bidid | string | Bidder generated response ID to assist with logging/tracking. | "bidid": "c3e048e2-d002-11ed-a24a-008902a05642" |
cur | string | Currency of the bid response. This is passed in the network currency | "cur": "EUR" |
Attribute | Type | Description | Example |
---|---|---|---|
bid | object array | Array of 1 or more Bid objects each related to an impression. | see Bid object |
seat | string | ID of the buyer seat on whose behalf this bid is made. By default, it is set to "FreeWheel" | "seat": "FreeWheel" |
Attribute | Type | Description | Example |
---|---|---|---|
id | string | Unique ID of the bid | "id": "c3e048e2-d002-11ed-a24a-008902a05642/1" |
impid | string | ID of the Imp object in the related bid request. | "impid": "1" |
price | float | Bid price expressed as CPM although the actual transaction is for a unit impression only. | "price": 26.002 |
adid | string | ID of a preloaded ad to be served if the bid wins. | "adid": "255329" |
adm | string | Used for sending inline VAST/creative response and any tracking in bid response. | "adm": "<?xml version='1.0' encoding='UTF-8'?><inline_VAST></VAST>\n" |
adomain | string array | Advertiser domain for block list checking. | "adomain": ["advertiserdomain.com","advertiserdomain2.com","advertiserdomain3.com"] |
cid | string | Campaign ID to assist with ad quality checking. | "cid": "2730526348" |
crid | string | Creative ID to assist with ad quality checking. | "crid": "2732710315" |
cat | string array | Array of IAB v1.0 Categories associated with the creative | "cat": ["IAB1"] |
dur | integer | Duration of the creative in seconds | "dur": 30 |
Response Code | Meaning |
---|---|
200 | Bid successful |
400 | Malformed json, or invalid Network ID, or invalid Profile ID |
403 | Network is not permissioned for ORTB-S, or app bundle/domain/ua are forbidden |
204 | No bid |
5xx | API Server-side error |
Term | Definition |
---|---|
Dynamic Ad Podding | Under the ORTB 2.6 specification, Dynamic Ad Podding offers a structure whereby an indeterminate number of ads can be requested to fill a known ad break duration |
Endpoint | A digital location exposed via the API whereby requests can be sent and received |
Network | Your publisher account at Freewheel. The linking of one or more Publishers to one or more Buyers under an agreed set of Rules, using OpenRTB. It is a safe and 100% controlled environment for the publisher to auction their video impressions. Each network has a unique identifier known as a Network ID |
Object | JSON object literals, a.k.a JSON objects, are surrounded by curly braces {}. Keys and values are separated by a colon. Keys must be strings, and values must be a valid JSON data type:
|
oRTB | openRTB |
Profile | A set of configurations that define which ads will be playable given the player environment and framework. This is set up in the backend during integration, and the correct profile for the player to set will be provided by FreeWheel. |
Site Section | An Ad placement within a network |
VAST | Video Ad Serving Template, developed by IAB as a framework to embed third-party video ads into a video stream: an XML markup schema placed on a publisher's website to display ads. |
{ "id": "851011cf-06d2-4ba5-bb50-4bbc509490bc", "cur": [ "USD" ], "at": 1, "bcat": [ "IAB23", "IAB11" ], "tmax": 600, "app": { "id": "APPLICATION ID OR REPLACED BY SITE SECTION ID OR CUSTOM SITE SECTION TAG", "bundle": "com.app.name", "cat": [ "IAB1", "IAB2" ], "name": "app-name", "publisher": { "id": "1234", "name": "publisher-name" }, "storeurl": "https://www.example.com/us/appstore/app/1234", "ver": "1.0", "ext": { "inventorypartnerdomain": "example.com" }, "content": { "cat": [ "IAB2" ], "contentrating": "tv-14", "genre": "GV,Entertainment,Automotive,Talk Show", "keywords": "NRS-TV,Entertainment", "language": "en", "len": 2700, "livestream": 1, "prodq": 1, "qagmediarating": 1, "series": "VOD", "title": "WeatherNation Live", "userrating": "4.6", "producer": { "name": "prorducer-name" }, "network": { "name": "network-name" }, "channel": { "name": "channel-name" } } }, "device": { "devicetype": 3, "ext": { "atts": 2, "ifa_type": "dpid", "ifv": "A994A398-3AD5-4296-8FFC-A97940C6BAA6", "lmt": 0 }, "geo": { "country": "USA", "lat": 28.7115, "lon": -81.5135, "zip": "32712" }, "ifa": "28febb41-2152-da34-f95a-bb0f89540e2c", "ip": "192.168.0.1", "ipv6": "::ffff:192.168.0.1", "language": "en", "lmt": 0, "make": "Roku", "model": "K000X", "os": "Other", "ua": "Roku/DVP-13.1 (13.1.4.1510-H2)" }, "ext": { "custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG", "network_id": "REPLACED BY NETWORKID", "profile_id": "REPLACED BY PROFILE NAME", "fw_gd": 1, "keywords": { "_fw_content_programmer_brand": "brand-name", "_fw_cookie_consent": "1", "_fw_h_x_city": "city-name", "_fw_h_x_dma": "501", "_fw_h_x_state": "state-name", "_fw_h_x_timezone": "-05:00" } }, "imp": [ { "id": "1", "secure": 1, "bidfloor": 8.2018, "bidfloorcur": "USD", "ext": { "custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG", "fw_gd": 1, "network_id": "REPLACED BY NETWORK ID", "profile_id": "REPLACED BY PROFILE NAME" }, "video": { "api": [ 1, 2, 7 ], "battr": [ 1, 3, 5, 8, 9 ], "h": 1080, "linearity": 1, "maxbitrate": 30000, "maxduration": 30, "mimes": [ "video/mp4", "video/H264" ], "minbitrate": 240, "minduration": 6, "placement": 1, "playbackend": 1, "playbackmethod": [ 1 ], "plcmt": 1, "protocols": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "sequence": 1, "startdelay": 0, "w": 1920 } } ], "regs": { "coppa": 0, "ext": { "consent": "", "gdpr": 0, "gpp": "DBABLA~BVQqAAAAAWA", "gpp_sid": [ 7 ], "us_privacy": "1---" }, "gdpr": 0, "gpp": "DBABLA~BVQqAAAAAWA", "gpp_sid": [ 7 ] }, "source": { "ext": { "schain": { "complete": 1, "nodes": [ { "asi": "lkqd.net", "hp": 1, "sid": "1100053830" }, { "asi": "krushmedia.com", "hp": 1, "rid": "b6d8343b-8413-ee6d-1c36-8152f30ef8f7", "sid": "AJxF6R43a9M6CaTvK" } ], "ver": "1.0" } } }, "user": { "buyeruid": "eaa46e6cc2b0d66a59f41667b264fefb", "ext": { "consent": "BOSSotLOSSotLAPABAENBc-AAAAgR7_______9______9uz_Gv_v_f__33e8__9v_l_7_-___u_-33d4-_1vX99yfm1-7ftr3tp_86ues2_XqK_9oIiA", "eids": [ { "source": "pubcid.org", "uids": [ { "id": "8309ad21-b466-4cc9-8287-8354bd442dd6" } ] } ], "gdpr": 0 }, "id": "RX-817f6b9c-b8f5-45fd-9ed6-3544206b4055-005" } } |
{ "id": "b6d8343b-8413-ee6d-1c36-8152f30ef8f7", "cur": [ "USD" ], "at": 1, "bcat": [ "IAB23", "IAB11" ], "tmax": 600, "site": { "id": "SITE ID OR REPLACED BY SITE SECTION ID OR CUSTOM SITE SECTION TAG", "cat": [ "IAB12" ], "domain": "example.com", "ext": { "inventorypartnerdomain": "example.com" }, "name": "site-name", "page": "https://example.com/article/1234", "publisher": { "id": "1234", "name": "publisher-name" }, "ref": "https://exmaple.com/", "content": { "cat": [ "IAB2" ], "contentrating": "tv-14", "genre": "GV,Entertainment,Automotive,Talk Show", "keywords": "NRS-TV,Entertainment", "language": "en", "len": 2700, "livestream": 1, "prodq": 1, "qagmediarating": 1, "series": "VOD", "title": "WeatherNation Live", "userrating": "4.6", "producer": { "name": "prorducer-name" }, "network": { "name": "network-name" }, "channel": { "name": "channel-name" } } }, "device": { "devicetype": 1, "ext": { "atts": 2, "ifa_type": "dpid", "ifv": "A994A398-3AD5-4296-8FFC-A97940C6BAA6", "lmt": 0 }, "geo": { "country": "USA", "lat": 28.7115, "lon": -81.5135, "zip": "32712" }, "ifa": "28febb41-2152-da34-f95a-bb0f89540e2c", "ip": "192.168.0.1", "ipv6": "::ffff:192.168.0.1", "language": "en", "lmt": 0, "make": "Generic", "model": "Android 6.0", "os": "Android", "ua": "Mozilla/5.0 (Linux; Android 10; K) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/128.0.0.0 Mobile Safari/537.36" }, "ext": { "custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG", "network_id": "REPLACED BY NETWORK ID", "profile_id": "REPLACED BY PROFILE NAME", "fw_gd": 1, "keywords": { "_fw_content_programmer_brand": "brand-name", "_fw_cookie_consent": "1", "_fw_h_x_city": "city-name", "_fw_h_x_dma": "501", "_fw_h_x_state": "state-name", "_fw_h_x_timezone": "-05:00" } }, "imp": [ { "id": "1", "secure": 1, "bidfloor": 8.2018, "bidfloorcur": "USD", "ext": { "custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG", "network_id": "REPLACED BY NETWORK ID", "profile_id": "REPLACED BY PROFILE NAME", "fw_gd": 1 }, "video": { "api": [ 1, 2, 7 ], "battr": [ 1, 3, 5, 8, 9 ], "h": 1080, "linearity": 1, "maxbitrate": 30000, "maxduration": 30, "mimes": [ "video/mp4", "video/H264" ], "minbitrate": 240, "minduration": 6, "placement": 1, "playbackend": 1, "playbackmethod": [ 1 ], "plcmt": 1, "protocols": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "sequence": 1, "startdelay": 0, "w": 1920 } } ], "regs": { "coppa": 0, "ext": { "consent": "", "gdpr": 0, "gpp": "DBABLA~BVQqAAAAAWA", "gpp_sid": [ 7 ], "us_privacy": "1---" }, "gdpr": 0, "gpp": "DBABLA~BVQqAAAAAWA", "gpp_sid": [ 7 ] }, "source": { "ext": { "schain": { "complete": 1, "nodes": [ { "asi": "lkqd.net", "hp": 1, "sid": "1100053830" }, { "asi": "krushmedia.com", "hp": 1, "rid": "b6d8343b-8413-ee6d-1c36-8152f30ef8f7", "sid": "AJxF6R43a9M6CaTvK" } ], "ver": "1.0" } } }, "user": { "buyeruid": "eaa46e6cc2b0d66a59f41667b264fefb", "ext": { "consent": "", "eids": [ { "source": "pubcid.org", "uids": [ { "id": "8309ad21-b466-4cc9-8287-8354bd442dd6" } ] } ], "gdpr": 0 }, "id": "RX-817f6b9c-b8f5-45fd-9ed6-3544206b4055-005" } } |
{ "app": { "bundle": "com.app.name", "content": { "cat": [ "IAB12" ], "channel": { "name": "channel-name" }, "contentrating": "TV-G", "context": 1, "ext": { "inventorypartnerdomain": "example.com" }, "genre": "Bulletin", "id": "aageykaagenda", "keywords": "ABP News", "language": "en", "livestream": 0, "network": { "name": "network-name" }, "series": "Aagey ka Agenda", "title": "Aagey ka Agenda" }, "id": "APPLICATION ID OR REPLACED BY SITE SECTION ID OR CUSTOM SITE SECTION TAG", "name": "app-name", "storeurl": "https://www.example.com/us/appstore/app/1234" }, "at": 1, "device": { "devicetype": 3, "ext": { "ifa_type": "aaid" }, "geo": { "city": "Gurugram", "country": "IN", "lat": 28.4597, "lon": 77.0282, "metro": "0", "region": "HR", "zip": "122001" }, "ifa": "7fb4c359-9912-4b16-9960-33cd7cbc2a18", "ip": "192.168.0.1", "lmt": 0, "make": "Xiaomi", "model": "MiTV-AXSO2", "os": "Android", "osv": "11", "ua": "Dalvik/2.1.0 (Linux; U; Android 11; MiTV-AXSO2 Build/RTT0.211201.001)" }, "ext": { "custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG", "fw_gd": 1, "keywords": { "_fw_content_programmer_brand": "brand-name", "_fw_cookie_consent": "1", "_fw_h_x_city": "city-name", "_fw_h_x_dma": "501", "_fw_h_x_state": "state-name", "_fw_h_x_timezone": "-05:00" }, "network_id": "REPLACED BY NETWORKID", "profile_id": "REPLACED BY PROFILE NAME" }, "id": "ct8jj1ri38r1hgri9u4g", "imp": [ { "bidfloor": 0.5, "ext": { "custom_site_section_id": "REPLACED BY CUSTOM SITE SECTION TAG", "fw_gd": 1, "network_id": "REPLACED BY NETWORK ID", "profile_id": "REPLACED BY PROFILE NAME" }, "id": "556650_ct8jj1ri38r1hgri9u2g_1", "secure": 1, "video": { "delivery": [ 1, 2 ], "h": 1080, "linearity": 1, "maxbitrate": 30000, "maxduration": 120, "mimes": [ "video/mp4", "video/H264" ], "minbitrate": 240, "minduration": 6, "placement": 1, "playbackmethod": [ 1 ], "plcmt": 1, "maxseq": 4, "poddur": 60, "podid": "1", "protocols": [ 1, 2, 3, 4, 5, 6, 7, 8 ], "w": 1920 } } ], "regs": { "ext": { "gdpr": 0, "us_privacy": "1---" } }, "source": { "ext": { "schain": { "complete": 1, "nodes": [ { "asi": "lkqd.net", "hp": 1, "sid": "1100053830" }, { "asi": "krushmedia.com", "hp": 1, "rid": "b6d8343b-8413-ee6d-1c36-8152f30ef8f7", "sid": "AJxF6R43a9M6CaTvK" } ], "ver": "1.0" } } }, "tmax": 850, "user": { "ext": { "consent": "CP0QLgAP0QLgAAGABCENDbCgAAAAAEPAABBoAAARvgFgAVABIADQAJgAUgD_gIWAYyAyMB7QEbwBwoAMAKQCFgGMigAYATAD_gMjGAAgAmAMjHgAwApAIWAYyQABABMAZGTABABSAYyVAAgMZAAA.YAAAAAAAAAAA", "us_privacy": "1---" } } } |
{ "id": "request-id", "bidid": "internal-id", "cur": "USD", "seatbid": [ { "bid": [ { "adid": "1234", "adm": "<VAST version='2.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='vast.xsd'><Ad id='1234.140217073869696'>...</Ad></VAST>", "adomain": [ "example.com" ], "cat": [ "IAB2" ], "cid": "0", "crid": "4:example.com/1234", "dur": 30, "id": "1", "impid": "1", "price": 10 } ], "seat": "FreeWheel" } ] } |
{ "bidid": "25538_1559714932183049-244_1", "cur": "EUR", "id": "25538_1559714932183049-244_1", "seatbid": [ { "bid": [ { "adid": "723012", "adm": "<VAST version='3.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='vast.xsd'><Ad id='723012.139762086734464' sequence='1'>...</Ad></VAST>", "adomain": [ "StickyAds.com" ], "cid": "0", "crid": "2:072d87f9f9ac654758112d62eeee0d8b7160606694818028045", "dur": 10, "id": "1", "impid": "1", "price": 27.522 }, { "adid": "733012", "adm": "<VAST version='3.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='vast.xsd'><Ad id='733012.139762086735360' sequence='1'>....</Ad></VAST>", "adomain": [ "StickyAds.com" ], "cid": "0", "crid": "3:54ed7ea4060b7bc2b9d7c7bf4e603d5316489806525904299806", "dur": 16, "id": "2", "impid": "1", "price": 9.183174 }, { "adid": "713012", "adm": "<VAST version='3.0' xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance' xsi:noNamespaceSchemaLocation='vast.xsd'><Ad id='713012.139762086733568' sequence='1'>...</Ad></VAST>", "adomain": [ "StickyAds.com" ], "cid": "0", "crid": "1:aa2ebc0fc2c33e7760c2196d0dd35fc413823698032879037899", "dur": 30, "id": "3", "impid": "1", "price": 27.522 } ], "seat": "FreeWheel" } ] } |