MRSS feed elements for Video Solutions

This is the new version of the MRSS feed specification for Video Solutions.
This version simplifies the ingestion of MRSS content sources, and allows for improved error handling and syncing. The table lists all of the fields that Video Solutions recognizes (and in some cases, expects) in your XML feed. Only these elements are recognized.

Jump to a specific element in the list

Required elements
<atom:link>
<item>
<dfpvideo:contentId>
<dfpvideo:lastModifiedDate>
<dfpvideo:version>
<title>

Recommended and optional elements
<dfpvideo:cuepoints>
<dfpvideo:keyvalues>
<dfpvideo:thirdPartyContentId>		 <media:content>
<media:status>
<media:thumbnail>		 <pubDate>
<tms:tmsId>
<tms:tmsSeriesId>

Dynamic Ad Insertion elements

These elements are specific to Dynamic Ad Insertion, and should be used in combination with the elements above.

<dfpvideo:ingestUrl>
<dfpvideo:lastMediaModifiedDate>
<dfpvideo:closedCaptionUrl>
<dfpvideo:fw_caid>

See an example of the elements in context in the sample feed.

The content ID is now case sensitive. A content ID with both uppercase and lowercase letters is considered separate from the same ID with only lowercase letters. This is reflected in your Ad Manager reports.

Required elements

<atom:link> <channel> Required
Description
Identifies the feed's paging information. Ad Manager reads this element for two attributes: rel and href.
  • rel indicates how the URL in the href attribute relates to the feed's result set.
    • rel='next': Indicates that the href URL points to the next page of the feed's result set. If the feed contains an <atom:link> tag with rel='next', this indicates that there's another page of results. Otherwise, the current page is the last page in the result set.
  • href specifies a URL that identifies the resource in the <atom:link> tag.
Example:
<atom:link rel='next' href='http://www.feedprovider.com/video/account/vids?page3'/>

Important notes:

  • When Ad Manager first creates a content source, it expects that the feed URL set returns the first result-set of the feed. A result-set of 100 items (per page) is recommended.
  • If the <atom:link> element is absent from a page of the feed, Ad Manager considers that page the last page of the feed.

back to top

Element Child element of Requirement
<item> <channel> Required
Description
Identifies a single video in the feed. An Ad Manager video feed may contain one or more <item> entries. Each of them are required to contain three elements for proper metadata ingestion:

<dfpvideo:contentId>, <dfpvideo:lastModifiedDate> and <title>

back to top

Element Child element of Requirement
<dfpvideo:contentId> <item> Required
Description
Stored as the CMS content ID in Ad Manager, this is an important request parameter, formed as a part of the ad request to identify which ads Ad Manager can serve against the corresponding video. This value can be used for the vid parameter on a video ad request. It can be numeric or alphanumeric, and is case sensitive.

Example:
<dfpvideo:contentId>sdjfbadfb8w3489y</dfpvideo:contentId>

back to top

Element Child element of Requirement
<dfpvideo:lastModifiedDate> <item> Required
Description

Indicates when any aspect of the video or its metadata was last modified.

In order for Ad Manager to ingest modified content, the lastModifiedDate should be specified and the feed must be ordered by most recently modified at the top.

All time stamps must conform to RFC 822 specification or follow IS0 8601 format. If the time zone is not included in the time stamp string, it defaults to Pacific Standard Time (PST).


Examples:
<dfpvideo:lastModifiedDate>2006-02-19T04:22:39+05:00</dfpvideo:lastModifiedDate>
<dfpvideo:lastModifiedDate>Sun, 19 Feb 2006 09:22:39 +0000
</dfpvideo:lastModifiedDate>
See examples of each date format

RFC 822 examples

  • Wed, 31 Oct 2016 08:00:00 EST
  • Wed, 31 Oct 2016 13:00:00 GMT
  • Wed, 31 Oct 2016 15:00:00 +0200

ISO 8601 examples

  • 20161031
  • 2016-10-31
  • 2016-10-31T08:00:00+01:00

back to top

Element Child element of Requirement
<dfpvideo:version> <channel> Required
Description
Indicates the current version of the MRSS spec that this feed uses. The value should be populated with an integer, and set once per feed.

The only current valid value for this field is 2.

Example:
<dfpvideo:version>2</dfpvideo:version>

back to top

Element Child element of Requirement
<title> <item> Required
Description

The name of the video entry.


Example:
<title>My video</title>

back to top

Recommended and optional elements

Element Child element of Requirement
<dfpvideo:cuepoints> <item> Varies *
Description

* Required if the video contains mid-roll ad breaks.

Identifies the cue points in seconds, separated by commas. Cue points are places in time where an ad can be inserted in the video.

Fractional seconds are supported for up to 3 digits (for example, 55.532 seconds). Additional digits beyond 3 are truncated.


Example:
<dfpvideo:cuepoints>55.532,109</dfpvideo:cuepoints>

back to top

Element Child element of Requirement
<dfpvideo:keyvalues> <item> Optional
Description
Identifies any custom metadata for the video. It has the following attributes: key, value, and type (which is limited to string data types).
 
Key-values ingested via your MRSS feed are subject to the same format requirements as key-values defined within the Ad Manager interface. Ensure your key-values comply with these format requirements.

Examples:
<dfpvideo:keyvalues key="episode" value="5" type="string"/>
<dfpvideo:keyvalues key="season" value="2" type="string"/>
<dfpvideo:keyvalues key="title" value="Example Title" type="string"/>
<dfpvideo:keyvalues key="recommended count" value="5" type="string"/>
<dfpvideo:keyvalues key="description" value="A lot of text here" type="string"/>

back to top

Element Child element of Requirement
<dfpvideo:thirdPartyContentId> <item> Optional
Description

This feature needs to be enabled before use. To use, contact your account manager.

This element is used if you have a custom MRSS feed that contains YouTube videos. No two MRSS content under your network should specify the same YouTube video.

There is only one required attribute for this element:

  • "id" attribute: This must refer to the contentId in the YouTube content source.

Example:
<dfpvideo:thirdPartyContentId cms="youtube" id='vNclnVLp_c0'/>
 

back to top

Element Child element of Requirement
<media:content> <item> Recommended
Description

This element has attributes that provide useful metadata information, such as the source URL and duration. It is an optional sub-element of <item>.

Ad Manager can read the following attributes of the <media:content> element:

  • "duration" attribute: Ad Manager only recognizes one duration entry per <item>. If more than one is specified, the duration is chosen from an entry at random, which may be unexpected. This attribute is required to deliver mid-roll ads.

    The duration value should be in seconds (whole numbers, no decimals).

  • "url" attribute: The direct URL of the video resource, used only to show a link in the content details within the Ad Manager interface.

Example:
<media:content url='http://www.feedprovider.com/video?8eqe7e' duration='39'/>

back to top

Element Child element of Requirement
<media:status> <media:content> or
<item> 		Optional
Description
Determines whether the video is marked as active, inactive, or archived in Ad Manager. If this element is absent, the default status is active. Values are case insensitive and may include the following state:
  • active (marked "Active" in Ad Manager)
  • deleted (marked "Archived" in Ad Manager; new "deleted" videos are not ingested)
  • blocked (marked "Inactive" in Ad Manager)
If a user changes the status for a video within Ad Manager, any subsequent status changes from the feed are ignored. A user can remove the override by clicking "Use source setting" in the Ad Manager interface, after which Ad Manager will resume using status updates from the feed.

Serving status when serving via Dynamic Ad Insertion

The serving status for Dynamic Ad Insertion is determined by factoring both the status of the source and the content itself. Content marked as inactive or archived will not serve via Dynamic Ad Insertion.

Here is the behavior you can expect when both values are considered:

Content source status Content status           Serving status             
Active Active Content serves
Active Inactive Content serves
Active Archived Content doesn't serve (404 error)
Inactive Active Content doesn't serve (404 error)
Inactive Inactive Content doesn't serve (404 error)
Inactive Archived Content doesn't serve (404 error)
Archived Active Content doesn't serve (404 error)
Archived Inactive Content doesn't serve (404 error)
Archived Archived Content doesn't serve (404 error)
 
  • Active: Eligible to serve ads.
  • Inactive: Ineligible to serve ads. Content will not serve via Dynamic Ad Insertion.
  • Archived: Ineligible to serve content-targeted ads, but it may still serve run-of-network ads. Content will not serve via Dynamic Ad Insertion.


Examples:
<media:status state="blocked" reason="http://www.reasonforblocking.com"/>
<media:status state="deleted"/>
<media:status state="active"/>

(Ad Manager does not ingest the reason attribute.)

back to top

Element Child element of Requirement
<media:thumbnail> <media:content> or
<item> 		Recommended
Description
Allows the thumbnail of the video to appear in the Ad Manager interface. Ad Manager currently only needs the URL attribute of this element, but you can provide additional attributes if desired: height, width, and time (the amount of time that the image, represented by the thumbnail, appears in the video).

The Ad Manager interface never displays a thumbnail larger than 280 pixels wide and 190 pixels high. If the url links to a larger image, Ad Manager links to the original version but visually scales the image with inline CSS for display in the UI.


Example:
<media:thumbnail url='http://www.myfeed.com/account/sdjfbadfb8w3489y/bigtn.jpg' width='280' height='190'/>

back to top

Element Child element of Requirement
<pubDate> <item> Optional
Description

Identifies the date on which the content was published. This element is only used for video ad rules.

All timestamps must conform to RFC 822 specification or follow IS0 8601 format. If the time zone is not included in the time stamp string, it defaults to Pacific Standard Time (PST).


Examples:
<pubDate>2006-02-19T04:22:39+05:00</pubDate>
<pubDate>Sun, 19 Feb 2006 09:22:39 +0000</pubDate>
See examples of each date format

RFC 822 examples

  • Wed, 31 Oct 2016 08:00:00 EST
  • Wed, 31 Oct 2016 13:00:00 GMT
  • Wed, 31 Oct 2016 15:00:00 +0200

ISO 8601 examples

  • 20161031
  • 2016-10-31
  • 2016-10-31T08:00:00+01:00

back to top

Element Child element of Requirement
<tms:tmsId> <item> Optional
Description

A unique 14-character alphanumeric ID for premium TV content, like TV shows and movies, used to relate the program to TV schedules or movie showtimes. These ID are specific to a program's title, description language, and version. They are used for recognizing and synchronizing entertainment assets.

The value for a tmsId should begin with EP (episode), MV (movie), or SP (sports).

Learn more about Gracenote (TMS) IDs.

Examples:
<tms:tmsId>EP123456789000</tms:tmsId>
<tms:tmsId>MV123456789000</tms:tmsId>
<tms:tmsId>SP123456789000</tms:tmsId>

back to top

Element Child element of Requirement
<tms:tmsSeriesId> <item> Optional
Description

Similar to the <tmsId> element, this is a unique 14-character alphanumeric ID of a series parent program.

The value for a tmsSeriesId should begin with SH (show).

Learn more about Gracenote (TMS) IDs.

Example:
<tms:tmsSeriesId>SH12345678000</tms:tmsSeriesId>

Elements specific to Dynamic Ad Insertion

Element Child element of Requirement
<dfpvideo:ingestUrl> <item> Required *
Description

* Required for Dynamic Ad Insertion.

Node for specifying the video ingest URL to the master m3u8 file used for conditioning and playlist generation.

  • "type" attribute: should be set to application/x-mpegURL for HLS, or application/dash+xml for DASH.
  • "preconditioned" attribute: should be set to true or false to indicate if the ingestURL for this content is already conditioned for mid-roll ads, which means that your segments are already split at the time of ad breaks. This attribute defaults to false if not explicitly set.

    Content is considered conditioned if the video segments in your stream are timed precisely for cue points to insert ads. If so, there should be a #EXT-X-PLACEMENT-OPPORTUNITY marker in the HLS stream to indicate to Ad Manager that an ad break should be inserted at this point in the video content.

    Learn more about conditioned and preconditioned content for mid-roll ad insertion.


Example for HLS:
<dfpvideo:ingestUrl type="application/x-mpegURL" preconditioned="false">https://cdn.example.com/?v=123.m3u8</dfpvideo:ingestUrl>
 
Example for DASH:
<dfpvideo:ingestUrl type="application/dash+xml" preconditioned="true">
https://cdn.example.com//playlist.mpd
</dfpvideo:ingestUrl>
 
Single piece of video content can have both HLS and DASH. The use of secure (https) ingest URLs is encouraged.

back to top

Element Child element of Requirement
<dfpvideo:lastMediaModifiedDate> <item> Recommended
Description

Indicates when the video file referenced in <dfpvideo:ingestUrl> was last modified. If this value is ever updated in the feed the lastModifiedDate for the content also needs to be updated.

All timestamps must conform to RFC 822 specification or follow IS0 8601 format. If the time zone is not included in the time stamp string, it defaults to Pacific Standard Time (PST).


Examples:
<dfpvideo:lastMediaModifiedDate>2006-02-19T04:22:39+05:00</dfpvideo:lastMediaModifiedDate>
<dfpvideo:lastMediaModifiedDate>Sun, 19 Feb 2006 09:22:39
+0000</dfpvideo:lastMediaModifiedDate>
See examples of each date format

RFC 822 examples

  • Wed, 31 Oct 2016 08:00:00 EST
  • Wed, 31 Oct 2016 13:00:00 GMT
  • Wed, 31 Oct 2016 15:00:00 +0200

ISO 8601 examples

  • 20161031
  • 2016-10-31
  • 2016-10-31T08:00:00+01:00

back to top

Element Child element of Requirement
<dfpvideo:closedCaptionUrl> <item> Varies *
Description

* Required only when you have activated subtitles in the interface.

Node for specifying the URL to the closed caption/subtitle file. All available closed captions files should be provided in the feed as multiple closedCaptionUrl elements -- one caption file per language.

The formats supported are TTML/DXFP (application/ttaf+xml) and WebVTT (text/vtt).

  • "language" attribute: required (cannot be empty), and should be set to the language of the caption file. It must be compliant with RFC5646, and cannot contain the string "$$$$$". This attribute is used similar to the xml:lang attribute detailed in the XML.
  • "name" attribute: cannot contain the string "$$$$$".
  • "type" attribute: should be set to the MIME type of the caption files.
  • "characteristics" attribute: should be set to one of the following (or can be empty):**
    • "public.accessibility.transcribes-spoken-dialog"
    • "public.accessibility.describes-music-and-sound"
    • "public.easy-to-read"

** A warning is shown if "characteristics" is not set to the above, but will still work.

For a single content source, the language and name combination should be unique for each closed caption file. For example, [language="en", name="English"] and [language="en", name="English (CC)"].

 

Examples:

<dfpvideo:closedCaptionUrl language="en" name="English" type="text/vtt">http://cdn.com/subtitle.vtt</dfpvideo:closedCaptionUrl>

<dfpvideo:closedCaptionUrl language="en" name="English (CC)" characteristics="public.accessibility.describes-music-and-sound" type="text/vtt">http://cdn.com/subtitle.vtt</dfpvideo:closedCaptionUrl>

back to top

Element Child element of Requirement
<dfpvideo:fw_caid> <item> Varies *
Description

* Required only for Freewheel users.

Node for specifying Freewheel custom asset ID used for ad targeting.

  Example:
<dfpvideo:fw_caid>621160003648<dfpvideo:fw-caid>

back to top

 

For any issues related to DAI troubleshooting or outages, contact publisher support.

Was this helpful?
How can we improve it?

Need more help?

Sign in for additional support options to quickly solve your issue