AdShark Documentation
Contents
Introduction
Requirements
Installation
Entering Registration Information
Preparing Your Site
Using the AdShark Administrator
- Creating or Editing an Ad
- Deleting an Ad
- Testing an Ad
Displaying Ads on Your Site
- Summary of AdShark Scripts
The AdShark Log Files
Where to Get Help
AdShark is a complete web ad management system for active server page (ASP) based Internet and intranet sites.
AdShark will randomly rotate all all types of advertisements (including GIF, animated GIF, HTML, DHTML and JAVA) in your site's ASP documents. You decide where the ads go in your layout by inserting a few lines of ASP, and AdShark does the rest. It can handle 'weighted' displays, where some ads get shown more frequently than others, and you can define 'categories' for ads that belong on certain pages or in different parts of your page layout. AdShark can also limit the number of times an ad is shown by displays, click-thrus or by date - and it can generate log files indicating the date, time and IP number of who saw or clicked on the ad.
AdShark's log files, generated in W3C extended log file format, can be used for single ads, or shared between as many as you like - so you can provide each of your sponsors with a detailed report of their activity, without any extraneous information. And because the reports are in a standard web log format, you can load them into many web access statistics utilities to analyze usage and produce activity graphs.
The password protected AdShark Administrator allows you to enter, edit, remove or test ads from any browser. The administrator also has built in support for virtual servers, so ISPs can perform one installation and allow multiple clients to access AdShark's features.
AdShark is supported on Microsoft Internet Information Server (IIS) and Personal Web Server (PWS) version 4.0 or higher running on Windows NT Server, Windows NT Workstation or Windows 9x. AdShark may function on other server platforms that support ASP, however alternate configurations are not officially supported.
AdShark can be used with Microsoft Internet Information Server 4.0 (or greater), Microsoft Personal Web Server 4.0 (or greater) and may also function with other ASP-enabled servers, although it is only officially supported on the Microsoft server family.
If you have a previous version of Internet Information Server or Personal Web Server, you can obtain a free upgrade to version 4.0 or better at http://www.microsoft.com/msdownload/
You will also need Microsoft's Data Access Components 2.0 or higher and the Visual Basic 6 runtime files for portions of AdShark. These files are not included in the distribution because most AdShark users will probably have them already, and therefore not need to reinstall them. If you are sure that you need to install the files, or if you experience errors when running AdShark, they can be obtained from http://www.microsoft.com/data/mdac2.htm (you can download the typical install) and from http://support.microsoft.com/download/support/mslfiles/Vbrun60.exe, respectively.
You will need to have your web server installed and running before you install and use AdShark. AdShark will not require significant resources beyond your web server's RAM, hard disk and processor needs (refer to your web server's documentation for its system requirements such as RAM, processor speed, etc.).
AdShark is distributed as a self-extracting installer. Running the AdShark.exe installer will set up the following files:
| adshark.dll | - | The main AdShark component library. |
| adshark.asp | - | An ASP script that is used for both banner management and for logging and tracking click-thrus. |
| adshark.mdb | - | A database file that AdShark uses to maintain settings and ad information |
| adshkreg.exe | - | Used to activate the registered version of AdShark |
| adshkdsn.exe | - | Can be used to change the location of the AdShark database |
| license.txt | - | The AdShark license agreement |
| docs.html | - | AdShark documentation (this file) |
| regobj.dll | - | A shared library (in the system directory) |
During the installation, you will be prompted to choose the AdShark installation directory. The default is in you program files directory. If you choose a different location, you should make sure the directory is not under your web server root (usually C:\InetPub\wwwroot). This will prevent non-authorized users from viewing your ad information. You will also be prompted for the location of adshark.asp. This file must reside under your web root. Virtual server support is built into AdShark - just place a copy of adshark.asp under each virtual server (or place it in a shared virtual directory, such as /Scripts).
You can uninstall AdShark using the Add/Remove Programs control panel.
Entering Registration Information
AdShark is distributed as shareware - after you first install, it will print a message under each ad indicating that AdShark is unregistered. To eliminate this message you will need to purchase an AdShark license from http://oceantek.com/adshark.
When you purchase a license, you will receive a serial number and registration key that is matched to your e-mail address. You must then enter the serial number, key and your e-mail address in the registration utility available under Start Menu -> Programs -> AdShark -> Register.
Make sure that the server directory adshark.asp resides in, and any directory where .asp documents will use it, have Script or Execute permission set in your web server. Please see your web server documentation for information on these settings.
Direct your browser (any browser will do) to adshark.asp on your web server. For example, if you installed adshark.asp as C:\inetpub\wwwroot\adshark.asp (the default), you would open http://www.yourwebserver.com/adshark.asp in your browser.
The first time you run the administrator, you will be prompted to enter an administrator username and password. This is essential as it will prevent unauthorized users from viewing or altering your ad information. Note that this is not a high security system. AdShark data is only as secure as the installation of Windows NT or 9x that you install it on!
Once you have set the administration username and password, you can begin setting up your ads. Each time your return to the administrator, you will be prompted for your login information.
Should you forget or need to alter your login information, you can open the file adshark.mdb directly using Microsoft Access or another ODBC compliant data access tool. The table ServerTbl contains the login information for each server. Do not modify any of the fields other than adminuser and adminpassword.
If you move your site to a new directory on your web server, AdShark will not recognize it as the same site. To move your old ad settings to the new directory, find the entry for your site in 'ServerTbl' in the AdShark database and change the 'rootpath' field to match your site's new root directory location.
Using the AdShark Administrator
The AdShark administrator lists all the ads currently available, any categories you have assigned them to, their relative weight, and any display limitations. For example, a banner ad OceanTek might have the following entry:
OceanTek [banner] 400 21,950 displays to go ^ ^ ^ ^
| | | display, click and date info
| | |
| | ad weight (relative display frequency)
| |
| ad category (if assigned, otherwise shows ad type)
|
ad name
Using the buttons at the bottom of the AdShark you can add a new ad, edit an existing ad, delete an ad or test an ad.
In addition, the administrator provides links to the AdShark home page, documentation, license and FAQ to provide easy access to those resources while your are using it. The versions of both adshark.asp and adshark.dll are also shown.
Creating a new ad or editing an ad brings up a page where you can set all of the ads parameters. All the parameters are described below, with indications when parameters are dependent on each other or are optional.
| Name | - | Used in the AdShark administrator and in log files to identify the ad. The name is not used when actually displaying the ad to a web user. |
| Category | - | (Optional) Can be used to create 'groups' of ads. For example, if you had a page layout where you wanted large banner ads in one area and smaller ads in another, you could put large ads in a 'banner' group and smaller ads in a 'badge' group. |
| Log | - | (Optional) The location on your server where you would like the display and click log for the ad. If left blank, no log will be kept. The file should be described with a full path (e.g. C:\logs\adshark.log), and the file will be created if it does not exist. Multiple ads can share the same log, if desired. |
| Weight | - | Used to indicate the relative display frequency of different ads. For example, if the weight of ad 'A' is 100, and the total weight of all the ads in the system put together is 1000, ad 'A' will be shown 10% of the time. If ad 'A' is also in a category whose weight total is 200, ad 'A' will be shown 50% of the time that that category is displayed. |
| - | Select this to make this ad an image ad. Image ads consist of a single GIF, animated GIF or JPEG that links to a single specific URL. You can log and limit both displays and clicks for image ads. | |
| Src | - | (Image only) The URL of the image file for the ad, e.g. '/ads/adpic.gif' or http://anotherserver/images/ad.jpeg |
| Link | - | (Image only) The URL destination that the ad should link to, e.g. '/productinfo/prodA.htm' or 'http://anothercompany.com' |
| Height | - | (Optional, image only) The vertical size, in pixels, that the ad image should appear in the browser. If left blank, the browser will determine the image size. |
| Width | - | (Optional, image only) Like height, above, but for the horizontal size. |
| Border | - | (Optional, image only) The border width around the image, in pixels. If you do not want a border around the image, enter 0 (zero) for the border. |
| Log click-thrus | - | (Optional, image only) Record click-thrus in the log file, in addition to displays. This only works if you have specified a log, above. |
| Code Ad | - | Select this option to make the ad a code ad. Code ads are useful for advertisements that are composed of blocks of HTML, Java applets, or banner and link exchanges. |
| HTML | - | (Code only) The HTML to send to the browser when this ad is displayed. |
| Limit by | - | Choose either unlimited, by displays, by click-thrus or by date. This determines when and if the ad will be removed from your rotation. Unlimited ads will never expire (although you can always change the setting manually or delete the ad), limit by displays or clicks will count down from the number you enter into the limit box, and limit by date will stop showing the ad after the specified date. Note that you can only limit by click-thrus |
When you have finished editing the ad parameters, click 'Enter' to enter them into the ad rotation. If you omitted any required parameters, you will receive an error message and be prompted to make corrections. If you would like to discard any changes you made, click 'Cancel'
To permanently delete an ad from the rotation, select it and then click the 'Delete' button. You will be asked to confirm the deletion. Deleting an ad can not be undone, however it does not delete any log files or images referenced by the ad.
You can select an ad from the list and view it as it will appear in a browser by clicking the 'Test' button. This will not count against any display limits, not will it be logged.
If you test an image ad that is limited by click-thrus, and then click on the test ad, your click will be counted.
Once you have set up your ads in the administrator, you can start placing them on ASP pages on your site. Examples are given below in VBScript, but AdShark will work just as well with JScript.
To display a single randomly selected ad (weighted by the 'weight' parameter), insert this code into your ASP page where you want it to appear:
<%
Set adObj = Server.CreateObject("AdShark.Display")
adObj.Ad
Set adObj= Nothing
%>
You can limit the randomly selected ad to any category by alternatively using:
<%
Set adObj = Server.CreateObject("AdShark.Display")
adObj.Category("category")
Set adObj= Nothing
%>
Where "category" is the category name you want to limit the display to.
You can also call a specific ad by name (for example, if one of your sponsors paid you for a specific spot on your home page):
<%
Set adObj = Server.CreateObject("AdShark.Display")
adObj.AdName("theAd")
Set adObj= Nothing
%>
Where "theAd" is the name of the ad you wish to call.
If you want to display more than one ad on a page, you should only call Server.CreateObject("AdShark.Display") once. For example, lets assume you've separated your ads into two categories, 'banner' and 'badge'. You want to have a larger 'banner' ad at the top of the page, three 'badge' ads in a part of your layout, and then another random 'banner' ad at the bottom. You would include in your page (the HTML tags are included for illustrative purposes. What appears between <% and %> is the important code):
<HTML>
...
</HEAD>
<BODY>
<%
Set adObj = Server.CreateObject("AdShark.Display")
adObj.Category("banner")
%>
...
Some text and layout HTML
...
<%
adObj.Category("badge")
%>
...
<%
adObj.Category("badge")
%>
...
<%
adObj.Category("banner")
adObj = Nothing
%>
</BODY>
</HTML>
Remember that AdShark will automatically not repeat an ad on a given ASP document until it has already cycled through the entire ad rotation for your site.
If you have no ads in the rotation, or specify an ad by name or a category that does not exist, AdShark will do nothing. This is a feature, so you can use it in a production environment without worrying about error messages being displayed or interfering with your HTML layout.
| VBScript | JScript | What it Does |
|
|
|
|
| Set adObj = Server.CreateObject ("AdShark.Display") | adObj = Server.CreateObject ("AdShark.Display") | Creates a new AdShark object for the current page. |
| Ad | Ad() | Displays a random ad from the site's ad rotation. Displays are weighted by the 'weight' parameter. |
| Category("category") | Category("category") | Displays a random ad from "category". Displays are weighted by the 'weight' parameter. |
| AdName("name") | AdName("name") | Displays a specific ad by the name listed in the administrator. |
| Set adObj = Nothing | adObj = "" | Releases the AdShark object. This is optional, but will increase performance for busy sites. |
Remember to enclose all your server-side scripting in <% and %>!
AdShark can log individual ad displays and click-thus to a text file anywhere you indicate on your server. The log file location is specified individually for each ad in your rotation (see 'Creating or Editing an Ad' above). You need not, however, use a different file for each ad. More than one ad can use the same log file simultaneously. The logs are written in the W3C extended log file format, with a few modifications from the standard to facilitate parsing them with standard web site statistics tools. Many commercial and free tools exist that can help you analyze the contents of the log files. A good starting point to find them is through Yahoo! (WWW:Log Analysis Tools).
In the standard W3C format, each line would contain the URL of the document a user requested. As we are interested in ads, and not actual web documents, each line of an AdShark log file contains information about a single ad. The ad is listed by the name you entered in the administrator (converting spaces to underscore characters) preceded by either '/display/' or '/click/'. This enables you to quickly look at display or click data individually in most log analysis programs, as it mimics looking at site access statistics in two different server directories.
If you have difficulty using AdShark, please check for product or documentation updates and FAQs on the AdShark home page at http://oceantek.com/adshark. If you are a registered user, you can get technical support via e-mail to adshark@oceantek.com. Be sure to include your serial number in the subject line of the message.