InStream (Video Ad) Integration

The SevenOne Media in-stream (video) ads are delivered via the Adition ad server. To load video ads in native apps, a VAST compatible video player or an VAST SDK must be integrated. The player (or SDK) must be fully compatible with IAB´s VAST 2.0 specification and must support impression, click, view-time tracking of Inline and Wrapper VAST XMLs.

Parameters

Before calling a video ad, the following placeholders need to be replaced properly in the somquery inapp tag.

Preroll iOS example:

https://somquery.sqrt-5041.de/mobile/ads/app_sc/precontent?mId=%MandatorID%&country=%COUNTRY%&pods=1&os=[ios/android]&device=[phone/tablet]&dc=nativeapp&mac=%MAC%&pos=1&tile=1&format=%FORMAT%&category=%CATEGORY%&brand=%BRAND%&aId=%VIDEONAME_VIDEOID%&gdpr_consent=%GDPR_CONSENT%&uncertified_vendors=%UNCERTIFIED_VENDORS%&idfa=%IDFA%&idfv=%IDFV%&ppid=%PPID%&c=%RANDOM%&%IAB_CONTENT%

Placeholder: %MandatorID%

The mandator id is an unique id provided by SOM.

Placeholder: %COUNTRY%

Needs to be replaced with a two digit char for the country. Possible values are 'de' for germany, 'at' for austria and 'ch' for switzerland.

Placeholder: %RANDOM%

At each ad-request a min. 8 chars long cachebuster (UNIX timestamp or random number) has to be set at the end of the ad-tag. If there are more than one video-ad formats per content video, the same cache-buster must be set at the end of each ad-tag. For example, the preroll-request and postroll-request must have the same cache-buster value (per playback session).

Placeholder: %IDFA%,%PPID%,%IDFV%,%GDPR_CONSENT%,%UNCERTIFIED_VENDORS%

More information regarding these parameters can be found on Provide user consent.

OpenRTB Content Object

Placeholder: %IAB_CONTENT%: Meta Data about the video content (optional)

With the help of %IAB_CONTENT% you pass meta data about the video content. This data is used for adserver targeting, programmatic distribution as well as the configuration of the amount of video ads, based on the len attribute. All attributes are optional. More information can be found in the official IAB documentation on openRTB API Specification 2.6.

The following table gives an overview on what attributes are supported by us:

AttributeTypeDescriptionFurther Information
idstringID uniquely identifying the content.used for programmatic distribution
episodeintegerEpisode number.used for programmatic distribution
titlestringContent title.

Video Examples: “Search Committee” (television), “A New Hope” (movie), or “Endgame” (made for web).

Non-Video Example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article).		used for programmatic distribution
seriesstringContent series.

Video Examples: “The Office” (television), “Star Wars” (movie),or “Arby ‘N’ The Chief” (made for web).

Non-Video Example: “Ecocentric” (Time Magazine blog).		used for programmatic distribution
seasonstringContent season (e.g., “Season 3”).used for programmatic distribution
artiststringArtist credited with the content.used for programmatic distribution
genrestringGenre that best describes the content (e.g., rock, pop, etc). Please see Supported Genreused for programmatic distribution
isrcstringInternational Standard Recording Code conforming to ISO3901.used for programmatic distribution
urlstringURL of the content, for buy-side contextualization or review.used for programmatic distribution
catstring arrayArray of IAB content categories that describe the content.

The values are defined by IAB Content Taxonomy. Please see IAB Categories for more details.

Example: &iab_content[cat]=1&iab_content[cat]=59		used for programmatic distribution
prodqintegerProduction quality. These values are defined by the IAB, refer to www.iab.com/wp-content/uploads/2015/03/long-form-video-final.pdf for more information.
Value Description
0 Unknown
1 Professionally Produced
2 Prosumer
3 User Generated (UGC)
used for programmatic distribution
contextintegerType of content (game, video, text, etc.).
Value Description
1 Video (i.e., video file or stream such as Internet TV broadcasts)
2 Game (i.e., an interactive software game)
3 Music (i.e., audio file or stream such as Internet radio broadcasts)
4 Application (i.e., an interactive software application)
5 Text (i.e., primarily textual document such as a web page, eBook, or news article)
6 Other (i.e., none of the other categories applies)
7 Unknown
used for programmatic distribution
contentratingstringContent rating
Value Description
FSK 0 no age restriction
FSK 6 age 6 or older
FSK 12 age 12 or older
FSK 16 age 16 or older
FSK 18 age 18 or older
keywordsstringComma separated list of keywords describing the content.used for programmatic distribution
livestreaminteger0 = not live,
1 = content is live (e.g., stream, live blog).		used for programmatic distribution
sourcerelationshipintegerSpecifies the relationship to the source, where:
0 = indirect,
1 = direct.
lenintegerLength of content in seconds; appropriate for video or audio.configuration of amount of video ads
languagestringContent language using ISO-639-1-alpha-2

The attributes must be handed over in encoded deep object style. Attributes that are handed over in a wrong way or with wrong values (values that dont apply with the standard) are sorted out and cannot be processed.

&iab_content%5Bid%5D%3D78342687&iab_content%5Bepisode%5D%3D8&iab_content%5Btitle%5D%3DDie%20Social%20Media%20Edition&iab_content%5Bseries%5D%3DGermany%27s%20Next%20Topmodel&iab_content%5D%3DHeidi%20Klum&iab_content%5Bgenre%5D%3DEntertainment&iab_content%5Bisrc%5D%3Dsome_isrc&iab_content%5Burl%5D%3Dhttps%3A%2F%2Fwww.joyn.de%2Fplay%2Fserien%2Fgermanys-next-topmodel%2F17-8-die-social-media-edition&iab_content%5Bcat%5D%3D1014&iab_content%5Bcat%5D%3D552&iab_content%5Bprodq%5D%3D1&iab_content%5Bcontext%5D%3D1&iab_content%5Bcontentrating%5D%3DFSK%2012&iab_content%5Bkeywords%5D%3Dkeyword1%2Ckeyword2%2Ckeyword3&iab_content%5Blivestream%5D%3D0&iab_content%5Bsourcerelationship%5D%3D1&iab_content%5Blen%5D%3D7883&iab_content%5Blanguage%5D%3Dde

&iab_content[id]=78342687&iab_content[episode]=8&iab_content[title]=Die Social Media Edition&iab_content[series]=Germany's Next Topmodel&iab_content[artist]=Heidi Klum&iab_content[genre]=Entertainment&iab_content[isrc]=some_isrc&iab_content[url]=https://www.joyn.de/play/serien/germanys-next-topmodel/17-8-die-social-media-edition&iab_content[cat]=1014&iab_content[cat]=552&iab_content[prodq]=1&iab_content[context]=1&iab_content[contentrating]=FSK 12&iab_content[keywords]=keyword1,keyword2,keyword3&iab_content[livestream]=0&iab_content[sourcerelationship]=1&iab_content[len]=7883&iab_content[language]=de
DatatypeDeep Object Style
integer/stringiab_content[name_of_attribute]=value
arrayiab_content[name_of_attribute]=value1&iab_content[name_of_attribute]=value2....
objectiab_content[name_of_object][name_of_object_attribute1]=value
&iab_content[name_of_object][name_of_object_attribute2]=value
object arrayiab_content[name_of_object][position_in_array][name_of_attribute1]=value
iab_content[name_of_object][position_in_array][name_of_attribute2]=value
iab_content[name_of_object][position_in_array+1][name_of_attribute1]=value

IAB Categories

We expect the categories to be handed over according to the lastest version 3.0, which can be found on: Content Taxonomy. Please be informed that we temporarily need to map the categories to an older version for the programmatic distribution. Since the versions are not fully backwards compatible, it can happen that not all of the categories can be handed over on the programmatic route.

Supported Genre

The following genre are supported by DSPs:

  • Action
  • Adventure
  • Animals
  • Animation
  • Automotive
  • Biography
  • Comedy
  • Cooking
  • Crime
  • Documentary
  • Drama
  • Education
  • Entertainment
  • Fantasy
  • Fashion
  • History
  • Horror
  • Music
  • Mystery
  • News
  • Reality
  • Romance
  • Sitcom
  • Sports
  • Thriller
  • Travel
  • Other
  • War
  • Weather
  • Western

Additional Player-Requirements

Click/Tap Handling

If the user taps on a video ad, the click-url must be opened in the in-app browser and the videoad must be paused, until the user closes the browser. Afterwards the video ad has to be resumed.

Fallback Handling

If there is no fill, the adserver responses with a so-called fallback VAST XML. A fallback VAST XML has an extra <Fallback>-Node in VAST Extensions. If such an XML is recognized by the player, the media files (1 sec. videos) don't need to be played. The player only has to fire the impression trackings and can skip to the next video-ad or to the content.

← IntroductionIntroduction →