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

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

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 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

V. Data Model Discussion

 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)
);

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 User Pages

VII. API

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

The Developer API

The User Interface

IX. Configuration/Parameters

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

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

XI. Future Changes

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