Introduction
Audience Items represent an audience segment you want to target. They are defined by the third-party audience tracking provider you have chosen to integrate with MRM rather than by FreeWheel.
You can reuse audience items for all the sites and site sections within your network. You can customize the audience item name, draw multiple data sources across providers, and combine data sources into one audience item.
With Audience Item API V3, you can:
- Show audience items
- Create audience items
- Update audience items
Related Documentation
Refer to the following documentation for more information about FreeWheel products and APIs:
- Getting Started with the FreeWheel APIs
- Getting Started with Authentication
- API Resources
- Audience Content - MRM User Guide
Resources
URIs
The Audience Item API v3 identifies two Uniform Resource Identifiers (URIs):
| Type of URI | URI |
|---|---|
| Production | https://api.freewheel.tv/services/v3/audience_items/[FW_ID].xml?[parameter1]=[query1]&... |
| Staging | https://api.stg.freewheel.tv/services/v3/audience_items/[FW_ID].xml?[parameter1]=[query1]&... |
Audience Item API Attributes
Attributes represent and describe data associated with an object, in this case the Audience Item object. Attributes are organized in sets. The attribute set determines the fields that are available during data entry, and the values that appear to the client. Use Audience Item API Attributes in conjunction with Audience Item API methods to accomplish your ad tech objectives.
Basic Attributes
The following attributes are included in basic GET requests.
| Function/Node | Description | Data Type(s) | Creatable? | Updatable? | Notes |
|---|---|---|---|---|---|
| id | Resource ID | FW_ID | No | No | Assigned automatically during POST |
| name | The name of the audience item | String | Yes | Yes | Must be unique in the network. Accepted length of name string is between 3 and 255 characters. |
| description | Description of the audience item | String | Yes | Yes | Maximum accepted length of description string is 2048 characters. |
| external_id | External ID for the audience item | String | Yes | Yes | Must be unique in the network |
| precedence | Precedence of the audience item | Integer | Yes | Yes | Accepted values are between -100 and 100. |
| status | Status for the audience item |
| Yes | Yes | These values must be provided in ALL CAPITAL letters. |
| created_at | The created time of the audience item | Datetime | No | No | |
| custom_targeting | The custom targeting criteria | Custom Targeting Criteria | Yes | Yes | There should be at least one key-value pair. |
Custom Targeting Criteria Attributes
The following attributes are included in basic GET requests.
| Function/Node | Description | Data Type(s) | Creatable? | Updatable? |
|---|---|---|---|---|
| include | Contains sets of key-value pairs to include in the audience item targeting | Targeting Inclusions Attributes | Yes | Yes |
| exclude | Contains key-value pairs that need to be excluded from audience item targeting | Targeting Exclusions Attributes | Yes | Yes |
Targeting Inclusions Attributes - Child Attributes of Custom Targeting Criteria Attributes
The following attributes are included in basic GET requests.
| Function/Node | Description | Data Type(s) | Creatable? | Updatable? | Notes |
|---|---|---|---|---|---|
| set | Contains key-value pairs and the relation between them | Include Sets | Yes | Yes | Sets and the placement of relation_between_sets are strictly interpreted based on the order in which they are provided in the request. For example, in the Create method sample below, the first and second nodes would have an OR relationship because it is placed between them. HTTP responses would be similarly ordered. |
| relation_between_sets | The relationship between the sets to include |
| Yes | Yes | The number of relation_between_sets nodes must be smaller than the number of set nodes by 1. |
Include Sets Attributes - Child Attributes of Targeting Inclusions Attributes
| Function/Node | Description | Data Type(s) | Creatable? | Updatable | Included in basic GET? | Notes |
|---|---|---|---|---|---|---|
| key_value | Key/value pair | Set | Yes | Yes | Yes | Must follow the specific format key=value. When you use attributes hosted by FreeWheel (true for most Audience Item API V3 scenarios), a prefix indicating the data provider must also be applied. A full key/value pair would follow this format: _fwu:[dataProviderID]:[attributeName]=[attributeValue]. Accepted length of key string is between 1 and 125 characters. Accepted length of value string is between 1 and 125 characters. |
| relation_in_set | Relation of key-value pairs within the set |
| Yes | Yes | Yes |
Targeting Exclusions Attributes - Child Attributes of Custom Targeting Criteria Attributes
| Function/Node | Description | Data Type(s) | Creatable? | Updatable | Included in basic GET? | Notes |
|---|---|---|---|---|---|---|
| key_value | Key/value pair | Set | Yes | Yes | Yes | Must follow the specific format key=value. When you use attributes hosted by FreeWheel (true for most Audience Item API V3 scenarios), a prefix indicating the data provider must also be applied. A full key/value pair would follow this format: _fwu:[dataProviderID]:[attributeName]=[attributeValue]. |