53291 - Creating Ad Requests for the SAS Intelligent Advertising for Publishers Ad Server

Usage Note 53291: Creating Ad Requests for the SAS Intelligent Advertising for Publishers Ad Server

Web Server Ad Call Directives

As a special-purpose web server, the SAS Intelligent Advertiser for Publishers ad server responds to HTTP requests from any browser. It uses path information to determine which creative to serve. The method in this path contains the directive that tells the server how to return the creative, as in the following example:



http://crtl.aimatch.com/{custid}/hserver/site=A/size=728x90

In this case, the directive /hserver/ tells the application to select an ad that is appropriate for delivery to site A and is sized 728 by 90, wrap it in an HTML tag, and return it to the browser as a complete HTML page. There are multiple middle-ware server directives that you can use to develop ad calls that are appropriate for your service model.

Ad Tag Parameters

custid is a unique string used to identify each SAS Intelligent Advertising for Publishers customer. The specific custid value to be used for your implementation of the SAS Intelligent Advertising for Publishers ad tag is provided by the SAS Implementation Manager.

The following ad call parameters are key-value pairs that the engine uses to select ads:

site specifes an available site value for targeting. Ads can respond to a call that contain the specified site name if they have been targeted to that site or if there is no site value specified.

area passes in the area value for targeting.

size specifies an available ad size value for targeting.

custom tag name can be included in your ad calls for logging or targeting if you have created custom tags and associated values. Pass in the exact tag name and value. For example, if you have designated a tag called "position" that has three values (top, middle and bottom), the ad tag might contain /position=top/.

viewid notifies the system about which ad requests belong together. The number specified as the viewid must be the same for each ad call in a group, which identifies a set of ad calls as existing on one page of a web site. Also, the number must be unique to that service of the group (or page). This is typically accomplished dynamically, using Javascript. There are no restrictions on the types of characters that comprise a viewed value.

There are exceptions to using viewid in this manner. One exception, for example, is when the publisher wants to suppress duplicate flight and advertiser settings in tiers or to suppress the use of categories.

Example:


http://crtl.aimatch.com/{custid}/hserver/site=x/area=y/viewid=438943894343/size=728x90/pos=top/

random prevents the caching of creatives, especially to third-party servers. Preventing caching is done to maximize impression counts (rather than using a cached version of the ad from the browser or a proxy server). Any value passed in with the random ad call parameter is also used to populate the %%RANDOM%% token within ads that contain it.

It is recommended that each ad call on a page have a unique random value. If two or more ad calls on the page have the same targeting values and random values, the first ad delivered for rendering could be cached in the other ad call positions. In addition, the random value should be a different value for each page or page refresh. This is typically done dynamically using Javascript. There are no restrictions on the types of characters that comprise a random value.

Example:


http://crtl.aimatch.com/{custid}/hserver/site=x/area=y/size=728x90/pos=top/random=345678/

act=1

This ad call parameter denotes a beacon count URL.

Example:


http://crtl.aimatch.com/{custid}/count/act=1/fcid=57/site=x/area=y

act=2

This ad call parameter denotes a click count URL.

act=3

This ad call parameter denotes a generic action count URL.

For more information about these ad call parameters, see SAS Note 53313.

Considerations for Developing an Ad Call

Choosing the best ad call for your situation depends on the targeting schema that you have created, the nature of your web pages, and the creative you are serving to the pages.

Consider these factors before choosing an ad call:

Caching and Cache Busting

Web browsers often save a local copy of files that they have requested and displayed in order to display them more quickly the next time it is requested.(The saved version is used instead of re-requesting the file from its server.) Some Internet Service Providers (ISPs), network proxy servers, or other network components might use the same process. The process is known as caching and it is normally a positive enhancement to the web-browsing experience.

When an online advertisement is cached and then viewed, the ad server is not able to count the impression. To prevent this problem, each instance of a given ad call should contain a unique random number. The unique number causes the browser or proxy server to see it as a unique object and therefore makes a fresh request for it from the ad server. The result is proper impression counts and revenue allocation. This process is known as "cache-busting", and there are several ways to effectively implement it.

Note: It is very important that cache-busting techniques be used properly.

Cache-Busting Techniques

SAS Intelligent Advertising for Publishers uses a specific ad call parameter designed to receive the random cache-busting number (/random=), although any unique variation in the ad-tag string can provide effective cache busting. The advantage of using the /random= parameter is that it can be referenced in several ways by objects that are downstream from the ad request.

The parameter can be used to provide cache busting within the source code of rich media or third-party advertisements without a separate, unique-number generation process. The random number can be generated by a server-side process and dynamically inserted into the ad call, or it can be generated using a client-side script that generates the entire ad call dynamically. Caching can lead to major discrepancies between SAS Intelligent Advertising for Publishers counts and those of third-party ad servers or site publishers.

Using the /viewid= tag

The /viewid= tag is required if you are going to use companion ads (also called roadblock ads). As described in the Ad Tag Parameters section, using the same viewid value in a set of ad calls enables the system to treat the set of ad calls as a single page.

Maximum Request Length

The SAS Intelligent Advertising for Publishers system truncates requests in the path information string of any type that are longer than 2048 characters. The query string portion of the URL (after the question mark (?)) can also be up to 2048 characters.

Ad Call Methods

iserver

returns a 302 RELOCATE response and the image source URL. This call is designed to be served to the SRC attribute of the <img src> tag. Example:


<img src="http://crtl.aimatch.com/{custid}/iserver/site=x/area=y/viewid=438943/random=948576789/size=728x90" width=728 height=90 border=0>

hserver

returns the text source of a creative with the tokens replaced as defined in SAS Intelligent Advertising for Publishers. This call is designed to be served to the SRC attribute of the <iframe> tag. Example:


<iframe src="http://crtl.aimatch.com/{custid}/hserver/site=x/area=y/viewid=438943/random=1827473656/size=728x90">

jserver

returns JavaScript that dynamically writes the advertisement into the web page that called it. This call is designed to be served to the SRC attribute of the <script> tag. Example:


<script src="http://crtl.aimatch.com/{custid}/jserver/site=x/area=y/viewid=438943/random=102958674/size=728x90">

bserver

is a special-purpose ad call that returns a bundle of advertisements with a single call. The system parses out the ad call parameters for each ad in the bundle, and then returns JavaScript code that contains the HTML code necessary for all of the ads. This code presents the ads as a group of numbered JavaScript variable strings. Example:


<script src="http://crtl.aimatch.com/{custid}/bserver/ball/site=x/area=y/viewid=43892143/random=09874756/b1/size=728x90/b2/size=728x90">

Incrementing count directives The following example increments the count for flight creative id 57 (fcid=57) and relocates to the click destination specified for that creative:


http://crtl.aimatch.com/{custid}/adclick/fcid=57/site=x/area=y

This example increments the click count for flight creative id 57 but does not relocate to the click destination:


http://crtl.aimatch.com/{custid}/count/act=2/fcid=57/site=x/area=y

Building an Ad Call Using Client-Side Javascript

Because modern browsers ordinarily parse Javascript, you can create dynamic ad calls on the page for each of the methods described in "Ad Call Methods." All examples here are shown using client-side Javascript for building the ad call dynamically. Comparable ad calls can be created using server-side dynamic solutions such as ASP, ColdFusion, PHP, and so on.

iserver

The iserver ad call method is used to return a 302 RELOCATE response and a relocation URL to an "<img src=>" element on the page. This ad call is often used in e-mail newsletters as most e-mail readers do not accept the hserver | jserver | bserver methods.

Strengths

simplicity
enables ad delivery into e-mail newsletters

Weaknesses

Does not support rich media creatives; supports static image creatives only.
Does not allow the insertion of a unique identification number for tyhe creative ("FCID"). The FCID positively correlates clicks into the "<a href=>" URL at any time after the creative has been served. Omitting an FCID can result in incorrect click-throughs. E-mail newsletter content management systems typically allow the use of variable tokens such that a unique mid value can be placed in the <img src=> and <a href=> URLs. (See example below.)

iserver Example

Notes:

Replace {path to your adserver} with the correct adserver domain URL, including your specific {clientid} value.
Replace {ad call targeting} with the correct targeting parameters for each ad instance.
Replace the width= and height= values with the correct sizes.


<a href="http://{path to your adserver}/{custid}/adclick/{ad call targeting}">
<img src="http://{path to your adserver}/{custid}/iserver/{ad call targeting}" width={width} height={height} border=0>

iserver Example for E-mails

Notes:

To avoid encoding issues with some e-mail readers, insert the targeting values in the querystring using an ampersand ("&") as the delimiter between each key=value pair.

The publisher’s content management system that generates the e-mail will need to generate two sets of values in order for SAS Intelligent Advertising for Publishers to accurately pair the ad image with the click-through. These values are mid={value} and pid={value}.

For multiple ad calls in each newsletter, the mid value should remain the same for all ad calls, and the pid value should be unique for each set of <a href> and <img src> tags.

Add hint=x to the targeting string to avoid possible issues with intra-session routing to the ad server.

See this forum article for information about e-mail ad calls: Serving Ads to E-mails and Newsletters.


<a href="http://{path to your adserver}/{custid}/adclick?hint=x&site=x&area=y&size=728x90&mid=1234&pid=5678">
<img src="http://{path to your adserver}/{custid}/iserver?hint=x&site=x&area=y&size=728x90&mid=1234&pid=5678" width={width} height={height} border=0>
</a>

hserver

The hserver ad call method is used to return content to an <iframe src> element on the page. The iframe is defined in the parent document, but is told to reference SAS Intelligent Advertising for Publishers (with the appropriate ad call parameters) for its content. The system returns the advertisement as a complete document.

Strengths

Enables the insertion of rich media (file-based advertisements).
Not likely to delay the rendering of the page content because modern browsers usually render iframes asynchronously.
Enables the insertion of a unique identification number (FCID) that positively correlates clicks at any time after the creative has been served. There is no expiration on click functionality.
Supports all creatives that can function in the browser.

Weaknesses

Does not support creatives that resize themselves or modify their position on the page without additional coding on the page.
Can cause issues with creative that are designed to open in the parent page and not as a new document.

hserver Example

Notes:

Replace {path to your adserver} with the correct adserver domain URL, including your specific {clientid} value.
Replace {ad call targeting} with the correct targeting parameters for each ad instance.
Replace the iframe width= and height= values with the correct sizes.
If you are using Minify Javascript remove all HTML comments beginning with <!—.
Creative content URLs which are protocol-agnostic (meaning the URL begins with "//" rather than "http:" or "https:") will not render as the URL after the "//" will be treated as a comment by the browser's JavaScript parser. Prefacing "//" with the %HTTP% token will prepend the ad request URL's protocol, whether it's "http:" or "https:".


<script type="text/javascript"  language="JavaScript">

<!-- Hide from old browsers

// Modify to reflect site specifics

adserver = "http://{path to your adserver}";

target = "/{ad call targeting}";



// Cache-busting and viewid values

random = Math.round(Math.random() * 100000000);

if (!pageNum) var pageNum = Math.round(Math.random() * 100000000);



document.write('<iframe src="'+adserver+'/hserver/random='+random + target + '/viewid=' + pageNum + '"');

document.write(' noresize scrolling=no hspace=0 vspace=0 frameborder=0 marginheight=0 marginwidth=0 width ={width} height={height} allowTransparency="true">');

document.write('</iframe>');


// End Hide -->

</script>

jserver

The jserver ad call method is used to return content to a <script src> element on the page. The <script src> ad call with is made and the system returns the selected ad wrapped in JavaScript, which is then written dynamically into the page and parsed.

Strengths

Enables the insertion of rich media (file-based advertisements).
Enables the insertion of a unique identification number (FCID) that positively correlates clicks at any time after the creative has been served. There is no expiration on click functionality.
Supports all creatives that can function in the browser.

Weaknesses

Javascript could delay the rendering of the rest of the content if the response of the ad server is degraded.
Poorly written or malformed advertisements might interfere with or (in extreme cases) break page content.

jserver Example

Notes:

Replace {path to your adserver} with the correct adserver domain URL, including your specific {clientid} value.
Replace {ad call targeting} with the correct targeting parameters for each ad instance.
Replace the iframe width= and height= values with the correct sizes.
If you are using Minify Javascript remove all HTML comments beginning with <!—.
Creative content URLs which are protocol-agnostic (meaning the URL begins with "//" rather than "http:" or "https:") will not render as the URL after the "//" will be treated as a comment by the browser's JavaScript parser. Prefacing "//" with the %HTTP% token will prepend the ad request URL's protocol, whether it's "http:" or "https:" so that the URL will be properly parsed.
The jserver method wraps each line of code with document.write() or document.writeln(). If required, this can be suppressed for one or more lines of the creative's code by wrapping the statements with ' {code} '.


<script type="text/javascript"  language="JavaScript">

<!-- Hide from old browsers

// Modify to reflect site specifics

adserver = "http://{path to your adserver}";

target = "/{ad call targeting}";



// Cache-busting and viewid values

random = Math.round(Math.random() * 100000000);

if (!pageNum) var pageNum = Math.round(Math.random() * 100000000);



document.write('<scr');
document.write('ipt src="' + adserver + '/jserver/random=' + random + target + "/viewid=" + pageNum + '">');

document.write('</scr');

document.write('ipt>');


// End Hide -->

</script>

bserver

The bserver ad call is the most efficient ad call. It has the smallest code footprint for multiple ad calls on a page and requires only one request to the system to get all ad content for the page. The single request aspect of the ad call also eliminates a "race condition" that can occur when multiple ad calls are made from the page simultaneously. A race condition can impair companion ad serving or sequential ad delivery.

The ad call construction shown below is required on the page only once, although you can use multiple bserver calls if you want to use multiple viewid values on a single page. The ad-rendering code for each ad (also shown below) is inserted at each ad position on the page.

Strengths

Most efficient method of delivering multiple ads to a page.
Enables the insertion of rich media (file-based advertisements).
Enables the insertion of a unique identification number (FCID) The FCID positively correlates clicks at any time after the creative has been served, so there is no expiration on click functionality.
Prevents a race condition from occurring.

Weaknesses

Javascript could delay the rendering of the rest of the content if the response of the adserver is degraded.

Poorly written or malformed advertisement code might interfere with or (in extreme cases) break page content.

bserver Example

Notes:

Replace {path to your adserver} with the correct adserver domain URL, including your specific {clientid} value.
Replace {ad call targeting} with the correct targeting parameters for each ad instance.
If you are using Minify Javascript, remove all HTML comments that begin with <!—.
Creative content URLs which are protocol-agnostic (meaning the URL begins with "//" rather than "http:" or "https:") will not render as the URL after the "//" will be treated as a comment by the browser's JavaScript parser. Prefacing "//" with the %HTTP% token will prepend the ad request URL's protocol, whether it's "http:" or "https:" so that the URL will be properly parsed.
Add the adx Javascript variable and its accompanying /bx/ string for each ad instance on the page, replacing the x with an incremented number.
For each adx variable created, add an adx + string in the section of Javascript, which builds the script src bserver ad call (shown below).
Edit the rendering code to replace x with the correct /bx/ value that was referenced in the ad call.
Note:The initial value of x cannot be zero (0).
The resulting bserver URL pathinfo (the ad call request itself, not the Javascript used to create it) cannot exceed 2048 characters.
/ball/ strings are appended to each /bx/ ad request section of the bserver URL, which gives you the ability to insert global ad call data into each ad request while defining it only once.
Typically, this would be used for random and viewed values, but it can also include targeting tags (for example, if all ad calls on the page use the same SITE and AREA values). The /ball/ string should appear after bserver in the ad call, but before any /bx/ strings. If the ad call is not set up correctly, the system will not fail, but it might include extraneous strings in the ad requests.
If the number of document.writeln(bx) calls on the page do not match the number of /bx/ ads defined in the bserver script src call, the impressions are logged (even though the ads are not rendered). Make sure that the bx() calls match the /bx/ ads defined in the bserver script src call.
You can add multiple bserver calls can on a page but do not duplicate /bx/ values between the calls.
Because the /ball/ string contains a /random= value that is appended to each /bx/ ad request, multiple ad requests to the same third party ad server within the same bserver ad call will contain identical /random= cache-busting values. The identical values might affect the third party ad server’s impression counts. One alternative is to use multiple bserver ad calls on the page.
The ad call below uses the aimRnd variable value for both the /random= and /viewid= values.
Rich media file-based ads should be stripped of all comment strings.
There are known issues with Google ads when multiple Google ads are served to the same bserver call. Test the multiple Google ads with the bserver ad call in a test campaign and test environment before going live.




<head>
<script language="javascript" type="text/javascript"
>
<!--

var b1 = "";

var b2 = "";

var b3 = "";

var b4 = "";

//-->

</script>

<head>


<body>

<script type="text/javascript" language="Javascript">

<!-- Hide from old browsers

// Cache-busting and viewid value

var aimRnd = Math.round(Math.random() * 100000000);


// adserver URL

adserver = "http://{path to your adserver}/bserver";
 

// Ad tag targeting values which will be appended to each ad request section in the bserver ad call

allAdTags = "/ball/random=" + aimRnd + "/viewid=" + aimRnd;


// Individual tags for each ad request  - increment the adx variable name and the ‘/bx/’ parameter.

ad1 = "/b1/{ad call targeting}";

ad2 = "/b2/{ad call targeting}";

ad3 = "/b3/{ad call targeting}";

ad4 = "/b4/{ad call targeting}";

// bserver ad call – insert the adx variables document.write('<scr' + 'ipt src="' + adserver + allAdTags + ad1 + ad2 + ad3 + ad4 + '?" type="text/JavaScript" language="JavaScript">'); document.write('</scr' + 'ipt>'); // End Hide --> </script>

At the Ad Locations -- insert the following Javascript (edit “bx” to reference the appropriate ad by number):



<script type="text/javascript" language="JavaScript">

document.writeln(bx);

Operating System and Release Information

Product Family	Product	System	SAS Release
			Reported	Fixed*
SAS System	SAS Intelligent Advertising for Publishers	N/A

* For software releases that are not yet generally available, the Fixed Release is the software release in which the problem is planned to be fixed.

Date Modified:	2016-09-06 10:13:38
Date Created:	2014-06-24 13:27:20

Type:	Usage Note
Priority:

Support

Usage Note 53291: Creating Ad Requests for the SAS Intelligent Advertising for Publishers Ad Server

Web Server Ad Call Directives

Ad Tag Parameters

Considerations for Developing an Ad Call

Ad Call Methods

iserver

hserver

jserver

bserver

Building an Ad Call Using Client-Side Javascript

iserver

hserver

jserver

bserver

Operating System and Release Information