Managing AddressableTV Campaigns
Introduction
Addressable TV Ad formats that are run on broadcast networks require configuration on both Icareus Suite (campaigns, creatives, integrations, ...) and Icareus Playout (HbbTV signalling, broadcast synchronization, etc).
Requirements for AddressableTV campaigns:
- There needs to be a Channel configured on Suite
- There needs to be a HbbTV Launcher on-air with Icareus Pixel activated
- There needs to be a HbbTV carousel available that can be used to send stream events
Launcher App with Icareus TV Pixel
Using the Addressable TV requires an application running on HbbTV that takes control of the user input and experience. The application is normally called a Launcher. When using Icareus Launcher it automatically has Icareus TV Pixel integrated and thus easily available. Alternatively you can integrate Icareus Pixel with your own hbbTV application.
Creating a Launcher Application on Suite
To create a HbbTV Launcher on Icareus Suite navigate to APPS and click the 'Add' button. Select 'HbbTV Launcher' as the 'TYPE'.
While creating the HbbTV Launcher Application, make sure that 'Addressable TV' is enabled.
Make sure to also select a Channel for the launcher.
The selected Icareus Suite Linear Channel's name needs to match the name of the DVB Service in PMC that the launcher is attached to!
Finally click 'Save' to create the HbbTV Launcher Application.
Stream-event configuration for Addressble TV Campaigns
Some additional configuration is required in order to make triggered ads work on the launcher.
A XML file needs to be created in the launcher's web folder (Usually /opt/nginx/html/hbbtv/launcher on suitecache.icareus.com). The name of the XML file should be 'event_<LAUNCHER_APPLICATION_ID>.xml'.
Example XML:
- <?xml version="1.0" encoding="UTF-8"?>
<dsmcc xmlns="urn:dvb:mis:dsmcc:2009">
<dsmcc_object component_tag="55">
<stream_event stream_event_id="1" stream_event_name="ad_trigger" />
</dsmcc_object>
</dsmcc>
dsmcc_object_component_tag needs to match the 'Stream event component tag' of the launcher application on Playout.
The 'Stream event component tag' of the application can be obtained in PMC by opening the 'Applications repository' and selecting the launcher application in question.
If the 'Stream event component tag' is listed as 'Auto', it is recommended to manually assign a value to it. This can be done by right-clicking the launcher application in the 'Applications repository' list in PMC, selecting 'Properties' and then unchecking the checkbox for 'auto' and entering a value by hand.
If the application was originally added to PMC with 'Stream event component tag' set to 'Auto', it is possible to find the automatically assigned component tag by navigating to 'Status' > 'Reserved Ids' and selecting the 'Component tag' tab from the 'Playout ID viewer' view.
Correct configurations need to be present in the Icareus Playout Server's 'campaignhandler.conf' file in '/opt/playout/conf/campaignhandler.conf' in order for automatic triggers to work!
Configuration of Icareus Playout for AddressableTV
Icareus Playout has a key role in executing Addressable TV advertising in HbbTV environment. It interacts closely with Icareus Suite and Broadcasters traffic management or playout system to generate necessary triggers to synchronise advertising with the linear broadcast.
Icareus Suite Addressable TV module provides information about active campaigns to Icareus Playout to ensure that all campaigns are in-sync. Data is polled from Icareus Suite to Playout.
Formats impacted by this Icareus Playout configuration
ActiveAd
VideoSwap
AFTER THE CONFIGURING IS DONE THE PLAYOUT-ADMIN PROCESS MUST BE RESTARTED IN ORDER TO GET THE NEW VALUES INTO USE. SEE COMMAND BELOW
| [root@admin ~]# service playout-admin restart |
The configuration is done in the file /opt/playout/conf/campaignhandler.conf.
The table below describes the configuration file parameters.
Name | Value | Example | Requirement | Descriptions |
sourceIdChannel | 21 <Estradi> 12000 tcp 3000 1 false | |||
suitePollerIP | suite.icareus.com | |||
suitePayloadIP | suite.icareus.com | |||
suiteProtocol | https | |||
organizationId | 103709 |
Integration to synchronise addressable TV ads with Linear broadcast
Icareus Playout provides different APIs for integration and to trigger synchronized ads on-screen.
Supported AdFormats
ActiveAd
VideoSwap
The APIs can be used to integrate with existing systems for broadcasters to automate the ad triggering on-screen.
Some example flows given below.
Automation Examples
1) Video playout automation
The video playouts of broadcasters may have available features to trigger TCP or HTTP connections whenever there is a change in e.g. broadcasted programme/event. If that event is an advert and Icareus Playout has information on that event via the data ingestion or manual upload it will automatically trigger a stream event on the appropriate channel.
Example
Events in broadcast: Event1 (News), Event2 (Ad), Event3 (TV Show)
Broadcaster’s video playout sends a TCP/HTTP trigger on every event to Icareus Playout. But Icareus Playout only has information on Ads, so:
Trigger for Event1 -> Ignored
Trigger for Event2 -> Stream event sent -> Active Ad Launched
Trigger for Event3 -> Ignored
2) Custom automation
Since all trigger mechanisms provided by Icareus Playout are standard technologies. They can easily be automated using standard mechanisms' server scripts.
Example
There is a schedule file with a precise schedule for each advert. A server side script (NodeJS, JAVA etc.) can easily be created that reads that file and triggers an HTTP call whenever there is time for an advert. The same file can be ingested to suite beforehand so that it has data already available for Icareus Playout.
An example script(pseudo-code) could be:
//PSEUDO-CODE
adverts = parseFile(advertSchedule)
now = getTime()
for(advert in adverts) {
if(advert.time==now) {
triggerHttpCallToPlayout(advert)
}
}
Icareus Playout API
TCP API
Icareus Playout provides a TCP socket based interface to receive triggers for a particular Advert based on the data available and synchronized from Icareus Suite.
The ID 12345 is available in Suite when playlists are ingested to Icareus Suite.
TCP message <12345> sent to Icareus Playout on port 1234. Playout has information about ID 12345 and knows that this advert is assigned to campaign running on Channel X. Playout will automatically create and trigger a Do-It-Now (DIN) stream event for this campaign on channel X.
29843299
Http API
Icareus Playout also provides an HTTP based interface to trigger adverts, this is also for a particular Advert based on the data available and synchronized from Icareus Suite.
The source-Id parameter is obtained via Playout Management Console (PMC). It is the value of the "Database Id" for an application in the applications repository.
Playout will trigger a Do-It-Now (DIN) stream event for this campaign on channel as provided in the payload.
Example:
Example HTTP call
http://<playout-server-ip>:8080/campaignhandler/triggerhandler?channel=<X>&lyid=<12345>
X = channel name as defined in Icareus Playout and Suite
lyid = mediaId that is currently being played out on broadcasters video playout
UDP API
UDP trigger with key value:
1211212336
Triggering Ads On-screen Manually
Using Playout Management Console
Open Playout Management Console (PMC)
Right click the application, add/edit stream events. Add stream object called “suite_ads”. Add event called “ad_trigger” (type is 'do it now' event)
Attach the application to the intended service. Click on the attached application and note the “Database/Carousel Id” of it (from the panel on the right) and note it down.
On PMC open “Status” menu and go to “Reserved Ids” > “Component Tags”. There check the ID of “dsmcc-carousel” && "dsmcc-stream-event" for the application above. Note these and send them to Icareus.
Two mechanisms are defined for referencing sources of stream events from applications:
- By referencing a DSM-CC stream event object in an object carousel. This requires the service to contain an object carousel as well as the elementary stream carrying the stream event messages.
- By referencing an XML file containing equivalent information to the DSM-CC stream event object. This enables synchronization to services carrying the stream event messages but not containing an object carousel.
Currently we support just the latter approach.
Using HTTP API
It is mandatory to generate two different campaign trigger URLs. First one is "download the data" and second is "trigger the ad". The example payloads for these are shown above.
The channel name above should also exactly match the channel name set on Playout
To trigger stream events via playout HTTP API:
http://<ip/address of playout server>:8080/event?Source-Id=<DB/Carousel ID noted above>&Object-Name=suite_ads&Event-Name=ad_trigger&Payload=<Payload URLs defined above to trigger campaign>
The value for parameter"initial_path_bytes" should be taken from the index.html part of that same URL, and add also a channelId (and in case of Video Swap, also a region).
A "channelId" is a "System Id" of the channel used in Icareus Suite Addressable TV.
Examples of Stream-event Payloads
ACTIVE AD
DOWNLOAD DATA STREAM-EVENT WITH DELAY INFORMATION
scheme:http,addr:suite.icareus.com,path:/api/campaign,p_trigger:download,p_action:getCampaign,p_delay:6000,
p_campaignId:7354154,p_type:activead,p_channel:NovaTV,p_ts:1506939166845
TRIGGER THE AD STREAM-EVENT
p_trigger:trigger,p_type:activead,p_ts:1506939172845
VIDEO SWAP
DOWNLOAD DATA STREAM-EVENT WITH DELAY INFORMATION
p_trigger:download,p_delay:5000,p_type:videoswap,p_breakId:1006010000,p_channel:NovaTV,p_ts:1507206502667
TRIGGER THE VIDEO SWAP STREAM-EVENT
p_trigger:trigger,p_type:videoswap,p_ts:1507206507667
Monitoring and Troubleshooting
The Playout logs with useful information can be viewed from /var/log/messages.
When playout-admin process is started, all information related to sourceIdChannel tag are logged. After that all ports that have been started to be listen to are also logged. Every time the trigger is received to some of these ports, the key and port number are logged.
It is also logged whether received key did or didn't match to any of the key list. When the received key matches to some on the list, payload URL is sent to the Suite and the URL is also logged.
When new key list is fetched from Suite, the number of keys of that list is also logged.
Related Articles
VideoSwap Format and Configuration
Introduction VideoSwap format is Icareus' solution for Dynamic Ad insertion or substitution (DAS). It enables substitution of linear TV spots or pods with more personalised video ads. Supported platforms HbbTV OTT Browser based set-top box ...Introduction to Addressable TV
INTRODUCTION Icareus Suite enables broadcasters to maximise their revenue with Addressable TV formats. Icareus Suite in collaboration with Icareus Playout can be used to trigger and synchronise Display Ads and replace the broadcasted commercials with ...ActiveAd Configuration
Introduction In order to successfully display Active Ads on a device, the following things are required: HbbTV Launcher Application Active Ad Campaign Creative Adding an Active Ad Campaign Campaigns can be added in Icareus Suite by navigating to ...Microsite
Introduction A microsite is actively used as a landing page for Addressable TV campaigns. It offers a variety of features to provide additional information to viewers and collect their contact details in a GDPR compliant way. Supported Platforms ...SwitchIn Format and Configuration
Introduction SwitchIn is a simple ad format where viewers are shown a Display ad when they enter a TV channel. In order to successfully display SwitchIns on a device, the following things are required: HbbTV Launcher / Red-button Application SwitchIn ...