• Ad Selection Phase
• Content Delivery Phase
• Statistics Recording Phase

What is ad.pl, ad delivery and redirection engine?

In DynAds software, ads/contents are defined and managed via admin web interface, dynadmin.pl. The script ad.pl (delivery engine), on the other hand, is for delivering the ads/contents to web pages, doing url redirection, and keeping view and click statistics. Most of the time, the html access codes generated by the code generator of the admin panel, dynadmin.pl, will be used to access the ads/contents. In those cases, a user only cuts and pastes the generated html code to his/her web page to access the delivery engine services. Users need not know how the delivery engine works. However, the delivery engine provides some features that are not covered by dynadmin code generator. In addition, for advance usage or for trouble shooting, the interface and behavior of the delivery engine must be known.

The delivery engine receives commands from the query string (http GET or http POST) and from cookies for some cases. Although, POST requests can be used, there is no apparent reason to prefer them to the GET requests. The response of the delivery engine varies depending on the request. In general, for ad delivery requests, the engine retrieves the requested ads, sets some statistics, and transfers them to the requested browser in the requested format. In addition, some cookies could be set to the browser, depending on the request. For redirection requests, engine retrieves the url, sets some statistics and redirects the browser to the retrieved url. Another mode of operation of the delivery engine, is the statistics only use. The delivery engine updates the view or click statistics of given ad or link upon request.

Before explaining the commands of the delivery engine in detail, here are some example access codes for different cases:

<IFRAME NAME="TextAds1" FRAMEBORDER="0" SCROLLING="No" 
SRC="http://YourDomain/YourPath/ad.pl?pos=TopLeft&agn=TextAds1&dsp=frm&sel=rnd&rp=60" >
</iframe> 

<SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript" 
SRC="http://YourDomain/YourPath/ad.pl?pos=BotCent&agn=TextAds1&dsp=js&sel=seq&dir=f">
</script>

<A HREF="http://YourDomain/YourPath/ad.pl?pos=Page2&c=FirstCat&ad=ThirdLink&md=re">
Click to go to the page </a>

<IMG BORDER="0" WIDTH="1" HEIGHT="1" 
SRC="http://YourDomain/YourPath/ad.pl?pos=MainPage&c=Cat2&ad=IntAd1&md=cn&typ=v">

<SCRIPT LANGUAGE="Javascript" TYPE="text/javascript"
  SRC="http://YourDomain/YourPath/ad.pl?md=api">
</script>

Setting the Mode of Operation

The mode of operation is selected by the query string parameter named 'md' (short for mode) as shown below.

Content Retrieval Mode

Content retrieval mode is selected by setting the mode selection parameter 'md' to 'ad', or simply not specifying it.

Content retrieval mode can be divided into three phases: ad selection phase, content delivery phase, and statistics recording phase. In the selection phase, an ad or list of ads are selected from the specified ad group, with the specified selection method. In the delivery phase, the contents of the selected ads are formatted to make them compatible with the access method of the ads and they are delivered to the requesting item. In the statistics phase, if enabled, view records are added to the statistics database of the selected ads.

Ad Selection Phase

Ad selection parameters determine from which ad group and how the ads are selected. The parameters are summarized in the table below.

Specifying the ad group name is essential. Only the ads referenced in the specified ad group are considered for selection. Furthermore, an ad must be in enabled state to be selected. Disabled ads are excluded from the selection list. A default ad, specified in the ad-setting.pl file, is selected if no ad group is specified, or if the specified ad group is not found, or if all of the ads in the specified ad group are disabled. For such cases, a broken link view record is saved in the BrokenLinks database no matter the value of 'nos' parameter.

After an ad is selected, that category and ad are checked for automatic disabling. If it is specified in the database, category and ad are check against the time, or the number of views for disabling. Any ad or ads of a category disable automatically will not be considered for selection again until they are enabled.

Random Ad Selection Scheme

Random ad selection scheme requires no other parameters. In this case, the active ads of the ad group are listed and one of them is selected in proportion to the assigned weights. If the weight of the ads are equal, then the selection is done uniformly. Otherwise, the ad having bigger weight value will be selected more frequently proportional to its weight relative to others.

Sequential Ad Selection Scheme

In this scheme, a visitor will be not be shown the same ad again until all of the ads in the ad group are shown. This is done by setting a cookie in the users browser with a life time of default one month. Cookie duration can be set in the ad-settings.pl file. That means that if a visitor returns back to the page in that duration after the first visit, the next ad in the list will be shown. In addition, more than one sequential ad displays on a single page can be shown independent of each other.

Sequential ad access does not need cookies for a special, and very useful case. When displaying ads in a html container (ie. windows, frames, inline frames) with auto-refresh property (see ad delivery phase below) enabled, then no cookies are needed to rotate ads on the browser. This is very useful to rotate banners without refreshing the browser

Sequential ad selection requires these extra parameters to be specified.

Parameter Name	Parameter code	Value(s)	Notes
Direction	dir	f or b	The direction of the sequence: Forward (f) or Backward (b). If not specified, direction is obtained from cookie. If the cookie is not defined, forward sequence is assumed.
Ad No	ano	Index of the ad that must be selected	'ano' specifies which ad to select in the ad group. Index of the first ad is 0 (zero). If it is not specified in the query string, the index of the last ad shown to the visitor is retrieved from cookie, and it is incremented (decremented) for forward (backward) sequence to find the index of the ad to select. All increment and decrement operations are performed circularly. If the list is completed then the index returns to the beginning. If a cookie is not found, then the value of 'init' parameter determines which ad to select.
Initial Ad No	init	Undefined or Index of the Ad desired for the first delivery	'init' parameter determines which ad to select when both 'ano' parameter and a cookie for the last selected ad are missing. If 'init is specified, then the ad at that index is selected. Otherwise, ad to select is determined by the random ad selection scheme. This is very useful property, because, if your visitors browser does not support cookies, then a random ad is displayed instead of the same ad if 'init' were defined (better than nothing).

After the selection of the ad, delivery engine sets a cookie to the visitors browser that contains the index of the ad selected and the direction of the sequence.

Examples

Select the first ad of ad group AdGrp1 (index starts from 0)

http://YourDomain/YourPath/ad.pl?agn=AdGrp1&sel=seq&ano=0

Select the next ad in forward direction from ad group AdGrp1. If cookie is not found select the first ad.

http://YourDomain/YourPath/ad.pl?agn=AdGrp1&sel=seq&dir=f&init=0

Select the next ad in backward direction from ad group AdGrp1. If cookie is not found select a random ad.

http://YourDomain/YourPath/ad.pl?agn=AdGrp1&sel=seq&dir=b

All Ad Selection Scheme

In this selection scheme, all of the enabled ads of the ad group are selected. When displaying, their content is appended to form a list of ads. The order of the ads, is the order of ads in the ad group.

This selection scheme is very useful for displaying list of contents such as to do lists, news headlines, or link lists.

Content Delivery Phase

After the ads to deliver are selected, delivery process starts. In this phase, the ad contents are put into the format of the requesting container.

Before delivering the ads, the Link field of the ad content is replaced by a redirection link pointing to the delivery engine. This automatic redirection makes it possible to track the click statistics of the ads.

The format and the method of delivery of the selected ads is specified by the delivery selection parameter 'dsp'. The table below shows the possible values of 'dsp':

(dsp=html) Untouched content delivery

In this case, the ad contents are delivered as it is, untouched. Therefore, this type of delivery must be requested when the bare content of the ad is needed. Some examples are SSI, ASP, PHP, and Perl.

In addition, most browsers can display html content even if they are not complete html documents with HTML, HEAD, and BODY tags. For this reason, WINDOW, FRAME, IFRAME and OBJECT can be used to access content in html delivery mode. However, if the ad contents are complete html documents, then the html mode must be used to access ads for WINDOW, FRAME, IFRAME and OBJECT, instead of frame (frm) mode. For these containers, an auto-refresh period can be specified through the parameter named 'rp'. If 'rp' is non-zero, then the container will refresh at every 'rp' seconds to load new content with the original parameters. The refresh is requested from the browser via HTTP request. The content is not modified in any way.

If accessed by SSI, ASP, Perl or PHP commands, and the selection scheme is sequential ad selection, user must be aware of the fact that these environments, in general, do not allow cookies to be set.

Examples

SSI or ASP call

<!--#include virtual="/YourPath/ad.pl?pos=UpLeft&agn=AdGrp1&dsp=html&sel=rnd"-->

PHP

<?php include("http://YourDomain/YourPath/ad.pl?pos=UpLeft&agn=AdGrp1&dsp=html&sel=rnd"); ?>

Link to open in new window to load ad contents with auto refresh period of 20 seconds

<A TARGET="_blank" 
HREF="http://YourDomain/YourPath/ad.pl?pos=NewWind&agn=AdGrp1&dsp=html&rp=20&sel=rnd">
Click here to load the ad </a> 

IFRAME with periodic refresh at every 10 seconds

<IFRAME NAME="UpLeft" FRAMEBORDER="0" SCROLLING="No" 
SRC="http://YourDomain/YourPath/ad.pl?pos=Pos1&agn=AdGrp1&dsp=html&rp=10&sel=rnd">
</iframe>

(dsp=frm) Frame content delivery

In this mode of content delivery, ad contents are encapsulated into HTML, HEAD and BODY tags so that they can be displayed in html containers safely. Margin of the BODY tag is set to zero to allow exact positioning.

An auto-refresh period can be specified through the parameter named 'rp'. If 'rp' is non-zero, then the container will refresh at every 'rp' seconds to load new content with the original parameters. The refresh is requested from the browser via META tag.

If sequential ad selection is used with auto-refresh on, then no cookies are needed. That means that banners can be rotated in an IFRAME on the fly, even if the cookies are disabled making it a very robust method of ad rotation.

Examples

Pop-up window with no auto refresh property.

<SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript">
<!--
var popupWin1 = 
    window.open("http://YourDomain/YourPath/ad.pl?pos=Win1&agn=AdGroup2&dsp=frm&sel=rnd&rp=0", 
                "popupWin1","SCROLLBARS=No") ;
//-->
</script>

Frame with 60 seconds refresh.

<FRAME NAME="UpLeft" FRAMEBORDER="0" SCROLLING="No" 
SRC="http://YourDomain/YourPath/ad.pl?pos=UpLeft&agn=AdGroup3&dsp=frm&sel=seq&dir=f&rp=60">

(dsp=img) Image content delivery

In this mode of delivery, only images can be displayed. The request is originated from an IMG or OBJECT tag. The delivery engine, extracts the source url of the last IMG tag in the ad content. The browser is redirected to this url to load the image. For this reason, if there are more than one image in a content, the last one must be the one you want to display via IMG tag. Use IMG tag delivery as the least prefered method of content delivery.

If 'all' selection scheme is requested, then only the image of the first ad is shown.

Examples

Image tag banner displaying. Note how the anchor link is configured.

<A HREF="http://YourDomain/YourPath/ad.pl?pos=BannerPos1&md=re&typ=img">
<IMG BORDER="0" WIDTH="480" HEIGHT="60"
SRC="http://YourDomain/YourPath/ad.pl?pos=BannerPos1&agn=Banners&dsp=img&sel=rnd">
</a>

(dsp=js) JavaScript content delivery

The contents of the selected ads are transfered to the requesting browser as JavaScript document.write statements. That means that, the ads are pasted to the document of the browser. Therefore, any html statement can be used as the content of ads.

After the paste of the ads, the ads will not be available for further post-processing. The ad is updated only when the page is reloaded

Examples

Load and display an ad

<SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript" 
SRC="http://YourDomain/YourPath/ad.pl?pos=MainUp&agn=ComplicatedAds&dsp=js&sel=rnd">
</script>

(dsp=ajs) JavaScript array content delivery

Examples

Load a randomly selected ad as a single element array. Then, display it with some formatting

<SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript" 
SRC="http://YourDomain/YourPath/ad.pl?pos=Pos2&agn=ComplicatedAds&dsp=ajs&sel=rnd">
</script>
<SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript" >
   document.write("<HR>" + Pos2[0] + "<HR>") ;
</script>

(dsp=djs) JavaScript DAG Class object content delivery

The contents of the ads are encapsulated into a DAG class object. The name of the object is the name of the display position name prepended by 'dag'. The content is loaded during the page load. Post processing is possible. The content can be displayed during the page load via a document.write or later via dhtml layer commands.

Examples

Load a randomly selected ad as a DAG class object. Then, display it.

<SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript" 
SRC="http://YourDomain/YourPath/ad.pl?pos=Pos2&agn=ComplicatedAds&asp=ajs&sel=rnd">
</script>
<SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript" >
   dagPos2.WriteContainer() ;
   dagPos2.PutAd(0) ;
</script>

(dsp=dim) Cookie content delivery

The contents of the selected ads are set as a cookie to the visitors browser. The browser is redirected to load an invisible, 1x1 image. The content can be accessed from the cookies. Post processing is possible. DAG API includes a method to retrieve the cookie content into a DAG class object. The content can be refreshed dynamically.

As a general rule of thumb, limit the size of the ad content to be loaded via cookies, be under 1 (one) KByte. Note that this size limitation is NOT for the size of the images or banners. But for the size of the html code to access them (IMG tags).

Examples

Select an ad randomly and loaded it via cookies.

<IMG BORDER="0" WIDTH="1" HEIGHT="1" 
SRC="http://YourDomain/YourPath/ad.pl?pos=CookiePos&agn=TextAds1&dsp=dim&sel=rnd">
<SCRIPT LANGUAGE="JavaScript" TYPE="text/javascript" >
// Retrieve the ads from the cookie
   dagCookiePos = new DAG("CookiePos") ;
   dagCookiePos.GetAdsFromCookie() ;
</script>

Statistics Recording Phase

After the ad delivery phase is completed, the view statistics of the selected ads are updated.

The parameters used in this phase are listed below.

DynAds saves the following information for each selected asd: The specified display position name, category name, name of the ad, time, IP address of the visitor, refering url, and event type as 'view'.

URL Redirection Mode

DynAds contains a redirection engine. The original links of the displayed ads are automatically replaced with a redirecting link while delivering the ads. Thus, a user normally does not need to know how to invoke the redirection engine.

However, for some applications, users need to generate redirecting links explicitly. For example, if a user wants to distribute redirecting links, he/she must generate the links explicitly

This mode is selected by setting the mode selection parameter 'md' to 're'. Other parameters are summarized below.

Upon receipt of the redirection request, redirection engine retrieves the original url of the given ad of the given category. The requesting browser is directed to this url.

However, if the ad or category is disabled or any of them is not found in the database, redirection is done to a default URL specified in the ad-setting.pl file. For such cases, a broken link click record is saved in the BrokenLinks database no matter the value of 'nos' parameter.

If 'nos' is not defined or defined as zero, a click record is logged for this ad/category and display position. Otherwise no further action is done. DynAds saves the following information for each redirection request: The specified display position name, category name, name of the ad, time, IP address of the visitor, refering url, and event type as 'click'.

After the redirection is done, that category and ad are checked for automatic disabling. If specified in the database, category and ad are check against the time, or the number of clicks for disabling.

Examples

<A HREF="http://YourDomain/YourPath/ad.pl?pos=BanPos1&md=re&typ=img">
<IMG SRC="http://YourDomain/YourPath/ad.pl?pos=BanPos1&agn=BanGrp&dsp=img&sel=rnd">
</a>

<A HREF="http://YourDomain/YourPath/ad.pl?pos=TxtPos1&md=re&c=Company2&an=Ad3">
Text content
</a>

Load DAG API Mode

This mode is selected by setting mode selection parameter 'md' to 'api'. No other parameter is used currently. Upon request, delivery engine submits the API content by using a two level hand-shaking protocol. Since the returned content is JavaScript, the requesting code must be a SCRIPT tag.

Example

<SCRIPT LANGUAGE="Javascript" TYPE="text/javascript"
  SRC="http://YourDomain/YourPath/ad.pl?md=api">
</script>

Direct Count Mode

There are times that users do not want DynAds to add a view or click record when the corresponding events occur. For example, consider a user loading all of the ads of a group to the browser at page load without displaying them immediately. User displays the ads interactively later using JavaScript. In this case, user does not want all of the loaded ads be marked as displayed, because some of the ads may never be displayed and some of them may be displayed more than once. The solution is to disable the view statistics while loading the ads. Then, user interactively sends direct count commands to the ad delivery engine via JavaScript codes at the time the ad is displayed.

This mode is selected by setting mode selection parameter 'md' to 'cn'. Other parameters are summarized below.

The direct count mode must be activated via an IMG tag. The image returned by the delivery engine is a small (1 pixel width and 1 pixel height) invisible image.

Examples

<IMG BORDER="0" WIDTH="1" HEIGHT="1" 
SRC="http://YourDomain/YourPath/ad.pl?md=cn&pos=MainPageTop&c=Cat2&ad=IntAd1&typ=v">

<IMG BORDER="0" WIDTH="1" HEIGHT="1" 
SRC="http://YourDomain/YourPath/ad.pl?md=cn&pos=MainPageTop&c=Cat2&ad=IntAd1&typ=c">

<IMG BORDER="0" WIDTH="1" HEIGHT="1" NAME="statImg" SRC="">
<SCRIPT LANGUAGE="Javascript" TYPE="text/javascript">
  function AddClickRecord() {
     document.statImg.src = "" ; 
     document.statImg.src = 
	    "http://YourDomain/YourPath/ad.pl?md=cn&pos=MainPageTop&c=Cat2&ad=IntAd1&typ=c" ;
  }
</script>