Contact support
    • Monetization
    • Developer documentation
    • Supply inventory
    • Supply in-stream video inventory

    Request video ads with VMAP

    Table of Contents

    About VMAP Equativ’s VMAP implementation VMAP ad call parameters Examples Example VMAP call Example VMAP response — one VAST ad Example VMAP response — multiple VAST ads Example VMAP response — no VAST ads

    About VMAP

    Video Multiple Ad Playlist (VMAP) is an IAB specification that allows publishers to define the ad breaks to be inserted in their video content:

    • the number of ad breaks
    • the timing for each ad break
    • the number of ads per ad break
    • the types of ads per ad break

    While VMAP defines the ad breaks (pre-rolls, mid-rolls, post-rolls), the actual video ads (contained in the ad breaks) are defined based on the IAB’s “Video Ad Serving Template” (VAST) specification.

    IAB specifications:

    Equativ’s VMAP implementation

    Equativ provides the following VMAP endpoint:

    https://vmap.smartadserver.com/

    This endpoint that can be called with dedicated parameters to receive a VMAP response. Basically, the VMAP response is a list of <vmap:AdBreak> nodes. The timeOffset attribute of each <vmap:AdBreak> node specifies the position of the ad break within the content video.

    Each <vmap:AdBreak> node contains one or multiple <Wrapper> nodes which include a <VASTAdTagURI> node containing a valid video ad call. This ad call needs to be triggered by the player to obtain the actual VAST ad to be played before (pre-roll), within (mid-roll) or after (post-roll) the video content.  

    VMAP ad call parameters 

    The VMAP endpoint https://vmap.smartadserver.com/ supports the following parameters:

    Parameter name Necessity Description
    acparams mandatory

    a URL encoded string of all the ad call parameters; these will be passed in the <VASTAdTagURI> to build a valid video ad call.

     

    Mandatory parameters:

    • siteid — website
    • pgid  — page
    • fmtid  — format

    About other parameters:

    • out —  if it is missing, out=vast is used as a fallback
    • ab — is replaced by a calculated value based on the parsed cue points
    • oc — is replaced by a hardcoded value of 1

    For the full list of parameters, see GET Ad API integration.
    ctd optional the content duration — not used, currently; the value -1 indicates a live stream
    cuepoints mandatory

    a comma separated list of cue points in random order — there is no need to pass them in chronological order;  Each cue point can have the following values:

    • for pre-rolls: start
    • for post-rolls: end
    • for mid-rolls*:    
      • a timestamp (in milliseconds) of the video content; example:  1500000,6050000
      • a percentage of the content video duration with suffix “%”; example: 15%,55%
      • a position number with prefix “#”; example: #3,#7; the prefix must be encoded — e.g. #2 =>  %232

    * Keep in mind:

    • Make sure you use a format (timestamp, percentage, position number) the player supports. 
    • In a VMAP ad call, multiple mid-roll cue points must all have the same format: either timestamps or percentages or position numbers; mixing the formats of mid-roll cue points is not possible!

     

    Examples

    Example VMAP call

    The example below calls a VMAP with the cue points start,1000000,end.

    /vmap?cuepoints=start,1000000,end&acparams=siteid%3D1000245744%26pgid%3D1000137181%26fmtid%3D1000008263%26tgt%3D%26out%3Dvast2%26ps%3D1%26pb%3D0%26visit%3DS%26vcn%3Ds%26tmstp%3D83383938

    Note that the value 1000000 is in milliseconds.

    Example VMAP response — one VAST ad

    The VMAP response below contains one VAST ad targeting the pre-roll ad break ("start"). 

    The timeOffset attribute of the <vmap:AdBreak> node is the equivalent of the cue points passed in the VMAP call.

     <?xml version="1.0" encoding="UTF-8"?>
<vmap:VMAP version="1.0" xmlns:vmap="http://www.iab.net/videosuite/vmap">
    <vmap:AdBreak breakId="aebd9ef3-b20d-41e2-9cc3-062dd700085d" breakType="linear" timeOffset="start">
        <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="-1622020171">
            <vmap:VASTAdData>
                <VAST version="3.0" xmlns="http://www.iab.net/videosuite/vast">
                    <Ad id="aebd9ef3-b20d-41e2-9cc3-062dd700085d" sequence="1">
                        <Wrapper>
                            <AdSystem>SMART AdServer</AdSystem>
                            <VASTAdTagURI><![CDATA[https://videodiff-dev.internal.smartadserver.com/ac?siteid=1000245744&pgid=1000137181&fmtid=1000008263&ab=1&oc=1&out=vast2&ctd=&tgt=&ps=1&pb=0&visit=S&vcn=s&vph=&vpw=&vpmt=&tmstp=83383938]]></VASTAdTagURI>
                            <Error><![CDATA[https://videodiff-dev.internal.smartadserver.com/track/action?ec=[ERRORCODE]&key=videoerror&opid=aebd9ef3-b20d-41e2-9cc3-062dd700085d&opdt=1637849444&pid=1000137181&fmtid=1000008263&imptype=1&ab=1]]></Error>
                            <Impression><![CDATA[https://videodiff-dev.internal.smartadserver.com/track/action?key=vmapimpression&opid=aebd9ef3-b20d-41e2-9cc3-062dd700085d&opdt=1637849444&pid=1000137181&fmtid=1000008263&imptype=1&ab=1]]></Impression>
                            <Creatives/>
                        </Wrapper>
                    </Ad>
                </VAST>
            </vmap:VASTAdData>
        </vmap:AdSource>
    </vmap:AdBreak>
</vmap:VMAP>

     

    Example VMAP response — multiple VAST ads

    The VMAP response below contains three VAST ads targeting the following ad breaks:

    • Pre-roll ad break ("start") 
    • Mid-roll ad break after 1000 seconds ("00:16:40.000")
    • Post-roll ad break ("end")

    The timeOffset attribute of each <vmap:AdBreak> node is the equivalent of the cue points passed in the VMAP call. 

    <?xml version="1.0" encoding="UTF-8"?>
<vmap:VMAP version="1.0" xmlns:vmap="http://www.iab.net/videosuite/vmap" >
    <vmap:AdBreak breakId="8661748b-b25a-4569-b03e-9dd33a43b28c" breakType="linear" timeOffset="start">
        <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="-1675117733">
            <vmap:VASTAdData>
                <VAST version="3.0" xmlns="http://www.iab.net/videosuite/vast">
                    <Ad id="8661748b-b25a-4569-b03e-9dd33a43b28c" sequence="1">
                        <Wrapper>
                            <AdSystem>SMART AdServer</AdSystem>
                            <VASTAdTagURI><![CDATA[https://videodiff-dev.internal.smartadserver.com/ac?siteid=1000245744&pgid=1000137181&fmtid=1000008263&ab=1&oc=1&out=vast2&ctd=&tgt=&ps=1&pb=0&visit=S&vcn=s&vph=&vpw=&vpmt=&tmstp=83383938]]></VASTAdTagURI>
                            <Error><![CDATA[https://videodiff-dev.internal.smartadserver.com/track/action?ec=[ERRORCODE]&key=videoerror&opid=8661748b-b25a-4569-b03e-9dd33a43b28c&opdt=1637849557&pid=1000137181&fmtid=1000008263&imptype=1&ab=1]]></Error>
                            <Impression><![CDATA[https://videodiff-dev.internal.smartadserver.com/track/action?key=vmapimpression&opid=8661748b-b25a-4569-b03e-9dd33a43b28c&opdt=1637849557&pid=1000137181&fmtid=1000008263&imptype=1&ab=1]]></Impression>
                            <Creatives/>
                        </Wrapper>
                    </Ad>
                </VAST>
            </vmap:VASTAdData>
        </vmap:AdSource>
    </vmap:AdBreak>
    <vmap:AdBreak breakId="67d32666-1613-4a8d-b7f9-34a8064770b3" breakType="linear" timeOffset="00:16:40.000">
        <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="907710148">
            <vmap:VASTAdData>
                <VAST version="3.0" xmlns="http://www.iab.net/videosuite/vast">
                    <Ad id="67d32666-1613-4a8d-b7f9-34a8064770b3" sequence="1">
                        <Wrapper>
                            <AdSystem>SMART AdServer</AdSystem>
                            <VASTAdTagURI><![CDATA[https://videodiff-dev.internal.smartadserver.com/ac?siteid=1000245744&pgid=1000137181&fmtid=1000008263&ab=2&oc=1&out=vast2&ctd=&tgt=&ps=1&pb=0&visit=S&vcn=s&vph=&vpw=&vpmt=&tmstp=83383938]]></VASTAdTagURI>
                            <Error><![CDATA[https://videodiff-dev.internal.smartadserver.com/track/action?ec=[ERRORCODE]&key=videoerror&opid=67d32666-1613-4a8d-b7f9-34a8064770b3&opdt=1637849557&pid=1000137181&fmtid=1000008263&imptype=1&ab=2]]></Error>
                            <Impression><![CDATA[https://videodiff-dev.internal.smartadserver.com/track/action?key=vmapimpression&opid=67d32666-1613-4a8d-b7f9-34a8064770b3&opdt=1637849557&pid=1000137181&fmtid=1000008263&imptype=1&ab=2]]></Impression>
                            <Creatives/>
                        </Wrapper>
                    </Ad>
                </VAST>
            </vmap:VASTAdData>
        </vmap:AdSource>
    </vmap:AdBreak>
    <vmap:AdBreak breakId="485e36e3-50ed-4723-bf3a-826aa6d6e52f" breakType="linear" timeOffset="end">
        <vmap:AdSource allowMultipleAds="true" followRedirects="true" id="1243253271">
            <vmap:VASTAdData>
                <VAST version="3.0" xmlns="http://www.iab.net/videosuite/vast">
                    <Ad id="485e36e3-50ed-4723-bf3a-826aa6d6e52f" sequence="1" xmlns="http://www.iab.net/videosuite/vast">
                        <Wrapper>
                            <AdSystem>SMART AdServer</AdSystem>
                            <VASTAdTagURI><![CDATA[https://videodiff-dev.internal.smartadserver.com/ac?siteid=1000245744&pgid=1000137181&fmtid=1000008263&ab=3&oc=1&out=vast2&ctd=&tgt=&ps=1&pb=0&visit=S&vcn=s&vph=&vpw=&vpmt=&tmstp=83383938]]></VASTAdTagURI>
                            <Error><![CDATA[https://videodiff-dev.internal.smartadserver.com/track/action?ec=[ERRORCODE]&key=videoerror&opid=485e36e3-50ed-4723-bf3a-826aa6d6e52f&opdt=1637849557&pid=1000137181&fmtid=1000008263&imptype=1&ab=3]]></Error>
                            <Impression><![CDATA[https://videodiff-dev.internal.smartadserver.com/track/action?key=vmapimpression&opid=485e36e3-50ed-4723-bf3a-826aa6d6e52f&opdt=1637849557&pid=1000137181&fmtid=1000008263&imptype=1&ab=3]]></Impression>
                            <Creatives/>
                        </Wrapper>
                    </Ad>
                </VAST>
            </vmap:VASTAdData>
        </vmap:AdSource>
    </vmap:AdBreak>
</vmap:VMAP>

     

    Example VMAP response — no VAST ads

    The example below shows the response in case no VAST ad was found for delivery— e. g. because there is no insertion that matches with the parameters or because there is no online insertion ready to be delivered etc. 

    <vmap:VMAP xmlns:vmap="http://www.iab.net/videosuite/vmap" version="1.0">  </vmap:VMAP>

     

    RELATED ARTICLES