Somtag Integration

Integration Steps

1. Embed Somtag

Insert the following code into the <head> of the page:

<script>
(function (s, o, m, t, a, g) {
  s.somtag = {
    cmd: function () {
      g = [].slice.call(arguments);
      g.push(o.currentScript || o.scripts[o.scripts.length - 1]);
      (this.q = this.q || []).push(g);
    } };
    a = o.createElement('script');
    a.src = m;
    o.head.appendChild(a);
  })(window, document, '//ad.71i.de/somtag/loader/loader.js');
</script>

(No access to the <head> section? See FAQ)

2. Configure Somtag

Pass the configObject to the init command. The minimal configuration looks like this:

somtag.cmd("init", {
    config: {
        id: "publisher_id", // Given by the SOM adtec team
    },
});

This minimal configuration will usually not be sufficient for a well targeted ad integration. See configObject for details.

3. Provide User Consent

Following GDPR regulations, it is mandatory to provide the user's consent to Somtag in order to be able to use Somtag library for your ad integration.

3.1 Provide information about IAB TC String 2.0

Somtag follows IAB Europe Transparency and Consent Framework v2. You will be instructed by your SevenOne Media's contact person about the required vendor lists that must be configured in your CMP (Consent Management Platform).

Somtag provides two options to pass the TC String from your CMP.

3.1.1 Pass the TC String during init call:
somtag.cmd("init", {
    config: {
        id: "publisher_id",
        consent: {
            tcfVersion: 2,
            gdprConsent: "CO5bDXcO5bDXcCjAAAENAwCAAAAAAAAAAAAAAAAAAAAA.IGLtV_T9fb2vj-_Z99_tkeYwf95y3p-wzhheMs-8NyZeH_B4Wv2MyvBX4JiQKGRgksjLBAQdtHGlcTQgBwIlViTLMYk2MjzNKJrJEilsbO2dYGD9Pn8HT3ZCY70-vv__7v3ff_3g",
            optOutUncertifiedVendors: false
        }
    },
});
Parameterallowed values
tcfVersion2
gdprConsentTC String created by your CMP.
optOutUncertifiedVendorstrue: user did not accept all non-iab vendors
false: user did accept all non-iab vendors
(see 3.2 for an explanation)
3.1.2 Let Somtag use the CMP API

If no TC String is passed during init, the Somtag library will check if a TCF compliant function from your CMP is available in the top document scope and will call that function itself to derive the consent string.

TCF versionfunction name
TCF 2.0__tcfapi(command, version, callback, parameter)

3.2 Provide information about non-IAB listed vendors

Somtag requires the consent to an aditional list of vendors that are not listed by the IAB. The information if a user fully accepted these complementary vendors must be passed to Somtag during the init call with an optOutUncertifiedVendors flag (see 3.1.1 for a code example).

3.3 Provide consent in terms of ePrivacy

In case you cannot pass an IAB Transparency Consent String or IAB TC String but have a custom solution (like a general cookie purpose banner) you can still pass an opt-out / opt-in information during the init call:

somtag.cmd("init", {
    config: {
        id: "publisher_id",
        consent: {
            optOut: false
        }
    },
});
Parameterallowed values
optOuttrue: user did not agree to all purposes -> no tracking, bidding, targeting
false: user did agree to all purposes -> all tracking, bidding, targeting

Using the optOut flag the Somtag library will still try to retrieve a TC String via the above mentioned __tcfapi API and use that information additionally for any third-party provider but will skip the internal evaluation of the TC String.

4. Get Ads

Display Ads:

<!-- anywhere in the page (preferred in the <head> of the page) -->
<script>
    somtag.cmd("insertAd", "rectangle1", {
        container: "#rectangle_ad_container",
    });
</script>

<!-- anywhere in the page -->
<div id="rectangle_ad_container"></div>

This is an example for a rectangle ad. For full documentation see Retrieve Display Ads

Video Ads:

somtag.cmd("getVideoBlock", "pre", {}, function (err, result) {
    // ... playout the preroll VAST files in `result`
});

This is an example for a preroll block. For full documentation see Retrieve VAST URLs

The configObject

Accurate control over the ad delivery can be achieved by modifying the configObject which is passed to Somtag in somtag.cmd('init', configObject). The most important configuration keys:

enabled: Toggle Advertising

To disable the Somtag advertising for a specific page, simply set the enabled property to false:

somtag.cmd("init", {
    enabled: false, // Default value is `true`, so this key is optional
    // ...
});

device: Force Mobile / Desktop Advertising

By default Somtag will automatically determine a suitable device category, however you can enforce desktop or mobile:

somtag.cmd("init", {
    // ...
    device: {
        mode: "auto", // values: 'mobile', 'desktop', 'auto'. default value. 'auto'
        breakpoint: 728, // threshold value to switch between mobile and desktop,
        // when mode is 'auto'
    },
    // ...
});

taxonomy: (Sub)Site Information

By setting these values you help us to match ads that are especially booked for your content:

somtag.cmd("init", {
    // ...
    taxonomy: {
        channels: [
            "lifestyle", // hierarchical information
            "news", // about
            "whatever", // (sub)site,
            "...",
            "...", // and page content
        ],
        content: "content", // optional: page category. possible values:
        // `content`, `gallery`, `video`, `liveticker`
    },
    // ...
});

Note: the affiliate value in the taxonomy site information is deprecated, please do not use it anymore.

display: Enabling Display Ad Slots

ad slot: a predefined area of the page designated to display advertising.

An insertAd() call will insert an ad in the ad slot only if the slot was enabled in configObject.display.slots before. If the slot was activated Somtag will try to insert an ad. Which ad product is going to be inserted will be decided at request time at the ad server.

Note: You may only enable slots that you will also do an insertAd() call on.

somtag.cmd("init", {
    // ...
    display: {
        slots: {
            fullbanner2: { enabled: true },
            skyscraper1: { enabled: true },
            rectangle1: { enabled: true },
            mbanner1: { enabled: true },
            inread1: { enabled: true },
            minread1: { enabled: true },
            performanceFullbanner1: { enabled: true },
            performanceFullbanner2: { enabled: true },
            performanceFullbanner3: { enabled: true },
            performanceFullbanner4: { enabled: true },
            performanceMbanner1: { enabled: true },
            performanceMbanner2: { enabled: true },
            performanceRectangle1: { enabled: true },
            performanceRectangle2: { enabled: true },
            performanceRectangle3: { enabled: true },
            performanceRectangle4: { enabled: true },
            performanceRectangle5: { enabled: true },
            performanceRectangle6: { enabled: true },
            performanceRectangle7: { enabled: true }
        },
    },
    // ...
});

More information regarding our ad slots can be found on Overview of Display Ad Slots and Products

video: Enabling Video Ad Blocks

video block: a series of single video ad spots running at a certain position in relation to the content video.

You need to enable each video block that you want your content video to be advertised with in the configObject:

somtag.cmd("init", {
    // ...
    video: {
        longplay: true,
        blocks: {
            pre: { enabled: true },
            mid: { enabled: true },
            post: { enabled: true },
        },
    },
    // ...
});

Overview of all video ad blocks can be found on video ad blocks.

iabContent: Meta Data about the video content (video only)

With the help of iabContent 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.

somtag.cmd("init", {
    // ...
    video: {
        iabContent: {
            id: "78342687",
            episode: 8,
            title: "Die Social Media Edition",
            series: "Germany's Next Topmodel",
            season: "17",
            artist: "Heidi Klum",
            genre: "Entertainment",
            isrc: "ISO3901_code",
            url: "https://www.joyn.de/play/serien/germanys-next-topmodel/17-8-die-social-media-edition",
            cat: ["1014", "552"],
            prodq: 1,
            context: 1,
            contentrating: "FSK 12",
            sourcerelationship: 1,
            keywords: "keyword1,keyword2",
            livestream: 0,
            len: 7883,
            language: "de"
        }
    },
    // ...
});

Please see OpenRTB Content Object for detailed description of the attributes and their data types.

keywords: Targeting on Special Topics

With the help of keywords you can tag the context of your content independently from taxonomy.channels in order to match ads to certain topics:

somtag.cmd("init", {
    // ...
    keywords: ["pollenflug", "birke"],
    // ...
});

Please ask your product manager at SOM for details in which cases tagging your content with keywords could be useful.

With custom-keyvalue you can enrich the tagging with your own values. In 'config' the property should look like:

custom: [
    { key: "A", value: ["a", "b", "c"] },
    { key: "B", value: ["x", "y", "z"] }, // ...
];

Example:

somtag.cmd('init', {
      config: {
        id: 'publisherde' // Given by the SOM adtec team
      },
custom: [
    { key: 'football', value: ['club1', 'club2']}
    ],
taxonomy: {...}, ...

OpenRTB Content Object

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 the correct format. 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 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
← Somtag IntroductionCallback Function →