Overview
An Ad Unit is a "class" of ad. Users can use Ad Unit Nodes to pair ad opportunities in requests with the appropriate ads booked in MRM.
Note
The Placement API v3 ad product section updates ALL of a placement's ad units. This API only updates one ad unit in a placement.
Use the Ad Unit Node API V3 to accomplish the following tasks:
- List ad unit nodes within the current network in most-recent-first order
- Show information about an ad unit node
- Update an ad unit node
- Activate an ad unit node
- Deactivate an ad unit node
- Link creative or update linked creative status
- List all linked creatives
Related Documentation
Refer to the following documentation for more information about FreeWheel products and APIs:
Resources
URI(s)
The Ad Unit API v3 identifies two Uniform Resource Identifiers (URIs):
| Environment | URI |
|---|---|
| Production | https://api.freewheel.tv/services/v3/ad_unit_nodes/[FW_ID].xml?[parameter1]=[query1]&... |
| Staging | https://api.stg.freewheel.tv/services/v3/ad_unit_nodes/[FW_ID].xml?[parameter1]=[query1]&... |
Ad Unit Node API Attributes
Attributes represent and describe data associated with an object, in this case the Ad Unit Node object. Attributes are organized in sets. The attribute set determines the fields available during data entry, and the values that appear to the client. Use Ad Unit Node API Attributes in conjunction with Ad Unit Node API methods to accomplish your ad tech objectives.
Basic Attributes
The purpose of this attribute set is to identify and define an ad unit node. Basic attributes describe fundamental properties of an ad unit. These attributes identify the name, ID, billing term, discounts, contacts, user assignments, address, financial information, industry, and status of the ad unit.
None of the attributes below are creatable.
| Function/Node | Description | Data Type(s) | Included in basic GET? | Updatable? | Comments |
|---|---|---|---|---|---|
| id | The ID of the ad unit node | FW_ID | No | No | Assigned automatically during POST |
| name | The name of the ad unit | String | No | Yes | |
| ad_unit_id | The ID of the ad | FW_ID | No | Yes | |
| placement_id | The ID of the placement to which this ad unit node belongs | FW_ID | No | Yes | |
| external_id | The external ID of the ad unit node | String | Yes | Yes | |
| price_model | The price model of the placement | 'ACTUAL_EcPM', 'FLAt-FEE_SPONSORSHIP' | No | Yes | |
| price | The price of the ad unit node | Float | No | Yes | |
| accounting_price | The accounting price| | Float | Yes | Yes | Valid only when placement_type == MAKE_GOOD |
| budget | The budget info of the ad unit node | Budget Attributes | Yes | Yes | |
| status | The MRM status of the ad unit node | 'ACTIVE', 'IN_ACTIVE' | No | Yes | These values must be provided in ALL CAPITAL letters. |
| type | The type of the ad unit| | 'INSTREAM', 'OVERLAY', 'DISPLAY' | No | Yes | |
| regulated_display | Indicate if the ad unit node is a regulated display ad | Boolean | Yes | Yes | Valid only when type == DISPLAY and link_method = LINK_WHERE_POSSIBLE or ALL_LINKED |
| ad_unit_package_id | The ID of the ad unit package that the ad unit node belongs to | FW_ID | No | Yes | Valid only when the ad unit was added from the ad unit package |
| creative | The creative info of the ad unit node | Creative Attributes | Yes | No | |
| bid_price | The bid price of the ad unit node. | Decimal | Yes | Yes | Bidding capabilites are gated by a network function. Contact your FreeWheel account team for more information. |
| bid_price_settings | The bid price configuration of the ad unit node. Valid values: NOT_SET NETWORK_DEFAULT OVERRIDE_RATIO OVERRIDE_PRICE | Enum | Yes | Yes | Bidding capabilites are gated by a network function. Contact your FreeWheel account team for more information. |
| bid_price_override_ratio | The ratio that a user manually sets as the % of ad unit price for bid price | Enum | Yes | Yes | Bidding capabilites are gated by a network function. Contact your FreeWheel account team for more information. |
Budget Attribute Definitions
All of the parameters below are updatable and included in basic GET requests.
| Function/Node | Description | Data Type(s) | Creatable? | Comments |
|---|---|---|---|---|
| impression_cap | The impression cap for this specific ad unit | Integer | No | Valid only when link_method is NOT_LINKED, LINK_WHERE_POSSIBLE or advanced linking |
| exclude_from_invoice | Indicates if the ad unit node should be excluded from the invoice | Boolean | No | Valid when budget_model != 'EVERGREEN' |
| exclude_from_budget | Indicates if the ad unit node should be excluded from the insertion order's budget | Boolean | No | Valid only when link_method is LINK_WHERE_POSSIBLE, ALL_LINKED or custom set |
Creative Attribute Definitions
None of the parameters below are creatable nor included in basic GET requests.
| Function/Node | Description | Value Type | Updateable? |
|---|---|---|---|
| id | The id of the creative | FW_ID | No |
| name | The name of the creative. | String | No |
| status | The status of the creative. Valid values: ‘ACTIVE’, ‘IN_ACTIVE’ | enum | Yes |
Basic Attributes POST Code Sample
The following example POST code shows you how to set up a budget for an ad unit node.
<ad_unit_node>
<budget>
<exclude_from_invoice>true</exclude_from_invoice>
<exclude_from_budget>true</exclude_from_budget>
<impression_cap>100</impression_cap>
</budget>
</ad_unit_node>