Ad Server Module Design

I. Essentials

Sitewide Administration Directory: /www/admin/adserver/
TCL Scripts: /tcl/adserver-defs.tcl
Requirements Document: /www/arsdigita/doc/requirements/adserver.html
Data Model: /www/arsdigita/doc/sql/adserver.sql
ER Diagram: /arsdigita/doc/er-diagrams/small_adserver_er

II. Introduction

The Ad Server module provides a system for Web site administrators to add banner ads to their Web pages. To do this, the software provides two key features: an administrator interface and a developer API. Through the administrator interface, Web publishers may add, configure, and group various banners that they receive from advertisers.

Developers use the API to add programmatically banner ads to individual pages. Once an administrator has added ads to his system and developers have programmed the pages to display the banners, users may visit the publisher's site and see banner ads on the appropriate pages.

III. Historical Considerations

Back in 1995, banner ads were the cornerstone of Internet entrepreneurs' dreams. Now people recognize them for what they are: mostly an annoyance. So why do we include an ad server in the ArsDigita Community System? Is it because it is too painful to watch publishers shell out $50,000 for packaged junkware ad servers that don't work? No. It is because it is too painful to watch them spend another $750,000 on systems integration to be able to query ad server data in conjunction with data from the rest of their system.

The ArsDigita ad server module was designed originally not to just serve ads but to incorporate with the other core features of the ACS. By sharing a common users data model with the rest of the ACS, the ad server allows ACS-backed Web sites to deploy ads and track which users view them with relative ease. Providing a functional ad system that easily (and without cost) integrates into an ACS-derived Web site was perhaps the driving principal behind the ad server module's design.

IV. Design Tradeoffs

User Tracking

The ad server tracks ads on which a user has previously clicked. This helps the ad server do things like compute the probability that User X will click on a health care product ad. But, the module focuses its detailed tracking efforts on registered users.

The ad server module records all clickthroughs for an ad. But, for each clickthrough, it only records which user clicked the ad if that user is a registered user. The main advantage for such a design is that the ad server does not have to identify every unique visitor to a site in order to guess at what ads to server. This prevents the ad server's code from becoming unwieldy and protects its performance from becoming too slow.

The logic behind this design is that a casual user will not have clicked enough ads or given any information providing the ad server with meaningful data about what ad the user might find interesting. Registered users, on the other hand, are presumably active users. They will much more likely have provided useful data for the ad server to offer individually-targeted ads.

The main disadvantage of only tracking which registered users clicked an ad is that Web sites whose main traffic comes from unregistered users will not be able to take advantage of historical user interests when serving ads. This tradeoff, though, does not seem too consequential. First of all, as previously mentioned, unregistered users probably have not provided much useful information. Furthermore, there are more effective ways to serve targeted ads to unregistered users. Key search words or the content of a Web page, for example, can clue the ad server as to what ads to serve.

Ad Keys

The database table which stores the ads, advs, uses an administrator-supplied varchar(200) for a primary key. This breaks with the ACS tradition of using sequence-generated integers as primary keys. The main reason for doing this is that using an administrator-defined, character-based key allows the ad server to integrate more easily with third-party ad products and services.

V. Data Model Discussion

The ad server data model consists of two main database tables and some auxiliary tables to help serve targeted ads. The two core tables are:

 create table advs (
	adv_key		varchar(200) primary key,
	adv_filename	varchar(200),
	target_url	varchar(500)
);

create table adv_log (
	adv_key		varchar(200) not null references advs,	
	entry_date	date,
	display_count	integer default 0,
	click_count	integer default 0,
	unique(adv_key,entry_date)
);

The advs table keeps a list of banner GIF files and the URLs to which users who click on them should be redirected. The adv_log table counts the number of times a day that ads were displayed and clicked on.

Two auxiliary tables help Web publishers serve ads in ad groups:


-- this is for publishers who want to rotate ads within a group

create table adv_groups (
	group_key	varchar(30) not null primary key,
	pretty_name	varchar(50)
);

-- these will rotate in the order spec'd (ascending, e.g., 0, 1, 2...) 
-- unless rotation_order is always NULL or is the same integer
-- in which case the order will be determined by however Oracle feels like
-- giving us the rows

create table adv_group_map (
	group_key	not null references adv_groups,
	adv_key		not null references advs,
	rotation_order	integer,
	primary key (group_key,adv_key)
);

A Web page can reference an ad group and display ads from that group in sequence. To do this, it can call ad_get_ad_html with group_key as an argument, and it will get back a reference to the next appropriate ad from that group.

The remainder of the data model consists mainly of tables to help Web publishers serve targeted ads. The tables map key words, categories, and users so that a Web page might serve an ad based upon particular content.

-- for publishers who want to get fancy

create table adv_user_map (
	user_id         not null references users,
	adv_key         not null references advs,
	event_time      date not null,
	-- will generally be 'd' (displayed) 'c' (clicked through)
	event_type      char(1)
);

create index adv_user_map_idx on adv_user_map(user_id);

-- for publishers who want to get really fancy 

create table adv_categories (
	adv_key         not null references advs,
	category_id     integer not null references categories,
	unique(adv_key, category_id)
);

-- for publishers who want to get extremely fancy

create table adv_keyword_map (
	adv_key		varchar(200),
	keyword		varchar(50),
	unique(adv_key, keyword)
);

Entity-Relationship Diagram

VI. Legal Transactions

The Administration Pages

The administrator may add, edit, and delete ads--changing advs. The administrator may add, edit, and delete ad groups--chaniging adv_groups. The administrator may add or remove ads from ad groups, changing adv_group_map.

The User Pages

When a Web page serves an ad, it increments the adv_log table to show that it has served an ad and notes when it served the banner. If a user clicks on an ad, the click_count in adv_log increments. If the user is a registered user, the adv_user_map table records which ads he has seen and which ads on which he has clicked.

VII. API

The ad server module exports a single scripting (TCL) procedure that returns the html for an appropriate ad to show.

adserver_get_ad_html {group_key {extra_img_tags ""}}: returns html for an ad to show. Right now, all we can really do is pick the ad in the specified group with the least exposure so far

VIII. User Interface

The Administrator Interface

From the administration pages, the administrator may add, edit, and delete ads. The administrator may add, edit, and delete ad groups. The administrator may also add or remove ads from ad groups. Finally, he can examine detailed viewing and serving statistics for ads and ad groups.

The Developer API

The developer will add a call to adserver_get_ad_html to pages on which he wishes to place banner ads.

The User Interface

Users simply view ads on Web pages, clicking on ads as they see fit.

IX. Configuration/Parameters

The ad server module stores the following configurable parameters in the ACS ini file under the section, [ns/server/acs-dev/acs/adserver]:

PartialUrlStub: the location of the adserver .tcl pages in the file system(typically /adserver/); note the trailing slash; also note that this isn't where ads go

DefaultTargetUrl: default target url for an ad if an ad does not specify a valid target.

DetailedPerUserLoggingP: should the system track detailed ad viewing and serving information for registered users.

X. Acceptance Tests

You should test that you can insert and view ads.
Suggested Method:

Add an ad in the admin pages
View the ad in the user pages

XI. Future Changes

Presently, the ad server data model supports more functionality than the API provides. For example, adserver_get_ad_html can only pick ads with the least exposure so far, even though the data model provides for other rotation methods, like random or keyword. A future release should include support for these other rotation methods.

Also, the ad server does not provide an interface for defining ad categories or key words. In the future, it should do so.

X. Authors

System creator: Philip Greenspun
System owner: Philip Greenspun
Documentation Author: Bryan Che

bryanche@arsdigita.com