Tagging guide

This guide describes the available tagging types (modes) and provides recommendations as well as best practices. It addresses web developers (administrators) who need to implement the ad tags on the website.

Information in ad tags

Each ad tag contains the following information:

Information
Description
siteId
identifies the website; parent element of a page
pageId
identifies the page on a website; child element of the website
formatId
identifies the format (medium rectangle, skyscraper, etc.)
target
optional; used to pass keywords and key=value pairs

sas.call tag options

Option
Type
Default value
Description
async
boolean
false
Forces a specific tag to be async. Warning: this option is only available if your placement use compatible templates (usage of sas_isAsyncCall mandatory)
forceMasterFlag
boolean
false
Forces the master flag; the master flag is used for page view counting; if the master flag is true, the ad call returns an ad (as usual) and the ad call is logged as a page view (page impression); ad calls with the master flag "true" will be reported as page views in Smart AdServer's reports
resetTimestamp
boolean
false
resets the timestamp; timestamps are used for features such as links (displaying ads from insertions always together on a page) or exclusions (never display ads from certain insertions together on a page)
clickTrackingUrl
string
empty
Adds a 3rd party click tracking URL
clickTrackingEncodingLevel
integer
0
Sets the encoding level for the clickTrackingUrl option. The parameter indicates the number of times that the click URL must be encoded before appending it to the 3rd party click tracking URL. For instance, clickTrackingEncodingLevel=2 means that the click URL is encoded twice.

Overview ad tag types

This table describes all the ad tag types as exported from the Smart AdServer UI

Ad tag type
Scripts
Where to place scripts
Typical usage
Synchronous (Standard) generic scripts, ad tags for each format on a page
generic scripts in the <head>; ad tags in the <body>
to retrieve ads one by one (as opposed to OneCall) synchronously (as opposed to asynchronous tagging)
Asynchronous (Ajax) generic scripts, ad tags for each format on a page
generic scripts in the <head>; ad tags in the <body>
to retrieve ads asynchronously without interference with the content
Synchronous One Call (One Call) generic scripts, ad tags for each format on a page
generic scripts in the <head>; ad tags in the <body>
to retrieve ads in one single call
Asynchronous One Call (Ajax One Call) generic scripts, ad tags for each format on a page
generic scripts in the <head>; ad tags in the <body>
to combine asynchronous tagging with OneCall
NonRich no javascript, one HTML ad tag for each format on the page; consists of an image source (img src) and a click url (a href)
ad tags in the <body>
to retrieve ads in environments where javascript cannot be used
Agency one javascript for each format on a page
ad tags in the <body> or a third party system
to make a third party system (e. g. a publisher ad server) retrieve ads from Smart AdServer (in the third party system, the Agency tag is used as a redirect tag); usage in an HTML page recommended only if none of the other tag types can be used
Standalone one javascript for each format on a page
ad tags in the <body> or a third party system
to make a third party system (e. g. a publisher ad server) retrieve ads from Smart AdServer (in the third party system, the Agency tag is used as a redirect tag); usage in an HTML page recommended only if none of the other tag types can be used

Generic scripts

Generic scripts are exported together with the ad tags (except for "NonRich", "Standalone" and "Agency") and must be integrated into the <head> of the page. They consist of:

  • the Smart AdServer smart.js library
  • the sas.setup ad manager

Example

<script src="//ced.sascdn.com/tag/620/smart.js" type="text/javascript"></script>
<script type="text/javascript">
    sas.setup({ networkid: 620, domain: "//www5.smartadserver.com" });
</script>

Calling ads over HTTPS

The ad tags you can export from the user interface are already HTTPS compatible. They use a schema-less URI model and can be used on HTTP and HTTPS web sites directly.

If your website (page) is loaded over HTTPS:

  • Smart AdServer ad tags must be called with HTTPS
  • third party ad tags (agency scripts pasted on the Creatives tab of insertions) must be called with HTTPS
  • the landing pages (clickURLs) must be secure (HTTPS)

Failing to do so leads to a security error in the browser!

Setting up the ad manager

Prior to calling any ad, the sas object must be initialized using the sas.setup(options) method. It must be called only once.

Available options:

Option name Type Mandatory Default value Description
domain string yes n/a Domain of the network (account) at Smart AdServer
async boolean no false If true, all ad calls of the given page will be asynchronous
networkid integer yes empty ID of the network (account) at Smart AdServer
renderMode integer no 0 Defines how ads are rendered. Values:
0 => render ad as soon as ad is ready
1 => render ad as soon as document is ready
2 => render ad on demand; sas.callAds() must be called
inSequence boolean no false If true, all ads are called in sequence to handle linked or excluded insertions
uid string no empty Unique identifier; overrides the unique id in Smart AdServers' pid-Cookie; used when devices cannot be identified with cookies (e. g. in mobile apps with Smart AdServer's iOS or Android SDK); Make sure this id is big enough to avoid id collisions

Best practices and recommendations

OneCall tagging vs Standard tagging

With OneCall tagging you can call all the formats (formatIds) of a given page in a single call. With Standard tagging, you call each format separately.

Smart AdServer strongly recommends OneCall Tagging. Standard tagging is not recommended. Some features do not work seamlessly with Standard tagging. For a comparison, read here.

Synchronous tagging vs Asynchronous tagging

Asynchronous tagging allows you to retrieve ads without interfering with the rest of the web page. It uses DOM manipulation instructions instead of document.write to retrieve ads.

Set the async option to true in the sas.setup function to enable the asynchronous retrieval. Also, use the renderMode, to declare how the ads are supposed to be rendered.

Smart AdServer strongly recommends fully asynchronous tagging (synchronous tagging is not recommended). Fully asynchronous tagging is the safest choice when facing latencies.

Fully asynchronous tagging

With fully asynchronous tagging, you use asynchronous calls for the formats (ad tags) and the configuration file (e. g. //ced.sascdn.com/tag/620/smart.js). This results in a fully asynchronous execution of all Smart AdServer scripts.

Rules:

  • when loading the configuration file, its async attribute must be declared 
  • in the sas.setup function, the async option must be set to true
  • the <div> for the ad must be created before invoking the function sas.call
  • the <div> for the ad must be named sas_<formatId>; example: when calling formatId: 12345, the id of the <div> must be named sas_12345.
  • async calls must not be mixed with non-async calls on the same page

All the calls to the sas namespace in the page must be inserted in a callback, which will be pushed into "sas.cmd" (including sas.setup).

Example with OneCall tagging

Generic scripts (in the <head>)

<script src="//ced.sascdn.com/tag/620/smart.js" async></script>
<script>
    var sas = sas || {};
    sas.cmd = sas.cmd || [];
    sas.cmd.push(function() {
        sas.setup({ networkid: 620, domain: "//www5.smartadserver.com", async: true });
    });
    sas.cmd.push(function() {
        sas.call("onecall", {
            siteId: 103409,
            pageId: 659846,
            formatId: '14968,14309,17669',
            target: ''
        });
    });
</script>

 Ad Tag

<div id="sas_14968"></div>
<script>
    sas.cmd.push(function() {
        sas.render("14968");
    });
</script>

Example with Standard tagging

Generic scripts (in the <head>)

<script src="//ced.sascdn.com/tag/620/smart.js" type="text/javascript" async></script>
<script type="text/javascript">
    var sas = sas || {};
    sas.cmd = sas.cmd || [];
    sas.cmd.push(function() {
        sas.setup({ networkid: 620, domain: "//www5.smartadserver.com", async: true });
    });
</script>

 Ad Tag

<div id="sas_14968"></div>
<script type="text/javascript">
    sas.cmd.push(function() {
        sas.call("std", {
            siteId: 103409,  
            pageId: 659846, 
            formatId: 14968, 
            target: '' // Targeting
        });
    });
</script>

OneCall tagging

With OneCall tagging you can call all the formats (formatIds) of a given page in a single call, rather than each format separately.

For OneCall tagging, you need to

  • call sas.setup with the domain parameter
  • specify the call type onecall in sas.call(<call type>, <options>)

 Example generic scripts

<script src="//ced.sascdn.com/tag/620/smart.js" type="text/javascript"></script>
<script type="text/javascript">
    sas.setup({ networkid: 620, domain: "//www5.smartadserver.com" });
</script>

 Example ad tag

<script type="text/javascript">
	sas.call("onecall", {
		siteId:		103409, 
		pageId:		659846,
		formatId:	'14968,14309,17669',
		target:		''  // Targeting
	});
</script>

The ad tag above calls the 3 formatIds 14968, 14309 and 17669 in onecall mode.

Rendering a format

To render a format, call the method sas.render([formatId])

Example 1

<script type="text/javascript">
 sas.render('14968'); // Format : myformat
</script>

The example above renders the formatId 14968.

 Example 2

// will render the format id 12345
sas.render(12345);
 
// will trigger the rendering if renderMode is 2 (render ad on demand)
sas.render();

The example above calls the method sas.render without any parameter. This triggers the rendering when renderMode is set to 2 (render ad on demand).

The callback beforeRender(data) is called before the format rendering (sas.render method). The callback is only called if the oneCall has produced a successful response. The data object contains the rendering context (formatId and tagId).

beforeRender(data) could be used to execute javascript in case of empty ad responses (noad). However, the onNoad(data) callback function is the recommended method for this purpose (read below: Managing empty ad responses (noad)).

Managing empty ad responses (noad)

The onNoad(data) callback function is triggered if there is no ad to display for the given format (empty ad response). You can use this callback function to execute javascript code on your website when an ad request does not return any ad.

In case of callType="onecall", the callback will be triggered for each empty format.

The onNoad(data) callback function has the properties:

  • data.tagId, (string): the tag id of the noad
  • data.formatId, (string): the format id of the noad

Example

<!doctype html>
<html lang="en">
<head>
	<meta charset="utf-8">
	<title>DEMO TAGS</title>
	<script src="//ced.sascdn.com/tag/620/smart.js" type="text/javascript" async></script>
<script type="text/javascript">
    var sas = sas || {};
    sas.cmd = sas.cmd || [];
    sas.cmd.push(function() {
        sas.setup({ networkid: 620, domain: "//www5.smartadserver.com", async: true });
    });
</script>
</head>
<body>
<div id="sas_36780"></div>
<script type="text/javascript">
    sas.cmd.push(function() {
        sas.call("std", {
            siteId: 86374,
            pageId: 609161,
            formatId: '36780',
            target: ''
		}, {
			onNoad: function(data){
				if (data.formatId) {
					console.log(data);
					console.log("FORMAT ID : "+data.formatId);
					console.log("TAG ID : "+data.tagId);
				}
			}
		});
    });
</script>
</body>
</html>

Standard tagging

Smart AdServer does not recommend Standard tagging. Use OneCall tagging instead. For more, read above: Best practices and recommendations.

To use standard tagging, you have to

  • call sas.setup (with the mandatory domain parameter) and
  • call sas.call(<call type>, <options>) with the call type std (for "standard").

Example generic scripts

<script src="//ced.sascdn.com/tag/620/smart.js" type="text/javascript"></script>
<script type="text/javascript">
    sas.setup({ networkid: 620, domain: "//www5.smartadserver.com" });
</script>

The example above shows the generic scripts to be placed into the <head>.

Example ad tag

<script type="text/javascript">
	sas.call("std", {
		siteId:		103409,	// 
		pageId:		659846,	// Page : MySite/home
		formatId: 	14968,	// Format : banner 300x250
		target:		''	// Targeting
	});
</script>
<noscript>
	<a href="http://www5.smartadserver.com/ac?jump=1&nwid=620&siteid=103409&pgname=home&fmtid=14968&visit=m&tmstp=[timestamp]&out=nonrich" target="_blank">                
		<img src="http://www5.smartadserver.com/ac?out=nonrich&nwid=620&siteid=103409&pgname=home&fmtid=14968&visit=m&tmstp=[timestamp]" border="0" alt="" /></a>
</noscript>

The example above retrieves an ad in standard (std) tagging mode.

Calling a format multiple times

In some cases you may want to call the same format multiple times on a given page. For instance, you may want to call two medium rectangles (with the same formatId) on a page: one at the top and one at the bottom of the page.
Use the tagId option in the sas.call method to make sure that the ads appear in the correct <div> containers. In this method, you specify the Ids of the containers, where the format is supposed to be displayed.

Example 1

<script type="text/javascript">
sas.call("std", {
    siteId:     79441,  // 
    pageId:     579235, // Page : mywebsite/mypage (PageID=579235)
    formatId:   34156,  // Format : mymediumrectangle 300x250
    target:     '',  // Targeting
    tagId:      'medrec-top'
});
</script>

The example above calls the formatId 34156 and displays it in the div with id 'medrec-top'

 Example 2

<script type="text/javascript">
sas.call("std", {
    siteId:     79441,  // 
    pageId:     579235, // Page : mywebsite/mypage (PageID=579235)
    formatId:   34156,  // Format : mymediumrectangle 300x250
    target:     '',  // Targeting
    tagId:      'medrec-bottom'
});
</script>

The example above calls the formatId 34156 and displays it in the div with id 'medrec-bottom'.

Cleaning ads

To clean a specific format, use the sas.clean([formatId]) method.

Calling the method without any specified formatId will clean all the formatIds of the page.

Example

// clean the format 300
sas.clean(300);
 
// clean all formats
sas.clean();

 When using the sas.clean method, the callback onClean(formatId, element) in the sas.call method will be triggered:

  • formatId (integer): the Id of the cleaned format
  • element (DOM element): the format DOM element container which will be cleaned

You can register a function to be warned when a clean has been executed.

Calling ads in an iframe

To call ads in an iframe, change the callType from "std" to "iframe" and specify the width and height of the iframe.

Example

<script type="text/javascript">
    sas.call("iframe", {
            siteId: 53008,
            pageName: 'mypage',
            formatId: 23028,
            height:300,
            width:250
    });
</script>

Forcing a specific ad call to be asynchronous

The renderMode in the sas.setup method applies to all the ad calls on the page. However, you can also force a specific ad call to be asynchronous by setting the async option in the sas.call method to true (default: false).

Example

<script type="text/javascript">
sas.call("std", {
    siteId:     79441,  // 
    pageId:     579235, // Page : mywebsite/mypage (PageID=579235)
    formatId:   34156,  // Format : mymediumrectangle 300x250
    target:     '',  // Targeting
    async:      true
});
</script>

Keep in mind that this needs compatible script templates (used in the insertions): the script template has to use the macro [sas_isAsyncCall]. The macro is replaced by true or false and allows for javascript expressions such as:

if([sas_isAsyncCall]){
document.createElement...
} else {
document.write...
}

Refreshing ads

To refresh ads, use the method sas.refresh([formatId], [options]).

FormatId

When using sas.refresh, the following rules apply for the formatId:

  • the formatId can be integer, string or array
  • if no formatId is specified, all the ad calls done in the page will be reloaded
  • if a formatId is specified, the ad will be called using the standard call type; this applies even if the ad was previously called using the OneCall call type

Options

This table provides an overview of the options available for sas.refresh:

Option Type Default Value Description
forceMasterFlag boolean false Forces the master flag; the master flag is used for page view counting; if the master flag is true, the ad call returns an ad (as usual) and the ad call is logged as a page view (page impression); ad calls with the master flag "true" will be reported as page views in Smart AdServer's reports
resetTimestamp boolean true resets the timestamp; timestamps are used for features such as links (displaying ads from insertions always together on a page) or exclusions (never display ads from certain insertions together on a page)
target string undefined updates the target criteria for the specified format; for more on the target parameter, see above

Keep in mind, that the sas.refresh method is only supported for ads which have been rendered asynchronously. Calling sas.refresh for ads which have been called synchronously will have no effect (will be ignored). If you call sas.refresh without specifying any formatId, only the ads which have been rendered asynchronously will be refreshed.

Target

You can alter the target criteria of a specified format. The following rules apply:

  • If the target option is unspecified (value undefined), the original target will not be altered
  • If the target option is set to an empty string (""), the target will be cleared
  • If the target option is set to a non-empty string, the specified string will become the new target

Callbacks

When using asynchronous tagging, you can make use of these callbacks:

  • the onLoad callback is called after an asynchronous call has been successfully performed
  • the onError callback is called in case an error occured during the call
  • the onClean(formatId, element) callback is called before cleaning the placement
  • the beforeRender(data) callback is called before the format rendering (sas.render)

onLoad could be used to execute javascript in case of empty ad responses (noad). However, the onNoad(data) callback function is the recommended method for this purpose (read above: Managing empty ad responses (noad)).

Examples

Example 1

// refresh the formatId 12345
sas.refresh(12345);

// refresh the formatId 12345 and force master flag
sas.refresh(12345, { forceMasterFlag: true });
 
// refresh all formats
sas.refresh();

// refresh all formats and force master flag
sas.refresh({ forceMasterFlag: true });

The example above refreshes formats and forces the master flag

 Example 2

// refresh all formats and clear the target
sas.refresh({ target: "" });

// refresh all formats and update the target
sas.refresh({ target: "age=42" });
 
// refresh the formatId 12345 and update its target
sas.refresh(12345, { target: "gender=m" });

// refresh the formatId 12345, update its target, and force master flag
sas.refresh(12345, { target: "country=uk", forceMasterFlag: true });

The example above refreshes the formats and alters the target.

Was this article helpful?
0 out of 0 found this helpful
Powered by Zendesk