VMAP Integration

How to integrate Ooyala Pulse ad delivery with your video player by creating direct VMAP requests.

Supported features and protocols

In Ooyala Pulse, the VMAP template is enabled for:
  • standard pre-rolls,
  • standard mid-rolls,
  • standard post-rolls,
  • and overlays.

These are the ad formats you can request in a VMAP integration.

The supported VMAP protocol is 1.0.

Limitations

Ad selection logic for VMAP requests filters out goals containing unsupported ad formats, like pause ads, even if the goal contains and ad that matches the request's criteria.

VMAP Ad Request

Note: When you use the sell-side platform (SSP) in Pulse and make requests from a native Android or iOS application, then it is mandatory to pass in the Mobile App Parameters
A request for a VMAP ticket follows the format of URL?parameter_name=value&parameter_name=value&..., where:
  • URL: http://[subdomain].videoplaza.tv/proxy/distributor/v2, where [subdomain] is the sub domain of your Ooyala Pulse account and can be found under Account Settings>Integration Information of the Settings tab.
    Note: The host URL may use the https protocol, but only in case HTTPS is enabled on your account. Verify with your Account Manager that this is the case before doing so.
  • parameter_name=value: a list of the parameter and value pairs, separated from each other with ampersands (&), defining the characteristics and filters for the ads in the VMAP ticket. For a list of all possible parameters, their descriptions and possible values, see VAST and VMAP Parameters

Example Request

The following URL requests a VMAP ticket containing prerolls which can be served for the standard-linears tag:
http://pulse-demo.videoplaza.tv/proxy/distributor/v2?tt=p&rt=vmap_1.0&t=standard-linears

VMAP response ticket

Sample of a VMAP response:

<vmap:VMAP xmlns:vmap="http://www.iab.net/videosuite/vmap" version="1.0">
  <vmap:AdBreak timeOffset="start" breakType="linear" breakId="dd9fe732-54c6-4aa1-a3bc-766134e8cf30">
    <vmap:AdSource allowMultipleAds="true">
      <vmap:VASTAdData>
        <VAST version="3.0">
          <Ad id="41039f00-6127-418b-a22a-0d31c46f92a5" sequence="1">
            <InLine>
              <AdSystem>Videoplaza Karbon</AdSystem>
              <AdTitle>Preroll green</AdTitle>
              <Error>
                <![CDATA[
                http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=0&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=0&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p&ua=%5Bua%5D&uc=%5Buc%5D
                ]]>
              </Error>
              <Impression>
                <![CDATA[
                http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=41039f00-6127-418b-a22a-0d31c46f92a5&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=0&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p&ua=%5Bua%5D&uc=%5Buc%5D
                ]]>
              </Impression>
              <Creatives>
                <Creative id="video">
                  <Linear>
                    <Duration>00:00:08</Duration>
                    <TrackingEvents>
                      <Tracking event="start">
                        <![CDATA[
                        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=41039f00-6127-418b-a22a-0d31c46f92a5&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=14&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p
                        ]]>
                      </Tracking>
                      <Tracking event="midpoint">
                        <![CDATA[
                        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=41039f00-6127-418b-a22a-0d31c46f92a5&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=16&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p
                        ]]>
                      </Tracking>
                      <Tracking event="complete">
                        <![CDATA[
                        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=41039f00-6127-418b-a22a-0d31c46f92a5&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=18&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p
                        ]]>
                      </Tracking>
                    </TrackingEvents>
                    <VideoClicks>
                      <ClickThrough>
                        <![CDATA[
                        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=41039f00-6127-418b-a22a-0d31c46f92a5&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=20&pid=3f2ede67-8e9f-4530-86fb-02888906b688&redirect=https%3A%2F%2Fwww.google.se%2Fsearch%3Fq%3Dgreen%2Bcolor&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p
                        ]]>
                      </ClickThrough>
                    </VideoClicks>
                    <MediaFiles>
                      <MediaFile delivery="progressive" type="video/mp4" bitrate="712" width="512" height="288" scalable="true">
                        <![CDATA[
                        http://vp.videoplaza.tv/creatives/assets/7aae2109-7f76-46da-9a79-47a3b1148738/2a62adb5-4217-4ceb-824f-e3670c0f9647.mp4
                        ]]>
                      </MediaFile>
                      <MediaFile delivery="progressive" type="video/mp4" bitrate="405" width="512" height="288" scalable="true">
                        <![CDATA[
                        http://vp.videoplaza.tv/creatives/assets/7aae2109-7f76-46da-9a79-47a3b1148738/26bfa1aa-f42a-4dae-8312-707dade19119.mp4
                        ]]>
                      </MediaFile>
                    </MediaFiles>
                  </Linear>
                </Creative>
              </Creatives>
              <Extensions>
                <Extension xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="VPAdServerExtension_type" type="AdServer" name="Videoplaza">
                  <AdInfo showSkipButton="never" lastImpression="0" skipReset="24:00:00.0" requestType="lazy" gid="6ef2e3d8-f4f1-4a90-870b-89d2b07cd341" cid="bf1a76a8-c28d-47f6-9d55-199250f1a3e3" format="spot_standard" variant="NORMAL" exclusive="false" report="http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=41039f00-6127-418b-a22a-0d31c46f92a5&e=500&pbi=%5BPASSBACK_INDEX%5D&pec=%5BPULSE_ERROR%5D&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3"/>
                </Extension>
              </Extensions>
            </InLine>
          </Ad>
          <Ad id="15f77699-5ebe-4e25-a0a4-8bb2e06fdb6f" sequence="2">
            <InLine>
              <AdSystem>Videoplaza Karbon</AdSystem>
              <AdTitle>Preroll blue</AdTitle>
              <Error>
                <![CDATA[
                http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=0&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=0&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p&ua=%5Bua%5D&uc=%5Buc%5D
                ]]>
              </Error>
              <Impression>
                <![CDATA[
                http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=15f77699-5ebe-4e25-a0a4-8bb2e06fdb6f&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=0&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p&ua=%5Bua%5D&uc=%5Buc%5D
                ]]>
              </Impression>
              <Creatives>
                <Creative id="video">
                  <Linear>
                    <Duration>00:00:08</Duration>
                    <TrackingEvents>
                      <Tracking event="start">
                        <![CDATA[
                        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=15f77699-5ebe-4e25-a0a4-8bb2e06fdb6f&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=14&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p
                        ]]>
                      </Tracking>
                      <Tracking event="midpoint">
                        <![CDATA[
                        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=15f77699-5ebe-4e25-a0a4-8bb2e06fdb6f&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=16&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p
                        ]]>
                      </Tracking>
                      <Tracking event="complete">
                        <![CDATA[
                        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=15f77699-5ebe-4e25-a0a4-8bb2e06fdb6f&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=18&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p
                        ]]>
                      </Tracking>
                    </TrackingEvents>
                    <VideoClicks>
                      <ClickThrough>
                        <![CDATA[
                        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=15f77699-5ebe-4e25-a0a4-8bb2e06fdb6f&cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=20&pid=3f2ede67-8e9f-4530-86fb-02888906b688&redirect=https%3A%2F%2Fwww.google.se%2Fsearch%3Fq%3Dblue%2Bcolor&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3&tt=p
                        ]]>
                      </ClickThrough>
                    </VideoClicks>
                    <MediaFiles>
                      <MediaFile delivery="progressive" type="video/mp4" bitrate="711" width="512" height="288" scalable="true">
                        <![CDATA[
                        http://vp.videoplaza.tv/creatives/assets/9cd142a8-35ad-4ebc-8884-2051b609b8e4/5433d830-6ff4-4120-a59f-db788fd3427f.mp4
                        ]]>
                      </MediaFile>
                      <MediaFile delivery="progressive" type="video/mp4" bitrate="401" width="512" height="288" scalable="true">
                        <![CDATA[
                        http://vp.videoplaza.tv/creatives/assets/9cd142a8-35ad-4ebc-8884-2051b609b8e4/f8c1c869-17b1-444a-a156-f4abd35a8c11.mp4
                        ]]>
                      </MediaFile>
                    </MediaFiles>
                  </Linear>
                </Creative>
              </Creatives>
              <Extensions>
                <Extension xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="VPAdServerExtension_type" type="AdServer" name="Videoplaza">
                  <AdInfo showSkipButton="never" lastImpression="0" skipReset="24:00:00.0" requestType="lazy" gid="f0d53d94-f530-4d16-b519-9e2e9a6ffcd0" cid="bf1a76a8-c28d-47f6-9d55-199250f1a3e3" format="spot_standard" variant="NORMAL" exclusive="false" report="http://pulse-demo.videoplaza.tv/proxy/tracker/v2?aid=15f77699-5ebe-4e25-a0a4-8bb2e06fdb6f&e=500&pbi=%5BPASSBACK_INDEX%5D&pec=%5BPULSE_ERROR%5D&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3"/>
                </Extension>
              </Extensions>
            </InLine>
          </Ad>
        </VAST>
      </vmap:VASTAdData>
    </vmap:AdSource>
    <vmap:TrackingEvents>
      <vmap:Tracking event="breakStart">
        http://pulse-demo.videoplaza.tv/proxy/tracker/v2?cf=short_form&dcid=d25462f4-ea19-4eaf-99b9-85de3f29d059&e=21&pid=3f2ede67-8e9f-4530-86fb-02888906b688&rnd=%5BCACHEBUSTING%5D&t=standard-linears&tid=bc384b7f-bc9a-11e6-bb24-002590e33bd3
      </vmap:Tracking>
    </vmap:TrackingEvents>
  </vmap:AdBreak>
</vmap:VMAP>

VMAP Tracking

Apart from the events you need to track for the VAST tickets embedded in the VMAP ticket, there are two other events to track specifically for the VMAP tickets:
  • breakStart: track the start of an ad break, even when there are no ads available.
  • breakEnd: if present, track at the end of an ad break, which may be straight after the tracking of the start when no ads are available. breakEnd is used to track inventory for unfilled positions in ad breaks in VMAP tickets.
Note: When an ad cannot be played, for example, because of a broken third party URL, then you must track inventory through the tracking URL in the <Error> element of the relevant ad in the VAST ticket.

To clarify these two tracking events, consider the following cases:

  1. All positions in the ad break are filled

    In this case, you only have to track the start of the ad break using the URL in the breakStart tracking event. The ads are available in an embedded VAST ticket, and any errors on the ads should be tracked through the VAST ticket's error trackers.

    Example ticket:

    <vmap:AdBreak timeOffset=“start” breakType=“linear” breakId=“0b0c735c-4110-d0a6-60d9-4711caaec7c8”>
      <vmap:AdSource allowMultipleAds=“true”>
        <vmap:VASTAdData>
          <VAST version=“3.0”>
          ...
          </VAST>
        </vmap:VASTAdData>
      </vmap:AdSource>
      <vmap:TrackingEvents>
        <vmap:Tracking event=“breakStart”>
    http://unittest.videoplaza.org/proxy/tracker/v2?cf=short_form&amp;e=21&amp;pid=690854f0-dc77-9425-14b6-08c8f3c71568&amp;rnd=%5BCACHEBUSTING%5D&amp;tid=e7e88ed1-b7d4-75c6-6670-56f468bb2974
        </vmap:Tracking>
      </vmap:TrackingEvents>
    </vmap:AdBreak>
  2. None of the positions in the ad break are filled

    In this case, the VMAP ticket only contains tracking events with a number of breakEnd event. When the ad break is supposed to start, you have to track the breakStart event first. Now, because there are no ads available, you immediately start tracking each available breakEnd event.

    Example ticket:

    <vmap:AdBreak breakId="598f7c61-0915-6979-5a5e-be4185e333bb-air" breakType="linear" timeOffset="end">
      <vmap:TrackingEvents>
        <vmap:Tracking event="breakStart">http://unittest.videoplaza.org/proxy/tracker/v2?cf=short_form&amp;e=21&amp;pid=690854f0-dc77-9425-14b6-08c8f3c71568&amp;rnd=%5BCACHEBUSTING%5D&amp;tid=e7e88ed1-b7d4-75c6-6670-56f468bb2974</vmap:Tracking>
        <vmap:Tracking event="breakEnd">http://unittest.videoplaza.org/proxy/tracker/v2?aid=0&amp;cf=short_form&amp;e=0&amp;pid=690854f0-dc77-9425-14b6-08c8f3c71568&amp;rnd=%5BCACHEBUSTING%5D&amp;tid=e7e88ed1-b7d4-75c6-6670-56f468bb2974&amp;tt=po&amp;ua=%5Bua%5D&amp;uc=%5Buc%5D</vmap:Tracking>
        <vmap:Tracking event="breakEnd">http://unittest.videoplaza.org/proxy/tracker/v2?aid=0&amp;cf=short_form&amp;e=0&amp;pid=690854f0-dc77-9425-14b6-08c8f3c71568&amp;rnd=%5BCACHEBUSTING%5D&amp;tid=e7e88ed1-b7d4-75c6-6670-56f468bb2974&amp;tt=po&amp;ua=%5Bua%5D&amp;uc=%5Buc%5D</vmap:Tracking>  </vmap:TrackingEvents>
    </vmap:AdBreak>
  3. Some of the positions in the ad break are filled

    In this case, some ads are available in an embedded VAST ticket, and the VMAP tracking contains at least one breakEnd event tracker. As usual, you start with tracking the breakStart event when the ad break starts, then you play all ads and track the appropriate events according to the VAST ticket. When there are no more ads to show, you track each available breakEnd event.

    Example ticket:

    <vmap:AdBreak breakId="0b0c735c-4110-d0a6-60d9-4711caaec7c8" breakType="linear" timeOffset="start">
      <vmap:AdSource allowMultipleAds="true">
        <vmap:VASTAdData>
          <VAST version="3.0">
            <Ad id="69dca780-808a-7613-47ec-4b8ee45f4db5" sequence="1">
              ...
              ...
            </Ad>
          </VAST>
        </vmap:VASTAdData>
      </vmap:AdSource>
      <vmap:TrackingEvents>
        <vmap:Tracking event="breakEnd">http://unittest.videoplaza.org/proxy/tracker/v2?aid=0&amp;cf=short_form&amp;e=0&amp;pid=690854f0-dc77-9425-14b6-08c8f3c71568&amp;rnd=%5BCACHEBUSTING%5D&amp;tid=e7e88ed1-b7d4-75c6-6670-56f468bb2974&amp;tt=p&amp;ua=%5Bua%5D&amp;uc=%5Buc%5D</vmap:Tracking>
        <vmap:Tracking event="breakStart">http://unittest.videoplaza.org/proxy/tracker/v2?cf=short_form&amp;e=21&amp;pid=690854f0-dc77-9425-14b6-08c8f3c71568&amp;rnd=%5BCACHEBUSTING%5D&amp;tid=e7e88ed1-b7d4-75c6-6670-56f468bb2974</vmap:Tracking>
      </vmap:TrackingEvents>
    </vmap:AdBreak>

Was this article helpful?