In some customer use cases, a video stream may be a mixture of the main content and other segments that are not considered real content in a strict sense. For example, a publisher may allocate one or more short segments (at the beginning or in the middle) of the video stream to show promotional material to viewers.

Ideally the data metrics and events collected by Datazoom should be adjusted to account for these “non-content” segments. However, oftentimes a media player is unable to distinguish between the content/non-content sections because they all appear to be part of a single homogeneous video stream.

To assist media players in identifying such “non-content” segments, a publisher may choose to inject special purpose markers (usually some form of timed metadata) into the video stream, which would require extra attention in the data processing flow. If the required timing information is available to the application directly through the publisher’s content management system or similar means, the following Datazoom collector interface can be used to pass the information to help Datazoom adjust the collected data accordingly.

Set Content Timeline Annotations

The Datazoom collector context interface exposes a method for this purpose:

context.annotateContentSession(array_of_annotated_time_spans) {}

For example, the following snippet informs the Datazoom collector about a 10 second promotional video at the beginning of playback and again at 10 minutes into playback:

// Create the video player and the collector context
var my_player = ...;
var datazoom_context = datazoom.createContext(my_player);

// Set content timeline annotations before starting playback
datazoom_context.annotateContentSession([
    { start: 0,   end:  10, type: datazoom.timeSpanType.PROMO },
    { start: 600, end: 610, type: datazoom.timeSpanType.PROMO }
]);

The method takes a single array argument consisting of objects with the following fields:

Field name	Format	Remarks
start	Number (in seconds)	The starting time position of the annotated time span in seconds, relative to the beginning of the video stream
end	Number (in seconds)	The ending time position of the annotated time span in seconds, relative to the beginning of the video stream
type	String as enumerated in `datazoom.timeSpanType`	The type of the annotated time span (for example, `datazoom.timeSpanType.PROMO` or “promo” literally)

Please note that:

The time ranges of the annotated time spans should not overlap. However, having one time span follows immediately after the other is allowed.
Datazoom may add more time span type definitions (enumerated in datazoom.timeSpanType) to be used along with this method in the future.
Datazoom may add additional fields to the time span object, in order to associate more data or properties with the specific segment in the future.

The Setting of Timeline Annotations is Time-critical

Please also note that the setting of the timeline annotations (i.e., the invocation of the annotateContentSession() method) is time-critical: it should be done before the beginning of the corresponding content session. In other words, if the annotation info isn’t available until after the content session plays, it would be too late to adjust crucial data metrics such as accumulated playback duration or milestone events. Because of this, any late annotateContentSession() call will not apply to an ongoing content session (but it will apply to the context’s next content session, if any).