Ave Wrigley > WWW-AdManager-0.007 > WWW::AdManager

Download:
WWW-AdManager-0.007.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.007   Source  

NAME ^

WWW::AdManager - a perl module to administer and serve online advertising

SYNOPSIS ^

CGI

advert interface

    WWW::AdManager->new(
        INTERFACE           => 'ADVERT',
        ADMANAGER_URL       => "/admanager",
    )->output();

admin interface

    WWW::AdManager->new(
        INTERFACE           => 'ADMIN',
        ADMANAGER_URL       => "/admanager",
        ADMANAGER_ADMIN_URL => "/internal/admanager",
    )->output();

mod_perl

    <IfModule mod_perl.c>

    <Location /internal/admanager>
        SetHandler          perl-script
        PerlHandler         Apache::WWW::AdManager
        PerlSetVar          INTERFACE ADMIN
        PerlSetVar          ADMANAGER_URL /admanager
        PerlSetVar          ADMANAGER_ADMIN_URL /internal/admanager
    </Location>

    <Location /admanager>
        SetHandler          perl-script
        PerlHandler         Apache::WWW::AdManager
        PerlSetVar          INTERFACE ADVERT
        PerlSetVar          ADMANAGER_URL /admanager
    </Location>

</IfModule>

DESCRIPTION ^

WWW::AdManager is a module which implements a web advert management system. This is based around linked images, that are organized into "campaigns". Within each campaign, the admanager randomizes the display of images, and tracks both "page impressions" - i.e. the number of times the image is displayed - and "clickthroughs" - i.e. the number of times the image is clicked on.

The module also provides an administration web interface, which can be served through a access restricted URL, for creating and updating campaigns and adverts, and displaying usage stats.

The interface support implementation both through CGI and mod_perl. mod_perl is highly recommended, especially where there are more than one adver to display per page.

The insertion of adverts into pages is done using SSI (server side includes - see http://httpd.apache.org/docs/mod/mod_include.html, for example). The module does both logging of each relevant transaction (clickthrough / page impression) and live compilation of stats.

Campaigns can be sub-divided into sub-campaigns for more convenient organization of adverts.

CONSTRUCTOR ^

The constructor for the module takes a number of options (see OPTIONS) as a hash of arguments.

Apache::Registry HANDLER ^

WWW::Admanger offers a "handler" method that can be used in a mod_perl ennabled Apache web server (see http://perl.apache.org/). Various options can be specified using PerlSetVar directives (see SYNOPSIS). These options correspond to the CONSTRUCTOR options, and are listed in the OPTIONS section. The handler method simple creates a new WWW::AdManager object using these options, and calls the output method on this object.

OPTIONS ^

INTERFACE

This option deltermined which interface is displayed by the output method. This option is REQUIRED, and its value should be one of ADMIN or ADVERT. Basically, the ADMIN interface presents a user interface to configure the advertising campaigns. This should probably be offered through an access restricted URL. The ADVERT interface presents HTML code to include in a page which is hosing the advert.

ADMANAGER_URL

This is the URL that corresponds to the CGI / mod_perl interface through which the advert is served. This is used by WWW::Admanger to generate links (e.g. test links in the ADMIN interface, and clickthrough / page impression links in the ADVERT interface. This option is REQUIRED.

ADMANAGER_ADMIN_URL

This is the URL that corresponds to the CGI / mod_perl interface through which the administration interface is presented. This is used by WWW::Admanger to generate links to other views in the administration interface. It is a REQUIRED option if the INTERFACE option is set to ADMIN.

INSTALL_DIR

This option specified the default root directory for installing the various files (logging, stats, advert data) used by / produced by the application. It is an OPTIONAL option. The default is either $HOME/.admanager, if the $HOME environment is set, or $TMP/.admanager, where $TMP is the system temporary directory, as determined by the TempDir module.

ERR_DIR

The directory where application error logs are written. This is an OPTIONAL option, and defaults to INSTALL_DIR/err.

LOG_DIR

The directory where application user logs are written. There is a seperate log file per camapign. These logs are of the following format:

    $datestr:$n:$type:$url:$document_name:$remote_host

where:

$datestr

Date string returned by localtime.

$n

No. of the advert in the campaign.

$type

Either 'img' if this is a page impression, or 'ct' if this is a clickthrough.

$url

The URL corresponding to the image served / clickthrough redirected to.

$document_name

The document from which the advert was served (through SSI).

$remote_host

The remote host requesting the advert.

This is an OPTIONAL option, and defaults to INSTALL_DIR/log.

STATS_DIR

The directory where usage statistics files are written. This is an OPTIONAL option, and defaults to INSTALL_DIR/stats.

DATA_DIR

The directory where advert data files are saved (using Data::Dumper). This is an OPTIONAL option, and defaults to INSTALL_DIR/data.

REDIRECT_PAGE_IMPRESSIONS

If this option is set, page impression URLs (i.e. the SRC attribute of the IMG tag) are redirected through the admanager system. This helps to ensure that page impressions are properly logged. It is NOT recommended if the application is being served through CGI, as it is likely to seriously affext performance.

METHODS ^

output

This moethod is called to generate the appropriate output for the INTERFACE created. It does the "right thing" depending on whether the application is called through CGI or mod_perl.

ADMINISTRATION WEB INTERFACE ^

Campaign

This section shows a list of links to all the current campaigns, plus a form input to create a new campaign. On creation and selection of a campaign, you should see ...

Sub-Campaigns of $campaign

This section shows a list of links all the sub-campaigns of the currently selected campaign (if any) plus a form input to create a new sub-campaign.

Current Campaign ($campaign_path)

This section shows details of the current campaign / sub-campaign. This includes:

a link to "Add a new advert"

This links to a form which can be used to enter the details of a new advert for the current campaign (Image URL, Alt. Text, Clickthrough URL, and whether the advert is to be opened in a new window).

a link to "View the usage log"

This link display the text of the usage log for the current campaign. See the LOG section for details of the log format.

a link to "Test the campaign"

This link launches a new window with can be used to preview the current campaign. Reloading the window should demonstrate the advert rotation.

a link to "Delete the campaign"

This link is used to delete all information about the current campaign. It throws us a javascript confirmation box, just in case!

Adverts

This section contains a table with details of all the adverts in the current campaign. It includes links to edit / delete individual adverts, and to change advert attributes for the whole campaign (the no. of ads to display simultaneously, the image margin in pixels). It also includes reports on the usage stats (page impressions / clickthroughs) for each advert in the campaign.

The "Log usage" attribute determines whether ad usage (page impressions / clickthroughs are logged, and stats accumulated). The default for this is "Yes" for a new campaign.

The "No. of ads to display" attribute allows campaigns with multiple images to be displayed simultaneously (side-by-side). The number of ads displayed >= the number of ads in the campaign, and the displayed images are randomised over the available "slots".

The "Image margin" attribute determines the margin around adverts. This is implemented using a margin stylesheet attribute on the img tag.

SSI code

This section displays the SSI comment that needs to be inserted in a page to display the current campaign.

AUTHOR ^

Ave Wrigley <Ave.Wrigley@itn.co.uk>

COPYRIGHT ^

Copyright (c) 2001 Ave Wrigley. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

syntax highlighting: