The Interactive Media Ads (IMA) Dynamic Ad Insertion SDK (DAI) relies on metadata information embedded in the stream's media segments (in-band metadata), or in the streaming manifest file (in-manifest metadata) to track viewers' positions and client-side ad events. Metadata is available from the DAI stream in different formats, depending on the type of stream being played. The IMA DAI SDK handles all metadata formats through a single API.
Your app is responsible for capturing metadata and forwarding it to the IMA DAI SDK. The SDK offers the
StreamManager.onMessage()
method to pass this information. This method forwards metadata in the form of a
msg
object provided by the roVideo port. These objects are then processed by
the IMA DAI SDK to establish the timing for ad events. It takes a single
argument:
msg
: a msg type object provided by the roVideo port.
Metadata sample code
Here's an example of how to handle the metadata from the roVideo port and
pass it to the IMA DAI SDK through StreamManager.onMessage()
.
Sub runLoop()
' Forward all timed metadata events to IMA.
m.top.video.timedMetaDataSelectionKeys = ["*"]
' Cycle through all the fields and set listeners.
' IMPORTANT: Failure to listen to the position and timedmetadata fields could
' result in ad impressions not being reported.
m.port = CreateObject("roMessagePort")
fields = m.top.video.getFields()
for each field in fields
m.top.video.observeField(field, m.port)
end for
while True
msg = wait(1000, m.port)
if m.top.video = invalid
print "exiting"
exit while
end if
m.streamManager.onMessage(msg)
currentTime = m.top.video.position
If currentTime > 3 And not m.top.adPlaying
m.top.video.enableTrickPlay = true
End If
end while
End Sub
For more information on how to incorporate the loop handling stream metadata into your app, see the IMA Roku getting started guide. The event listener and stream start section of the guide contains the metadata handling loop.
HLS CMAF streams
Linear DAI HLS streams using the Common Media Application Framework (CMAF) pass timed metadata through in-band eMSGv1 boxes following the ID3 through CMAF standard. These eMSG boxes are embedded at the beginning of each media segment, with each ID3 eMSG containing a PTS relative to the last discontinuity in the stream.
For IMA Roku, all HLS CMAF streams send in-band ID3 data using the eMSGv0 format. IMA combines information provided by the eMSGv0 format with information from the video object.
To enable proper parsing of HLS CMAF stream ID3 events, you must send your
video object in the stream request using
StreamRequest.videoObject
.