Retrieve VAST URLs

VAST URLs for video ad blocks can be retrieved by the command getVideoBlock:

  function callback(error, result) {}
somtag.cmd('getVideoBlock', <block>, <customValues>, callback {
  // ...
});
ParameterDescription
blockDefines the position of the ad block in the video. Allowed values are listed in (Video Ad Blocks)
Values must be aligned with the corresponding section configObject.video.blocks of the config object.
customValuesUsually an empty object ({}). Can be used to implement special requirements, compatible with SOM adtech
callback(error, result)You must pass a callback function.
Somtag will call your callback function and provide the ad urls in the result parameter. It contains an array of ad URLs, leading to VAST XML files, that have to be called, parsed and played in the order of their position in the array

The order of the single getVideoBlock calls has to reflect the order of the ad playout, to allow for features like frequency capping etc.

As the validity of some ad URLs is limited in time, the video ad block has to be retrieved directly before it is going to be played.

Example for a preroll block:

somtag.cmd("getVideoBlock", "pre", {}, function (error, result) {
    console.log(result);
    // array of ad URLs:
    [
        "https://ad71.adfarm1.adition.com/lt?...",
        "https://ad71.adfarm1.adition.com/lt?...",
        "https://ad71.adfarm1.adition.com/lt?..."
    ];
});

Video Ad Blocks

BlockNameDescription
Prerollpread block running before the content
Midrollmidad blocks intermitting the content, several blocks possible
Postrollpostad block running after the content

Somtag + Somquery

For the following features somtag delegates adserver requests to somquery. It therefore has to pass compliant information in the request which unfortunately may need the information first hand from the client (you) using somtag. For more information about what Somquery does https://docs.seven.one/docs

Live Video Feeds

For duration based live video feeds somtag requires an adBreakId and adBreakDuration to be requested alongside a mid block:

ParamDescription
adBreakIdIs an identifier to match the ad break to the backend systems of the playout center (only for P7S1 channels / signals possible)
adBreakDurationdefines the length of the adbreak / advertising block. based on this duration the advertising block is generated with a suitable number or length of advertising mediafiles
maxNonSponsorCountenables the reduction of possible advertising slots in an advertising block. The maximum number of slots is defined on the server side; the default setting can be reduced using this parameter. The sponsor slots are excluded here. These are always added
 
    somtag.cmd(
      'getVideoBlock',
      'mid', {
        adBreakId: 2134,
        adBreakDuration: 1337
      },
      callback
    );

Special Use Case: Disable normal ads but keep sponsors

    somtag.cmd(
      'getVideoBlock',
      'mid', {
        maxNonSponsorCount: 0
      },
      callback
    );

Get structural/contextual Information about an AdUrl

Somtag may provide differently shaped URLs per getVideoBlock request. In case you have a highly abstract system that does not know/cares about where the AdUrls Came from or how they were retrieved in the first place - we may be able to support you with this little API:

const adUrlConfig = await somtag.cmd('getAdUrlConfig', adUrl);

and adUrlConfig will look like this:

{
    "blockName": "pre",
    "slotName": "preroll",
    "video": {
        "verticalPosition": 1,
        "position": 1,
        "videoType": 1,
        "longplay": false,
        "maxVastVersion": "4_1"
    },
    "videoBlock": {
        "blockName": "pre",
        "enabledSlots": {
            "preroll": {
                "count": 1,
                "custom": [
                    {
                        "key": "isAdBlock",
                        "value": false
                    },
                    {
                        "key": "isInFullscreen",
                        "value": false
                    }
                ],
                "enabled": true,
                "yieldProbeStrategy": "single"
            }
        },
        "blockConfiguration": {
            "enabled": true,
            "slots": {
                "preroll": {
                    "count": 1,
                    "custom": [],
                    "enabled": true,
                    "yieldProbeStrategy": "single"
                },
                "sponsor": {
                    "count": 0,
                    "custom": [],
                    "enabled": true,
                    "yieldProbeStrategy": "single"
                },
                "cutin": {
                    "count": 0,
                    "custom": [],
                    "enabled": true,
                    "yieldProbeStrategy": "single"
                }
            }
        },
        "customConfiguration": {
            "custom": [
                {
                    "key": "isAdBlock",
                    "value": false
                },
                {
                    "key": "isInFullscreen",
                    "value": false
                }
            ]
        }
    },
    "mime": "text/xml",
    "taxonomy": {
        "channels": [
            "LIFESTYLE,WISSEN",
            "taff",
            "prosieben",
            "ProSieben"
        ],
        "content": "content",
        "topics": [],
        "units": [
            "DE_PRO7",
            "other"
        ],
        "inventory": {
            "units": [],
            "site": "prosieben",
            "brand": "ProSieben",
            "categories": [
                "LIFESTYLE,WISSEN"
            ],
            "format": "taff",
            "device": "",
            "country": ""
        },
        "aditionAt": {}
    },
    "passedCustomKeyValues": {
        "isAdBlock": false,
        "isInFullscreen": false,
        "xx": [
            "vp",
            "iad",
            "wrap"
        ]
    },
    "custom": {
        "0": "8",
        "1": "5",
        "2": "d",
        "3": "e",
        "4": "2",
        "5": "b",
        "6": "1",
        "7": "4",
        "8": "-",
        "9": "3",
        "10": "5",
        "11": "6",
        "12": "2",
        "13": "-",
        "14": "4",
        "15": "d",
        "16": "a",
        "17": "1",
        "18": "-",
        "19": "9",
        "20": "e",
        "21": "b",
        "22": "3",
        "23": "-",
        "24": "6",
        "25": "9",
        "26": "8",
        "27": "7",
        "28": "6",
        "29": "d",
        "30": "e",
        "31": "8",
        "32": "d",
        "33": "9",
        "34": "c",
        "35": "0",
        "consentData": "CPxUUEAPxUUEAE-ABBDEDUCsAP_AAAPAAAYgJAJR8D5dTWlCMX5_QPtEOIUX18ATAmAABgSAA2ABABGA4AwGw2AwJESgBCACEAIAolYBAAIEHAEUAEAAQAABAAFgAgAEBAAIIABEAAEAAAIIAAoKAIAAAACIgEAxEACAkAiYANKsQEAg1IAAAgAAIAAAAAABAgMABAAIABIAAQAAgQAAAAAAEAAAAAEAAQgAAAQSAABIFSYgAKAAJCaAMIIEQIgLAAiAEAAAAkABAAAACABwBgEoMBgAIEAAAAAAAABRAACAAAQAAAIAIAAgAAAAAAAAAAAAAAQAACAAAAAgAAAABAQAQAAAAEAAAAAAAABABCgACAEgIAAoAAABAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgChoAMAAQSAEQAYAAgkAKgAwABBIAZABgACCQASADAAEEgA.YAAAAAAAAAAA",
        "decodedConsentData": { },
        "version": 2,
        "isAdBlock": false,
        "isInFullscreen": false,
        "xx": [
            "vp",
            "iad",
            "wrap"
        ],
        "site": "prosieben",
        "brand": "prosieben",
        "mId": "",
        "categories": [
            "lifestyle,wissen"
        ],
        "format": "taff",
        "device": "desktop",
        "slot": "preroll"
    },
    "adLog": "tcf_2,c_7467794833,int_1",
    "genericKeyValues": {
        "rogator": {},
        "theAdex": {},
        "brandMetrics": {},
        "consentMgt": {
            "targeting": {
                "consentData": "CPxUUEAPxUUEAE-ABBDEDUCsAP_AAAPAAAYgJAJR8D5dTWlCMX5_QPtEOIUX18ATAmAABgSAA2ABABGA4AwGw2AwJESgBCACEAIAolYBAAIEHAEUAEAAQAABAAFgAgAEBAAIIABEAAEAAAIIAAoKAIAAAACIgEAxEACAkAiYANKsQEAg1IAAAgAAIAAAAAABAgMABAAIABIAAQAAgQAAAAAAEAAAAAEAAQgAAAQSAABIFSYgAKAAJCaAMIIEQIgLAAiAEAAAAkABAAAACABwBgEoMBgAIEAAAAAAAABRAACAAAQAAAIAIAAgAAAAAAAAAAAAAAQAACAAAAAgAAAABAQAQAAAAEAAAAAAAABABCgACAEgIAAoAAABAAAAAAAAAAAAAAAAAAQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAgChoAMAAQSAEQAYAAgkAKgAwABBIAZABgACCQASADAAEEgA.YAAAAAAAAAAA",
                "decodedConsentData": { ... },
                "version": 2
            },
            "targetingLog": {
                "tcf": 2
            },
            "isInitialized": true,
            "error": null,
            "other": {
                "url": ""
            }
        },
        "inventory": {
            "site": "prosieben",
            "brand": "prosieben",
            "mId": "",
            "categories": [
                "lifestyle,wissen"
            ],
            "format": "taff",
            "device": "desktop"
        },
        "topics": []
    },
    "exclusion": [],
    "uuId": "6c6a8df9-2694-4559-a755-90c63f9677a6",
    "network": "5731",
    "session": 7467794833,
    "size": [],
    "tile": 1,
    "syndication": {
        "content": "v_b0kzxm5y80o6"
    },
    "delayedImpression": true,
    "id": "pro7_supernova",
    "identifier": "pro7",
    "integrationId": "e5a7fce2-0370-4e0b-b9e8-d419d20fd8bf",
    "keywords": [],
    "ssl": {
        "ssl": true
    },
    "advertiser": "SOM_DE",
    "usePpid": {
        "enabled": false
    },
    "consent": {
        "targeting": true,
        "bidding": true,
        "tracking": true,
        "partialConsent": false,
        "hasFullConsentFromCustomP7CMP": true
    },
    "schain": "",
    "sessionGuid": "abe8c915-2076-494c-8674-a14b0458b939"
}
← Ad Slot and Ad Product OverviewVideo Example →