Click Here to Expand Version History!
VERSIONDATEAUTHORChanges
Ad Tag 4.22018-08-09AK
  • JSONP format removed and substituted with JSON (async)
  • Click tracking is added for all other ad servers
  • Bugfixes
Ad Tag 4.12018-07-24AK
  • Click tracking is added for mediation through MoPuB
  • Switch to SOMA API v 600
  • Bugfixes
Ad Tag 4.0.42018-06-19AKChanges and improvements, as well as added GDPR parameters
Ad Tag 3.0.42018-02-06AKImprovements on postscribe to support functional comments on creatives
Ad Tag 3.0.32018-01-08AKReduced size, various bug fixes
Ad Tag 2.3.0 [Deprecated]2016-11-18BROutstream Video Support added
Ad Tag 2.2.19 [Deprecated]2016-09-13BRSecure parameter added
Ad Tag 2.2.15 [Deprecated]2016-04-21BRSynchronous Ad Tag parameter added
Ad Tag 2.2.7 [Deprecated]2015-09-15NC

Ad Tag speed optimization

Changed VAST Skip timeout

Introduced Windows Phone ID

Ad Tag 2.2.6 [Deprecated]2015-08-15NCEnhanced passing referrer URL
Ad Tag 2.2.5 [Deprecated]2015-08-07NCBug fixes
Ad Tag 2.2.4 [Deprecated]2015-08-05NC

Bundle ID, Website URL, IAB Category, and app name were added as parameters.
Also, the Ad Tag automatically detects and passes the website referrer URL.

Ad Tag 2.2.0 [Deprecated]2015-06-16NCAdded VAST Video 2.0 Support
Ad Tag 2.1.5 [Deprecated]2015-05-07NCAdded query string param
Ad Tag 2.1.4 [Deprecated]2015-04-20NCRemoved all document.write
Ad Tag 2.1.3 [Deprecated]2015-03-26NCFix for callback
Ad Tag 2.1.2 [Deprecated]2015-03-17NCIntroduced wide skyscraper dimension
Ad Tag 2.1.1 [Deprecated]2015-02-23NCAdded callback for closing interstitial ads
Ad Tag 2.1.0 [Deprecated]2015-02-19NCNow supports interstitial
Ad Tag 2.0 [Deprecated]2014-11-17NCRewrite
Ad Tag 1.82014-07-21NCImproved geolocation
Ad Tag 1.72014-07-11NCIntroduced geolocation service
Ad Tag 1.62014-05-06MOAdded interstitial formats. Instructions for passbacks with Google DFP. Instructions for Mopub. Added Google Advertising ID. Added COPPA. Minor changes.
Ad Tag 1.52013-11-14MONow supports automatic and manual cachebuster (parameter “cb”)
Ad Tag 1.42013-10-28BUPassback tags are now supported via “passback” parameter. In-App and MobileWeb documents merged.
Ad Tag 1.32013-10-21MOMinor changes. First In-App version.
Ad Tag 1.22012-12-19BUAdded additional parameters: autorefresh, format, formatstrict, dimension, dimensionstrict
Ad Tag 1.12012-02-06MOAdded additional targeting parameter. Added auto refresh.
Ad Tag 1.02011-12-06MOInitial version

Ad Tag Generator in SPX

The Smaato Ad Tag can either be assembled and modified according to the documentation below or comfortably generated using SPX's built-in Ad Tag Generator.


 To generate your Ad Tags in SPX, please follow these steps:

  1. First, while in SPX select Integration Options for the dropdown menu in the right corner of the dashboard.
  2. Then Scroll down to Code Integration for Mobiles Sites.
  3. In the Ad Tag form, select an Adspace from the drop-down.
  4. Choose asynchronous or synchronous loading
    1. Asynchronous is the default setting and is the ideal selection for most cases; 
    2. We do not recommend selecting synchronous unless you explicitly need to.
  5. Insert any macros for user information as you have defined them on your page 
    1. (i.e. if you are to enter %%YOB%% as a macro for User Age, the ad tag will use the value set for %%YOB%% as an age value in the ad request). 
    2. This step is optional; however, we highly encourage passing user information to increase ad relevance, yield, and revenue.
  6. As you're specifying and tweaking the contents of your ad tag, it is simultaneously being generated. 
  7. When you're finished, click Copy to Clipboard, and then paste this into your page, right at where the ad placement should be. 
  8. Now you are done!

SPX Menu - Integration OptionsAd Tag Section


Ad Tag Version 4.3

JavaScript Ad Tag for in-application and mobile web.


Please note: a WebView is needed for in-app integrations”, we should add that “richmedia ads will be rendered in iframe for mobile browsers


Introduction

The Ad Tag is a lightweight, quick and easy javascript based solution making it easy to integrate Smaato ads directly into your mobile website.

The main usage of the ad tag is mobile websites, but it can also be used for in-app integrations.

Please note: a WebView is needed for in-app integrations)

The Ad Tag can be easily enriched with user targeting data, device ID, demographics or location data (see table below).

Furthermore, the Ad Tag gives you the option to choose ad dimension, auto reload timer as well as ad display mode (Inline or Fullscreen). 

Also, the Ad Tag can be also enriched using your ad server’s replacement macros in order to pass additional targeting data.

Ad Tag Code for InApp and MobileWeb

Inline Ads

<div id="smaatoad" style="padding:0px"></div>
<script type="text/javascript" src="https://soma-assets.smaato.net/js/smaatoAdTag.js"></script>
<script>
    function myJSCallBack(status) {
        if (status == "SUCCESS") {
            // TODO Handle ad available (Option)
        } else if (status == "ERROR") {
            // TODO Handle not ad available
        }
    };
    SomaJS.loadAd({
        adDivId: "smaatoad",
        publisherId: REPLACE_WITH_PUBLISHER_ID,
        adSpaceId: REPLACE_WITH_ADSPACE_ID,
        autoReload: 240,
        dimension: "xxlarge",
        dimensionstrict: true,
        keywords: "cars,shopping",
        gender: "m",
        age: 27
    }, myJSCallBack);
</script>

Full Screen Ads

If you are not able to show inline ads in your mobile website, you should opt for full screen ads; these ads are shown in full screen mode and won't need space inside your site as they will overlay the web page content. Full screen ads can be shown automatically (as soon as they are ready to be shown) or after a user action (e.g. user finished reading an article). Full screen ads can also be dismissed via close button by the user at any time.

In order to enable full screen ads, you need to set first the dimension to full screen (appropriate dimension should be used for tablet and phone) and activate the full screen mode. All you need are the following lines :

<div id="smaatoad" style="padding:0px"></div>
<script type="text/javascript" src="https://soma-assets.smaato.net/js/smaatoAdTag.js"></script>
<script>
    SomaJS.loadAd({
        adDivId: "smaatoad",
        publisherId: REPLACE_WITH_PUBLISHER_ID,
        adSpaceId: REPLACE_WITH_ADSPACE_ID,
        autoReload: 240,
        dimension: "full_320x480",
        dimensionstrict: true
    });
</script>

For tablet ad dimension, please use "full_768x1024" for portrait mode or "full_1024x768" for landscape mode. Phone dimensions are "full_320x480" for portrait and "full_480x320" for landscape.

Full screen ads can be used in combination with some optional callbacks that will notify you on user actions and ad states. 

  1. shouldShowModal: If this callback is defined, it has to return true or false . If returns true, the modal will be presented, otherwise it will be discarded.
  2. modalClosedCallback: If defined, this callback will be called once the modal is closed by the user.

Example:

<div id="smaatoad" style="padding:0px"></div>
<script type="text/javascript" src="https://soma-assets.smaato.net/js/smaatoAdTag.js"></script>
<script>
SomaJS.loadAd({
    adDivId: "smaatoad",
    publisherId: REPLACE_WITH_PUBLISHER_ID,
    adSpaceId: REPLACE_WITH_ADSPACE_ID,
    modalDisplay: true,
    shouldShowModal: function() {
        console.log("Modal is going to be shown!");
        return true;
    },
    modalClosedCallback: function() {
        console.log("The modal is closed!");
    },
    dimension: "full_320x480"
});
</script>

If you use the above configuration, the full screen ad will be shown as soon as the is ad is loaded.

The second option is showing the full screen ad after a user action. To enable this, you need to specify that in the ad tag integration and enable caching ads in background, along with modalDisplay parameter, shouldCacheModal parameter should also be set to true.

Outstream Video

Outstream video ads can be placed inside any mobile web content.

Publishers can load an outstream video using this ad tag snippet:


We recommend that you generate an Outstream Ad Tag within SPX, as explained hereafter.

<div id="REPLACE_WITH_YOUR_ID_OF_CHOICE" style="padding: 0px"></div>
<script type="text/javascript" src="https://soma-assets.smaato.net/js/smaatoAdTag.js"></script>
<script>
    function callBackForSmaato(status){
        if(status == "SUCCESS"){
            console.log("callBack is being called with status : " + status);
        } else if (status == "ERROR"){
            console.log("callBack is being called with status : " + status);
        }
    };
    SomaJS.loadAd({
        adDivId : "REPLACE_WITH_YOUR_ID_OF_CHOICE",
        publisherId: REPLACE_WITH_PUBLISHER_ID,
        adSpaceId: REPLACE_WITH_ADSPACE_ID,
        format: "outstream",
        formatstrict: true,
        dimension: "medrect",
        width: 300,
        height: 250, // Dimension values are examples and should match SPX configuration
        outstreamSelectors: ["#REPLACE_WITH_YOUR_ID_OF_CHOICE"],
        sync: false
    }, callBackForSmaato);
</script>

Please note the following:

  • The value for 'format' key should be 'outstream'
  • The value for 'outstreamSelectors' should be the div id where the video should be placed.
  • There is no callback needed; the outstream tag will try again after 10 seconds if no ad received. This time is currently not configurable.

Important Note For Outstream Video:

Content Revision:
Since a scrolling action is needed in order for the video to auto play, the Outstream Ad Tag should be wrapped by enough scrollable content before and after.


Generating Outstream Video Tags

If you're interested in integrating outstream video ads, we highly recommend using our Ad Tag Generator in SPX - at least for configuring and testing your setup.

Access our Ad Tag Generator here: https://spx.smaato.com/publisherportal/pages/integration/integration.xhtml

Just select an outstream adspace that you've created under Inventory, copy your generated tag and paste it into your page.

To test your setup, use the following test credentials in your tag:


	publisherId: 0,
    adSpaceId: 3090,

That will look something like this (click to enlarge):

Usage

Insert the code at the desired section of your application.

Replace REPLACE_WITH_ADSPACE_ID with your Ad Space ID and replace REPLACE_WITH_PUBLISHER_ID with your Publisher ID.

Please inform your account manager that you’re using the ad tag.


Advanced Usage

You can add additional targeting data by inserting additional parameter lines. Usually, you’ll insert your ad server’s replacement macros here instead of actual data.

The format to be used is the following:

PARAMETER: 'STRING' (for string values)

PARAMETER: true (for boolean values)

PARAMETER: 12345 (for numeric values, WITHOUT quotation marks!!!)

Example:

city: 'Miami'

formatstrict: false

age: 25

Parameters & Descriptions

ParameterMandatoryDescriptionPossible ValuesExample
adDivIdyes

The Div ID where the ad should be placed.

Note: Please use unique Div IDs if there are multiple ad placements on one page.

See example'smaatoad'
dimensionno

The desired dimension of ads to be returned. 
Standard Formats MMA (default): 
Any MMA size (the system will determine the right one for the requesting phone).

  • Medium Rectangle (300x250) 
  • Leaderboard(728x90)
  • Skyscraper(160x600)
  • Full screen(320x480)
  • Full screen(480x320)
  • Full screen(768x1024)
  • Full screen(1024x768)
  • "mma" 
  • "medrect" 
  • "leader" 
  • "sky"
  • "widesky"
  • "small"
  • "large"
  • "medium"
  • "xlarge"
  • "xxlarge"
  • "full_320x480" 
  • "full_480x320" 
  • "full_640x960" 
  • "full_960x640"
  • "full_1136x640"
  • "full_768x1024" 
  • "full_1024x768"
  • "full_800x1280"
"mma"
gendernoThe user’s gendermale,female,m,f"m"
gdprno

info: http://advertisingconsent.eu/

Parameter used to enable/disable gdpr

1, 01
gdpr_consentno

Base64-encoded consent string

only when gdpr value is set to true
See example"BOMCfKjOMdcevABAB8AAAAAZ+A=="
agenoThe user’s age.2-digit number. If only a range is available, use the mean average.See example25
keywordsnoTags (free text, case insensitive) describing the content.string: comma separated values'motorsport,news,cars'
qsnoQuery String: A search term entered by the user within the mobile site.string: comma separated values

'coffee,san+francisco'

syncnoParameter used for requesting the ad synchronously. (Default: false)true, falsetrue
didyes (for in-app traffic)

Only for in-app traffic.

Unified Device ID. Should be enriched with the device id (iOS and/or Android).
The ad tag will then automatically pick up the right parameter for you and let us know if it is iosadid, androidid or googleadid.

iOS - Identifier for Advertising (IDFA) please refer to ASIdentifierManager

Android - Google Android Advertising ID please refer to http://bit.ly/MBMTTJ

Android - Android ID please refer to Settings.Secure.ANDROID_ID

Windows Phone - Windows Phone ID please refer to AdvertisingManager.AdvertisingId | advertisingId property

See example

'1D76F5D1-1983-47C8-B18D119D52E4597A'
diddntyes (for in-app traffic)

Only for in-app traffic.

Apple’s advertisingTrackingEnabled Property. (false = user has decided against tracking – this is the opposite way around as on Android)

Android limit ad tracking preference.(true = user has decided against tracking – this is the opposite way around as on iOS)

true, falsefalse
coppayes“0” will indicate that your content should not be treated as child-directed for purposes of COPPA. “1” will indicate that your content should be treated as child-directed for purposes of COPPA.0, 10
cbnoCachebuster. Insert your cachebuster macro here. This is optional: If no cachebuster is set, we’ll generate our own.String'%%CACHEBUSTER%%' (Dart)
autoReloadnoAutomatically refresh ad. Value in seconds. Minimum value: 10.Any number, minimum: 10, maximum 240.45
latitudeno (but highly recommended)GPS coordinates of the user’s location (latitude).Latitude as decimal degrees.37.530676
longitudeno (but highly recommended)GPS coordinates of the user’s location (longitude).Longitude as decimal degrees.-122.262447
countrynoThe country of the users location.See example'United%20States'
countrycodenoThe country code of the users location.See example'US'
citynoThe city name of the users location.See example'New%20York'
zipnoThe postal code of the users location.See example'94402'
regionnoThe region of the users location.See example'Texas'
useLocationno

Will enable user geolocation tracking.

PS: This will trigger a popup to get users permission

true, false (default)true
refyes (‘no’ if the device is requesting directly or if you’re sending the correct referer header of the requesting webpage)Refers back to the origin of the user (i.e. the URL of your mobile website)String"http://my.website.com"
iabcategoryno (but highly recommended)The Application or Mobile Website IAB category.String
IAB-XXX 
or 
IAB-XXX-XXX
adspacenameno (but highly recommended)The Adspace's name. Please use the following format: AppOrSiteName_OSName_AdspaceDimensionString
MyApp_iOS_320x50

Synchronous vs. Asynchronous Ad Tag

Recently, we've added the option to request our ad tag synchronously (as opposed to previously only asynchronously). The following details outline what this means and how this may be useful to you.

What's the difference between the types of Ad Tag?

Javascript in itself is synchronous and single-threaded. That means that scripts and script contents are not executed in parallel, but sequentially. While there are improvements made to Javascript engines in modern browsers, this basic caveat has remained.

Therefore, "asynchronous" javascript describes a way to handle loading and executing additional scripts in a given page's context without blocking the initial process of loading the page, mostly using callback functions and waiting/handling events.

How may this create issues for me?

As a publisher, asynchronicity of a tag on your own property is a good idea (because your page isn't prone to being stalled by a delayed ad request). However, especially when it comes to cases using an environment that's entirely detached from the rest of the page (such as iframes or SDKs), asynchronous tags have shown to "confuse" said environment and e.g. lead to triggered impression beacons without an ad being actually shown. This mostly applies to using the ad tag within a third-party SDK (e.g. MoPub) or an ad server.

To rectify this, set the sync parameter's value of your ad tag to true (the default is false!).

Callbacks

Use callback to trigger custom events in case Smaato serves an ad or does not serve an ad. For example, you can insert a tracking method that informs you whether an ad was served or not. You can also define a custom passback function in order to fill the impression through a different source.

Example:


function myJSCallBack(status) {
    if (status == "SUCCESS") {
        alert("callback invoked, Ad Delivered");
    } else if (status == "ERROR") {
        alert("callback invoked, No Ad Delivered");
    }
};

Setting up a Passback for DFP & GPT Tags

If you're using DFP and requesting Smaato via Ad Tag, you can pass an ad request back from a NoAd-response to DFP - just follow these steps:steps:

1) Prerequisite

You'll need to have the following already set up:

  • An Adspace in SPX that represents your inventory
  • A Line Item in SPX to go along with the above (this can be the default Line Item, or a specific one)
  • A Line Item in DFP with the according Ad Tag - use this snippet with your Publisher and Adspace IDs:
<div id="smaatoad" style="padding:0px"></div>
<script type="text/javascript" src="https://soma-assets.smaato.net/js/smaatoAdTag.js"></script>
<script>
    function callBackForSmaato(status){
        if(status == "SUCCESS"){
            console.log("SUCCESS");
        } else if (status == "ERROR"){
            console.log("ERROR");
        }
    };
   
SomaJS.loadAd({
    adDivId: "smaatoad",
    publisherId: REPLACE_WITH_PUBLISHER_ID,
    adSpaceId: REPLACE_WITH_ADSPACE_ID,
    dimension: "xxlarge",
    ref: "%%PATTERN:url%%"
},callBackForSmaato);
</script>

If you have all of the above set up, you should be able to send ad requests from DFP to Smaato and receive ads in case of a successful ad call.


Now, for the passback:

2) Set up another Ad Unit in DFP to accommodate for the passback

The Ad Unit needs to be unique to the passback and not used for anything else. Mostly, it makes sense to use the original Ad Unit's name and to add *PB*, (passback) or a similar note to the name.

3) Set up your GPT Tag

This one is a little bit tricky; fortunately, you'll only have to do most of the legwork once.

Head over to https://support.google.com/dfp_sb/answer/1651549#noEdit, and follow the instructions on setting up a GPT tag. Please note that unfortunately, you're not able to use the auto-generated passback tag from within the DFP UI.

This tag contains the routing back to your DFP account, and should look something like this:


<script type="text/javascript">
    var googletag = googletag || {};
    googletag.cmd = googletag.cmd || [];
    (function() {
        var gads = document.createElement('script');
        gads.async = true;
        gads.type = 'text/javascript';
        var useSSL = 'https:' == document.location.protocol;
        gads.src = (useSSL ? 'https:' : 'http:') + '//www.googletagservices.com/tag/js/gpt.js';
        var node = document.getElementsByTagName('script')[0];
        node.parentNode.insertBefore(gads, node);
    })();
</script>
<div id="div-gpt-ad-1234567891234-0">
    <script type="text/javascript">
        googletag.cmd.push(function() {
            googletag.defineSlot('/1234/sports/football', [320, 50], 'div-gpt-ad-1234567891234-0')
                .addService(googletag.pubads())
                .setTargeting('Gender','Male');
            googletag.enableServices();
            googletag.display('div-gpt-ad-1234567891234-0');
        });
    </script>
</div>

DFP + Autoreload Issue

If the ad uses autoreload, there is a bug when DFP detects that the ad with the same uniqueID has been already rendered.

IMPORTANT

To solve this, it is necessary append an extra command inside the tag snippet provided by DFP

<script type="text/javascript">
    googletag = undefined;
    var googletag = googletag || {};
    googletag.cmd = googletag.cmd || [];
    (function() {
        var gads = document.createElement('script');
        gads.async = true;
        gads.type = 'text/javascript';
        var useSSL = 'https:' == document.location.protocol;
        gads.src = (useSSL ? 'https:' : 'http:') + '//www.googletagservices.com/tag/js/gpt.js';
        var node = document.getElementsByTagName('script')[0];
        node.parentNode.insertBefore(gads, node);
    })();
</script>
<div id="div-gpt-ad-1234567891234-0">
    <script type="text/javascript">
        googletag.cmd.push(function() {
            googletag.defineSlot('/1234/sports/football', [320, 50], 'div-gpt-ad-1234567891234-0')
                .addService(googletag.pubads())
                .setTargeting('Gender','Male');
            googletag.enableServices();
            googletag.display('div-gpt-ad-1234567891234-0');
        });
    </script>
</div>
2| googletag = undefined;

4) Set up a House Line Item in SPX

...to send NoAds back in DFP's direction:

  • Follow the instructions on https://wiki.smaato.com/display/SPX/Direct+Orders for setting up a House Line Item.
  • Set up an HTML creative and paste your GPT tag in there.
  • Target this House Line Item to your Adspace (as mentioned above).
  • Make sure that the House Line Item is also set to a lower Priority than the Line Item that you'd like to use to get Smaato demand from.

Using the Smaato Ad Tag inside MoPub

Please Note!

  • When using MoPub as your primary Ad Server, we recommend you to use Smaato SDK for a seamless integration.
  • In order to use our Ad Tag inside Mopub, you need to request it synchronously, i.e. set the sync parameter to true!
  • When using our AdTag inside Mopub in applications running on iOS10, you need to add the "Allow Arbitrary Loads in Web Content" key in the info.plist file in order to allow non-secure creatives to render

You can traffic the Smaato ad tag from within your MoPub instance. Make sure to use the passback functionality (prefilled below) and fill in the MoPub macros. See below:

<div id="smaatoad" style="padding:0px"></div>
<script type="text/javascript" src="https://soma-assets.smaato.net/js/smaatoAdTag.js"></script>
<script>
	function callBackForSmaato(status){
 		console.log("callBack was called with status : " + status);
		if (status == "ERROR"){ 
			loaded= true; 
			window.location="mopub://failLoad"; 
		}
	};
	SomaJS.loadAd({
		adDivId: "smaatoad",
		publisherId: REPLACE_WITH_PUBLISHER_ID,
		adSpaceId: REPLACE_WITH_ADSPACE_ID,
		did: "%eudid!", // Android and iOS
		diddnt: ("%%DNT%%" == "1"),
		keywords: "%%KEYWORDS%%",
		latitude: "%%LATITUDE%%",
		longitude: "%%LONGITUDE%%",
		sync: true,
		cb: "%%CACHEBUSTER%%",
		dimension: "xxlarge"
 	},callBackForSmaato);
</script>