As we kept improving the user experience on broadpeak.io, we introduced a new way to handle Categories (also called Audiences) when dealing with Content Replacement or Virtual Channel Applications a couple of weeks ago. Here is a summary of what we did.
What were the changes
Until the change, “Categories” were not managed as defined objects in our platform. It was possible to specify a Category or a list of zip codes as conditions of Content replacement or Virtual Channel slots. However this condition was not stored in our backend, nor could it be retrieved, nor re-used. This update allowed API users to use Categories as objects in order to manage their lifecycle in broadpeak.io.
What was the impact on the REST API
New REST API endpoints were available to manage the lifecycle of a Category object, more details can be found in the API reference in our knowledge center.
Basically, broadpeak.io generates an Id on your behalf for each Category object created that you can retrieve through API.
When creating a Content Replacement or Virtual Channel slot, one can specify the id of a defined Category after it has been made.
The possibility to create a category with a list of values is being removed, which now requires to create a Slot with a dedicated category for each value.
- Previously: Combined request for UserId 1 and 2 as Audience values
{
"name": "Content Replacement slot A",
"startTime": "2022-02-25T12:30:00Z",
"duration": 120,
"replacement": {
"id": 2
},
"categories": [
{"value": "userid1"},
{"value": "userid2"}
]
}
- After the change: Single request per UserId value
As a first step, we need to create 2 categories, one for each userid, and retrieve the category Ids. In this example we will assume the Id are respectively 1 and 2 for category userid1 and userid2).
Request for UserId 1
{
"name": "Content Replacement slot A",
"startTime": "2022-02-25T12:30:00Z",
"duration": 120,
"replacement": {
"id": 2
},
"category": {
"id": 1
}
}
Request for UserId 2
{
"name": "Content Replacement slot A",
"startTime": "2022-02-25T12:30:00Z",
"duration": 120,
"replacement": {
"id": 2
},
"category": {
"id": 2
}
}
What was the impact on the ESNI API
On the ENSI API, “Categories” in fact are named “Audiences“.
No additional endpoints have been created for the ENSI API, and the documentation is still available in the knowledge center here.
With the new method, Audiences only exist if they have been defined when creating a new Content Replacement or Virtual Channel slot. The Id of the Audience is being by the API users, so re-using the same Id would erase the previous Audience.
Note: Category (Audience) object created through ESNI API are also usable through REST API.
Some changes have been made when dealing with Audience values, as opposed to zip code. The possibility of creating an Audience with a list of values is being removed, which now requires creating a Slot with a dedicated Audience for each value.
- Previously: Combined request for UserId 1 and 2 as Audience values
<Media href="MyServiceName">
<MediaPoint id="mySlot" matchTime="2022-12-22T14:15:00Z" expectedDuration="PT0H1M">
<Apply>
<Policy id="1">
<ViewingPolicy id="1">
<Audience id="IOS"
<broadpeak:Category>userid1</broadpeak:Category>
<broadpeak:Category>userid2</broadpeak:Category>
</Audience>
<action:Content>urn:scte:224:action:blackout</action:Content>
</ViewingPolicy>
</Policy>
</Apply>
</MediaPoint>
</Media>
- After the change: Single request per UserId value
Request for UserId 1
<Media href="MyServiceName">
<MediaPoint id="mySlot" matchTime="2022-12-22T14:15:00Z" expectedDuration="PT0H1M">
<Apply>
<Policy id="1">
<ViewingPolicy id="1">
<Audience id="userid1" match="ANY">
</Audience>
<action:Content>urn:scte:224:action:blackout</action:Content>
</ViewingPolicy>
</Policy>
</Apply>
</MediaPoint>
</Media>
Request for UserId 2
<Media href="MyServiceName">
<MediaPoint id="mySlot" matchTime="2022-12-22T14:15:00Z" expectedDuration="PT0H1M">
<Apply>
<Policy id="1">
<ViewingPolicy id="1">
<Audience id="userid2" match="ANY">
</Audience>
<action:Content>urn:scte:224:action:blackout</action:Content>
</ViewingPolicy>
</Policy>
</Apply>
</MediaPoint>
</Media>
What to do if you are using Categories
Today, there is nothing to implement as the previous way of handling Categories is preserved on the platform. We will soon let you know a removal date, but we will ensure that it gives you enough time to do the transition.
Please reach out if you need help transitioning to the new method.
Need more info? Here you have a list of technical resources:
- API Reference
- More information about how to deal with Audiences can be found here.
- Postman Collection have been updated and is available here.
Streamingly yours,
The broadpeak.io team.
Picture from Suzanne D. Williams on Unsplash
