HTML delivery delivers source HTML code required both to display the ad, and create the correct hyperlink to the click-thru event. To do this it uses dynamically generated <IMG>, <APPLET> or <EMBED> tags, or free-form HTML of your own specification. Usually the HTML will be returned to the SRC parameter of a FRAME, LAYER or IFRAME tag, or loaded by JavaScript events on the banner site page.
N.B. When putting ads onto secure pages, ensure that all calls to Domino Banner Ad agents are also using https protocol rather than http, to avoid browser security warning messages.
All ads are displayed using a URL which calls the Domino agent WebAdShow. A number of optional parameters can be specified on the end of the URL:-
| HTML Delivery Only |
| &S | Request for HTML source to be delivered rather than a binary image, i.e. to switch on HTML Delivery rather than File Delivery |
| &R | Use on WebAdShow to request a random number to be generated on HTML delivered ads. Used to beat local and proxy caches, to ensure that the latest ad site is always the one returned. The random number will appear as &R=4744829 on the dynamically generated WebAdClick code. |
| All Delivery Methods |
| &K | Do not increment ad display counter or perform any analysis. |
| &X=MyAccount | Specify an account name for the advert rather than the referring page address. If omitted, Banner Ad uses the current page URL as the account.
If "Allow Automatic Account Creation" has been switched off, these must be created beforehand in the database; otherwise they will be initialized on the fly.
If "Enforce Accounts" is switched on, this parameter is mandatory. |
| &E | Select only ads with embedded objects. Use in the SRC parameter of an <EMBED> tag on a web document, or combined with the &S parameter of a HTML delivery request.
If omitted, an object compatible with the <IMG> tag will be sent on File Delivery ads, and any ad for which HTML can be generated on an HTML Delivery ad. |
| &J | Select only Java ads. Use in the CODE parameter of an <APPLET> tag on a web document, or combined with the &S parameter of a HTML delivery request.
If omitted, an object compatible with the <IMG> tag will be sent on File Delivery ads, and any ad for which HTML can be generated on an HTML Delivery ad. |
| &Debug | Turn debugging mode on - errors are reported in detail as text, rather than images. Only operational if Allow Debug is switched on in the Settings document.
For Java ads with internal URL links, clicking on the ad in the Debug page will lead to the WebAdClick debug page. For all other ads, clicking on the ad will have the standard click behaviour, but an additional Debug Ad hyperlink will be provided underneath the ad to debug the click-thru. |
The ad is placed on a web page using the format:
<A HREF="<click agent web address>">
<IMG SRC="<show agent web address>">
</A> |
or
<A HREF="<click agent web address>">
<EMBED SRC="<show agent web address with &E parameter>">
</A> |
or
| <APPLET CODE="<show agent web address with &J parameter>"> |
(N.B. HTML delivery allows a wide variety of extra parameters to be placed on APPLET tags)
The basic syntax for the Domino Banner Ad address is:-
http://your.webserver.com/DomBanAd.nsf/WebAdShow?OpenAgent
(If you have placed DomBanAd.nsf in a subdirectory, adjust this URL accordingly).
In addition, the <IMG> or <EMBED> tag must be surrounded by a hyperlink definition pointing to the Domino Banner Ad agent which handles clicked ads and forwards the user onto the advertised site (Java applets may process mouse clicks internally).
<EMBED> Tags
If using <EMBED> ensure that you supply the &E parameter in the WebAdShow agent URL - Banner Ad will supply ads with <IMG> tag compatible images where the URL does not contain &E and <EMBED> compatible images where it does.
Java ads
For Java ads, you must use the &J parameter to ensure that only a Java class will be returned as a file. Note that File Delivery is limited in use with Java to single classes, unless you hold the rest of the code in an external static URL. Also, you may only pass parameters if you have a standard set of parameters for all applets in use, and can pre-code the <PARAM> tags accordingly. HTML delivery is required for the full power of Java applets.
Example Code
Including click-thru hyperlink, for delivering an image file:
<A HREF="http://www.acme.com/DomBanAd.nsf/WebAdClick?OpenAgent&X=HomePage">
<IMG SRC="http://www.acme.com/DomBanAd.nsf/WebAdShow?OpenAgent&X=HomePage">
</A>
Dynamic Ad Generation
N.B. The code above can be hard-coded onto a web page. Alternatively, the Banner Ad HTML can be generated, whether by Perl, dynamic HTML, or more simply using Notes formula language if being served by a Domino server.
For example, the code could be included in the design of a Notes form, and the subject (or other field) abbreviated to form an account (&X) code for the ad. Coupled with dynamic account creation, this offers a quick way of creating 100s of banner sites, each individually trackable, from the same form. |
N.B. In order to use HTML delivery, it is essential that the BaseURL setting in the preferences document has been set correctly.
For example, if your Banner Ad server is called www.rhizomatics.com and the ad database is called DomBanAd.nsf in the web subdirectory, the BaseURL would be http://www.rhizomatics.com/web/DomBanAd.nsf |
With HTML delivery, Banner Ad does not deliver the binary image file in response to a <IMG> tag, but delivers the entire HTML required to display and link the ad, as would be used for file delivery. HTML delivery is much faster and more flexible than file delivery.
There are three ways to incorporate HTML delivered ads:
1. Use the SRC= parameter of a frame within a frameset. For non-framed pages, use an IFRAME (Internet Explorer), LAYER or ILAYER (Netcape)
2. Load via JavaScript
3. Load via SSI (Server Side Include)
Whichever method used, the Domino Banner Ad agent must be called as the source of the HTML code, and the &S parameter incorporated in the agent URL. Code to do this is generated automatically for you in each banner site document.
Domino Banner Ad selects the next ad in the rotation and builds a reference to this into the dynamically built click-thru URL using the &A parameter. This means that no impression document need be created by the display agent, nor will the database of impressions have to be searched (and deleted) by the click-thru agent. This leads to at least 60% performance gains, and minimizes the amount of database transactions. This method also handles browsers behind proxy gateways, and guarantees that the ad clicked is always the ad displayed (which typically requires cookies to ensure).
Frameset Example
Non-framed example
This method uses the <IFRAME> tag on MS Internet Explorer (available on v3 upwards), with alternate code (within the <IFRAME> and </IFRAME> tags) for Netscape Navigator - using Netscape's <ILAYER> (or <LAYER>) equivalent to <IFRAME>. This ad code can be placed anywhere in an existing page.
JavaScript example
This simple javascript header will load the generated HTML into a new window. Vary to change the attributes of the window, or to display the HTML within the main browser:
SSI example
The banner ad code can be invisibly merged into any part of a web page using a Server Side Include (SSI) call.A simple CGI program is attached below which will run on any brand of server on an Intel/Win32 platform; it should be detached into the cgi-bin directory of the server on which the banner site pages is served (not necessarily the same server as that serving the ads - you might have a site running on a MS IIS or Apache server, but ads served from a Domino server).
| <!--#exec cgi="/cgi-bin/dombanad.exe?http://www.myserver.com/web/"--> |
dombanad.exe
If run with no arguments, this CGI program will default to fetching the ad code from the same server it is executed on, and will look for the Banner Ad database as DomBanAd.nsf on the root of that server. You only need enter as much of the full agent path as is required to override those defaults; e.g. in the example above, the ad agent will be called from http://www.myserver.com/web/DomBanAd.nsf/WebAdShow?OpenAgent. Other parameters, such as &R and &debug can be specified at the end of the URL and will be passed on to the WebAdShow agent. N.B. the syntax of SSI calls can vary by HTTP server.
Results
When called, Domino Banner Ad will dynamically build and deliver the HTML for the page in the 'ad' frame. The example dynamic code for a frameset might look like:
The delivered code comprises five sections:
Some features to note:
- Optional target frame for the click-thru. Typically this could be main to open the sponsor's page in a new browser, _top to open the page in the entire current window, or a named frame on the specific page. Target frame can be set in the Ad document or the Site document. Usually the Site is more appropriate, since all the custom frames for that page may be known, but the Ad document is useful to send to one of the standard frame names.
- Optional alternate text for the image. This will show if the image cannot be displayed (e.g. the user has switched off graphics display or is using a text-only browser). Recent Netscape and MS browsers will also show this as pop-up text when the mouse is passed over the ad image.
- Optional additional tag parameters, most useful for fully specifying Java <APPLET> tags, but will also work with <IMG> and <EMBED> tags
- Optional Java applet parameters. This field can be used to contain the set of <PARAM> required for a Java applet. If the Java applet takes a URL to action a mouse-click, specify the name of this parameter in the Link Parameter field. If the parameter value references a file stored as an attachment on the ad, use the special word %CODEBASE% as part of the parameter value to reference it. e.g. <PARAM name="image1" value="%CODEBASE%sample.gif">
- Image sizing - if Banner Ad knows the size of the image it will pass this on the <IMG> tag, allowing the browser to pre-allocate the screen space for the image before it is delivered.
- Optional Random URL using the &R parameter. The tag is ignored by the click-thru agent, but will force the browser to request the link again, and not return a page from its own or a proxy cache.
- Additionally, Banner Ad can replace the standard Domino HTML and HTTP headers with codes of your choice, and override the <BODY> tag, e.g. to change the background colour. The header control allows you to add meta tags of your own - for example, to force the client browser to load a new ad every 30 seconds. Use the Header HTML, Body Type, Cache Expiry, Cache Control, HTTP header, Frame Refresh and Browser Cache to control the headers.
Three scheduled agents are supplied with Domino BannerAd:-
- Purge Agent. Clears down impressions, records of ads displayed to particular users using File Delivery and maintained for brief periods to link a click of an ad to the original ad displayed. If all your ads are delivered via HTML, there is no need to run this agent.
- Purge Cache. Clears down the file cache. To improve the performance of delivering images, Java classes, flash files and other media, these can be cached in the server's native file system rather than served from the Notes database. This is handled automatically by Domino Banner Ad. This agent can be set to run periodically to remove these files and their associated directories.
- Ad Refresh. Runs every midnight and introduces ads which have reached their start dates, retires ads which have reached their end date, sets default values and maintains the list of valid site groups for ads which may appear on any page (i.e. have Site Group field left blank). An agent is used rather than a view selection to maximize performance.
For efficient database operation, and space conservation, use the purge agent regularly. It is also possible to switch on purge of impressions as they are clicked, but there remains the need to purge unclicked impressions - alternatively, all purging can be made by the agent reducing on-line time.
By default the Purge agent operates every 2 hours, and the Ad Refresh agent once per day shortly after midnight.You may amend these schedules to fit your own environment.
- If using File Delivery, in addition to regular purging of the impression documents, it is essential to minimize the number of deletion stubs held in the database. If uncontrolled, the database size will grow for long periods, even though purging of impressions is carried out regularly.
- Notes retains minimal details of all deleted documents for a period of one third the number of days set in the replication setting 'Remove documents not modified in the last x days'. This defaults to 90 days, and hence the default deletion stub retention period is 30 days. If the database is not being replicated, this replication setting can be set to 0 days, and therefore deletion stubs will be immediately purged from the database.
- HTML delivery is much faster than File Delivery. This is largely because the latter requires a server-side cookie to be created to track each ad between impression and click-thru. HTML delivery manages this by building the link into the generated HTML - reducing processing time for both impression and click-thru, and reducing database 'churn' (i.e. the number of documents being created and deleted).
- For maximum database performance, switch off multi-dimensional (OLAP) statistics or create a separate database for the statistic documents. The more dimensions you select, the greater the overhead for maintaing multi-dimensional stats. Ad and site level stats have much lower overhead.
- To improve the speed of delivering files - such as images, Java applets, Flash files etc - to browsers, these can be cached in a local file cache (under the domino/html) directory. Since native file system retrieval is usually much faster than retrieval from Domino databases, you can give your site an extra performance boost. See the caching FAQ for more details.
- For file delivery, use internal redirection where your server supports this. In principal, this has been a part of Domino since v4.5, but in practice only R5.X servers can be assured to operate it. Internal redirects (a.k.a. 'double-bracketing') sends the file location URL immediately to the Domino web command engine, thus eliminating a double journey from the browser and back to the server. It also affects the URL as seen by the browser - with internal redirection, the actual file location is never revealed to the client.
|
N.B. The information here relates to browser and proxy caches, not to the internal file cache which can be switched on for Domino Banner Ad, and which is an invisible performance enhancing measure.
For control over browser and proxy caches you need HTML delivery - for File Delivery ads you must rely on the poor cache control of the Domino server itself. With HTML delivery you have control over both the HTML Header and more importantly the HTTP Header (which is usually seen only by webmasters rather than web authors)
HTML Header
The HTML Header control can be switched on automatically by selecting the Block Browser Cache in the Ad document, or you can specify your own alternate META codes in the Header HTML field. However, despite the widespread use of META codes by hopeful web designers, they are often ignored in practice.
A sample of code generated by the Block Browser Cache option is shown below - one advantage of using this function rather than hand coding the META statements in the Header HTML is that the expiry date and time are automatically calculated. Documents are expired within 60 seconds.
<META HTTP-EQUIV="Pragma" CONTENT="no-cache">
<META HTTP-EQUIV="expires" CONTENT="Fri, 12 Nov 1999 14:57:38 GMT">
<META NAME="revisit-after" CONTENT="1 days">
Also, use the Randomize URL function, either by selecting this on in the Ad, or by putting a &R tag onto the URL for the agent.
HTTP Header
The HTTP header precedes every web page sent by a web server, and contains the most powerful controls available to you over how your pages are treated by remote browsers and proxy caches.
META tags in HTML headers are only respected by certain web browsers, and will generally be ignored by proxy and in-line caches. HTTP headers allow you much more precise control, including the ability to separately indicate how proxy and browser caches should handle your pages.
| Sample HTTP Header |
HTTP/1.1 200 OK
Server: Lotus-Domino/Release-4.6.7(Intl)
Date: Mon, 29 May 2000 12:44:09 GMT
Content-Type: text/plain
Content-Length: 218
Content-Type:text/html
Expires: Mon, 29 May 2000 12:44:39 GMT
Last-Modified: Mon, 29 May 2000 12:44:09 GMT
Cache-Control: smax-age=60, proxy-revalidate, no-cache
ETag: "943B30C845D25B52802568EE003DD680"
Connection: Close |
The HTTP cache expiry counts in seconds how long the page should live in such a cache before being refreshed. Banner Ad will automatically generate an Expires header (HTTP 1.0 compatible) and a max-age setting (HTTP 1.1 only). In addition, it allows you to specify a separate expiry for proxy caches (which generates a smax-age setting) and will always include a Last-Modified date, which enables proxies and browser caches to make better cache decisions.
Additionally, you can discriminate between public caches (such as that of a corporations proxy server, or an in-line cache used by an ISP) and private caches on the browser or mobile device. The private keyword selected in Cache Control specifies that the expiry period applies only to private caches, rather than public ones.
Of the other cache control keywords available, no-store switches off all caching and no-cache is the equivalent of setting the expiry to zero seconds, i.e. the image will still be cached, but will expire immediately.
The reason for separately controlling public and private caches is that some web material times out for everyone (like today's news), whereas other personalized content times out for individual users. If you wish to ensure that every hit to your page gets a fresh ad, then select no-store. If you want to have freshened ads, but don't want to supply new ads quite that often, tune the timings for the expiry counter.
A new addition to HTTP 1.1 is the ETag - this allows down-stream browsers and caches to be object-aware; it is possible using ETags to discriminate between multiple ads sent using the same HTML address. When switched on, Domino Banner Ad will generate an ETag using the Universal ID of the Ad document being supplied. Another HTTP 1.1 addition is Connection Control - Banner Ad allows you to close this, to prevent an expectation of a persistent connection.
HTTP Headers are not visible from web browsers, even when using the "View Source" option - this will show only the HTML header. A useful tool for viewing both types of header is gethttp.exe, also supplied by Rhizomatics.
N.B. The cache control offered by Domino Banner Ad is far in advance of what is available from the Domino server itself (which is often criticized by webmasters for its poor caching support). Another good reason to use HTML delivery.
Further information
| Statistics, Reporting and OLAP |
Banner Ad always collects basic statistics, such as impressions and click-thrus, on the Ad and Site documents. Buttons exist both on the form and view to clear all statistics, or to reset for period. Performing a reset will keep both current and life-time statistics up to date, with a record kept of the last reset date.
Additionally, Ad and Site documents may also be used to gather extended Ad and Site Analysis Statistics, such as analysis of browser network domains, and browser versions at both simple or detailed level. Naturally, the more stats you choose to gather the more processing work is involved, but the overhead of document level statistics is relatively small.
For more powerful reporting, Banner Ad offers multi-dimensional (a.k.a. OLAP) statistics gathering for powerful reporting. These stats can be gathered in the same database as the ads, or in an optional separate database (with the same design template). The level of detail of the statistics is as broad or as narrow as you wish.
Multi-dimensional stats are stored as Fact documents, created with two measures - impressions and click-thrus, and a choice of dimensions, including multiple hierarchies (e.g. Day, Month,Quarter) for the time dimensions. Dimension selection is carried out from the Settings document. The more dimensions selected, the greater the processing time and disk space requirements to hold the data. On the other hand, each dimension is a different independent method of analyzing the resulting data, and can be used in combination with other dimensions for any type of query.
Two simple views are provided in the Analysis Menu to analyze the fact documents. However, to benefit from the full available power, a separate reporting tool or hypercube builder, such as Seagate Info, Business Objects, MS Access or Excel is recommended.
Optional reporting by XML is included both as a useful new way of reporting, and as an example of how to code the various XML delivery components in Notes, and how to make them dynamic. N.B. This requires an XML-enabled browser, MS Internet Explorer 5 recommended.
The sample report included here has a number of features which distinguish it from vanilla XML or what can be done with HTML:
- Notes style sorting based on a particular column works for all columns, as in Notes by simply clicking on the column header
- Rows of the report are highlighted automatically to show high and low ad activity
- The schema, data and stylesheet are all dynamically generated to match exactly the structure of your OLAP data. If you only have Site, Ad and Date selected, then these will be the only three fields to appear in either the schema, stylesheet or data.
- Certain data values, such as day of week, day type and watch, are converted from numbers to descriptions by conditional XSL
- XSL functions calculate total clickthrus, impressions and average ratio
- All the code is open and free, for you to re-use and adapt as you wish.
There are three elements required for an XML report, each with its own LotusScript agent:
- XML data itself. Created by agent report.xml
- Schema for the XML data, itself in XML. Created by report_schema.xml
- XSL stylesheet. Created by report.xsl
To display the report, call the web agent which produces the XML data. An example URL is:
http://www.me.com/dombanad.nsf/report.xml
The plainly formatted data includes the following lines, which call the other two web agents to complete the output:
<?xml:stylesheet type="text/xsl" href="http://www.me.com/dombanad.nsf/report.xsl"?>
<report xmlns="x-schema:http://www.me.com/dombanad.nsf/report_schema.xml">
N.B. You must ensure that the Base URL is set in the database preferences, so that the correct URLs can be built for both the stylesheet and namespace. In the examples above, it is highlighted in green.
An XML enabled browser will show not the actual XML file (although this can be seen using the 'View Source' option), but the dynamically generated HTML produced by the actions of the stylesheet on the base data. Internet Explorer 5 will also allow you to call the stylesheet and namespace directly from the browser, and display these as properly structured documents, rather than plain text - a useful aid in debugging XML.
To expand the reporting capabilities, it is not neccesary to create another stylesheet, namespace and XML data output for every report - all that is required is a new stylesheet for the new report. A stylesheet can contain not only HTML formatting instructions, but also filtering, field selection and sorting power.
The Domino security model for web agents, as described in the documentation, allows a simple choice for authentication between the signer of the agent and the remote browser user who runs the agent. In practice, operation is not so simple, since Domino cannot be relied upon to consistently apply the published security model - and the pattern of inconsistency varies between QMR and QMU releases.
The one certainty in a security model for a web agent such as banner ad displays, is that there must be no authentication box for access to such an agent. It would be ridiculous to expect a casual visitor to a corporate home page to be faced with a login box before a banner ad could appear in the browser.
The next principle, is the need to assign remote users the minimum possible permissions in order to execute the agent. In the context of the apparent Domino security model, this can fairly easily be accomplished using a combination of public access switches and the ability to base security for an agent on the signer. This will not, however, actually work - at least until Lotus iron out the problems with web agent security.
v2 applies the following security model:
- Anonymous access set to Reader and Write Public Documents
- Ad, Site and Stat documents set to be Public Access
- WebAdShow and WebAdClick set to Public Access
- Statistics and reporting views controlled by Private Stats role
- All views hidden from Anonymous
N.B. For upgraders to v2 run the Upgrade\Make Documents Public Access agent once after upgrading in order to support the security model above. This will add a field called $PublicAccess with a value of "1" to each document - this permits web users with Reader access to update such documents via web agents.
If Anonymous rights are set to Editor, then there's no need to set individual documents to Public Access; however, it is not recommended for Internet use to give unknown browser users a whet more access rights than is absolutely necessary - somebody, somewhere will try to abuse any such gap in your web armour.
| Frequently Asked Questions |
Questions
1. I can't get any banner ad to appear on my page
2. How can I find out who is visiting my pages?
3. Can I mail stats to my users?
4. What controls which ad is shown next?
5. What does it cost?
6. Isn't it inefficient to use LotusScript rather than say perl?
7. Why aren't the LSS files for the agents included in the ZIP distribution?
8. Why doesn't clicking on ads work on browser X?
9. How do I get an ad to automatically refresh itself?
10. How do I prevent browsers caching ads?
11. How do I stop Domino creating it's own HTML header and BODY tag?
12. How do I create a Java applet ad?
13. How can I target ads at specific locations?
14. Why do I get a browser message complaining about insecure items on a page?
15. How can I improve performance?
16. Short Lesson on Domino Paths
Answers
I can't get any banner ad to appear on my page
Check that:-
a) You have signed the Domino Banner Ad database with a locally certified ID. This can be done quickly and simply using the Database Tools section of the Notes Server Administration screen.
b) Try executing the agent directly from the browser, rather than specifying the address inside an IMG tag. When you do this, any error messages returned by the Domino server or Domino Banner Ad will be displayed on the screen, whereas when called by an image tag, the browser will only display a 'bad image' icon. You can obtain further textual information on any problem by using the &debug parameter.
e.g. http://myserver/DomBanAd.nsf/WebShowAd?OpenAgent&debug
If you don't get a debug report, then the agent is not being run at all - either because your URL is not specified correctly, or there's a permission problem on the server.
c) Check the syntax of your URL. If you've shifted the DomBanAd.nsf database to a subdirectory on the server, your URL will have to change to compensate. Easy way to test your root URL is to open the DomBanAd database directly in a browser. The simple URL http://myserver/DomBanAd.nsf will open up the default web navigator of Domino Banner Ad, if your URL is right.
d) Make sure you have adverts in the database! Domino Banner Ad comes with a sample ad, but if you've deleted all of these, it isn't going to be able to display any ads.
e) Check the Server's Agent Restrictions. Since the agent must create files at operating system level, it is categorized as an Unrestricted LotusScript Agent. Ensure that the agent signer (if signer-security is being used) is included in the Agent Restriction section of the appropriate server document in the Name and Address book. If you can only acquire Restricted LotusScript rights then use the WebAdShowRestrict and WebAdClickRestrict agents.
f) Check the Agent Execution Rights option. The rights to run a Domino web agent can be determined by who signed the agent, or by the person executing it (the choice is made via the "Run Agent as Web user" option on the agent's properties box). Since the latter will usually be anonymous, the agent signer method is preferred.
N.B. An excellent summary of the issues involved in Domino web agent execution and security is available in Julie Kadashevich's article in August 1997's Notes Today webzine.
g) Check the Database Access Control (ACL) There must be an entry for Anonymous, to prevent the server requesting authentication for every access. However, so long as the agent is being run with the signer's security (see item above) there is no need to give Anonymous users any more than No Access access, so long as the Read Public Documents is switched on. All of the web agents, and all of the error report forms, are marked as public documents.
h) Edit and Save the preferences document. This is found under Edit Settings action.
How can I find out who is visiting my pages?
The banner ad agents maintain a LastBrowser and LastAddress field automatically in the Account document to record. Additionally, you have the option of detailed analysis in the Ad document of both displays and clicks by browser and domain. Full multi-dimensional (a.k.a. OLAP) statistics allow you to track any desired combination of browser type, time of day, domain etc.
Can I mail stats to my users?
There isn't an agent for this at present, but it is scheduled for a future Domino Banner Ad release. Meantime, if you wish to run your own agent, either using the simple Notes agent actions or in code, there is a field called StatsRecipient in the Account form for this purpose.
What controls which ad is shown next?
Ads are stacked up ready for next showing in the hidden view called (Ad Stack). This view is not locked, and the formulae for selection can be amended, so long as the basic structure of the view remains.
There are 5 factors which control ad selection. Primary is delivery mechanism - sites which use File Delivery cannot display ads with HTML content but no image; sites using HTML Delivery can display any ad. Secondary is placement - adverts sited for top locations will always be sited on page-top sites; only if no other ads are available will a bottom, frame or middle sited ad be placed on a page top. Rotating evenly is controlled by the Ads Shown to date, Priority and Ads Shown today. The latter is used to dampen down the effect of introducing a new ad (with zero displays) into an existing set of ads with 1000s of displays to date - without the dampening effect of counting in that day's displays, the new ad would be shown continously until it had reached a similar display count to its predecessors. Finally, Priority is used to weight the effect of ads shown to date.
The formula currently used to sort ads for display (in ascending order) is:
(AdsShown-(AdsShown*(1-AdPriority)))+(AdsShownToday*2)
Priority has the effect over time that 3 ads registered at the same time, one with 200% priority, one with the default 100% and the other with 25%, might after several months be balanced out after rotation at 20000, 10000 and 2500 hits respectively.
What does it cost?
At present, nothing. Rhizomatics reserve the right to charge for any future enhanced version, but whatever, you may continue to use this current database for the rest of your Domino-using life. If you really feel appreciative, then a little acknowledgement on the banner ad with a link back to us would be sweet.
Isn't it inefficient to use LotusScript rather than say perl?
Using LotusScript has the big advantage of moving all the admin for managing adverts and page accounts within Notes databases, with all their facilities for extension and security. What's the price for that extra functionality?
Domino Banner Ad has efficiency advantages over standard cgi-bin scripts: it doesn't require an operating system shell to be created to load Perl and run the script (cgi-bin scripts can hit your server hard), and executes within the already loaded Notes agent manager. If you wish to gauge the effect of detailed statistics gathering, use the &debug option to run the agent at different levels of analysis.
So with Domino Banner Ad, you have all the advantages of databased ad processing, without the performance penalty.
Why aren't the LSS files for the agents included in the ZIP distribution?
Domino BannerAd is currently distributed free for use in any situation. However, it makes use of techniques and code which are the commercial property of Rhizomatics and is reserved for future products. Note, these source code files are not required for the operation of Domino Banner Ad. The only effect is that you cannot edit the code of the two web agents; however, all agents, views, forms and other elements are totally unlocked and available for your inspection or modification. This structure also minimizes agent loadable image size and boosts agent performance.
Why doesn't clicking on ads work on browser X?
File Delivery relies on three pieces of information to make a link between a displayed ad, and the forwarding URL to be used when the ad is clicked: the account (or page reference), the remote address, and the referring page URL.
Different browsers can handle referring URLs differently. For instance, Netscape will return a suffix beginning with # when the ad is in a Notes section or reached via an internal page anchor, while Internet Explorer will not. Banner Ad has a setting to standardize such behaviour - from the Settings document, select 'Trim URL' to trim any browser URL with this suffix.
You can have direct control over which information is used to make that link between impression and clickthru. To do so, adjust the 'BrowserTracking' control in the Settings document. The IP address is mandatory, but the choice of account code, user agent and/or referring URL is optional. N.B. Omitting the account code will mean that only one unique banner ad per web page can be tracked. If you have problems with certain browsers not tracking ads, switch off 'Referer' first. This will also marginally boost performance.
Altenatively, use HTML Delivery and the link between image and ad is built right into the dynamically generated HTML - this is faster, and allows much more control and image options.
How do I get an ad to automatically refresh itself?
For this you need HTML delivery. Choose the number of seconds before a refresh is made and enter into the Auto Refresh field of the Advanced HTML Delivery section in the Ad document.
Alternatively, roll your own custom meta code using the Header HTML field, for example:
<META HTTP-EQUIV="Refresh" CONTENT="10">
The content in this case is the number of seconds before this page or frame should be automatically refreshed. On each refresh, another ad will be selected from the stack of ads, and a new set of HTML generated for the frame.
How do I prevent browsers caching ads?
See the section on Cache Control
How do I stop Domino creating it's own HTML header and BODY tag?
Banner Ad will automatically override the standard Domino document preamble, and give you total control of the HTML output whenever you enter values for any of the following in the Ad document: HTML header, Body Parameters, HTTP Header, Auto Refresh, Block Browser Cache.
Gaining control in this way is achieved on Domino by outputting an HTTP header before outputting any HTML. Current versions of Domino will acknowledge this when the following header is used:
Content-Type: text/plain
Content-Type: text/html
If you have a need to change or augment this header, for example for a future version of Domino with different behaviour, you can take control of the HTTP header by supplying your own in the HTTP Header field of the Ad document.
How do I create a Java applet ad?
Java applets can be used with File or HTML delivery, but require HTML delivery for anything other than the simplest (single class, no parameters) applets.
To create an ad,
- Load the principal class file in exactly the same way as for any other media, i.e. use the Load Media and Analyze Media buttons on the form to make the attachment and determine the media type.
- Load any additional classes, CABs, images or other required files into the Ad Files field using the File | Attach menu.
- Enter any additional parameters for the <APPLET> tag into the Tag Parameters field.
- Enter any applet parameters, i.e. <PARAM> tags, as plain HTML into the Applet Parameters field.
- If you wish to reference binary files (e.g. media imags) attached to the Ad document, and the Java agent is not set to look for them at the codebase URL, put the special code %CODEBASE% into the parameter value. This will be replaced when the dynamic URL is created with the full code base (beginning with http and ending with a trailing /) of this ad.
- If you want a message to be displayed to non-Java capable browsers, place this text in the Alternate Text field.
- If the applet has a parameter to specify the destination (e.g. Ad Sponsor's site), type the name of this parameter into the Link Parameter, and omit that <PARAM> tag from the Applet Parameters field.
For file delivery, Banner Ad will simply supply the binary class (as loaded by the Load Media button above) file to the browser when called by the WebAdShow agent using the &J parameter.
For HTML delivery, Banner Ad will dynamically generate and send to the browser complete HTML to specify the applet, complete with applet parameters, codebase and alternate text.
How can I target ads at specific locations?
Banner Ad has two complementary mechanisms for targetting banner ads. One is the Site Group, and the other is the Banner Location (on the page).
Each banner site can be marked as belonging to a certain Site Group, and each ad can be marked as targetted at a list of one or more groups, including the special group 'Ungrouped' which allows ads to be displayed on sites with no group specified.
Banner location allows banner ads to be targetted at particular locations on a page, and also to direct multiple ads onto the same page. First of all, sites must have recorded the extact location on the target web page - top, bottom, middle or frame. Then ads can be selected for which, or all, locations on a page they will be targetted at.
If no ad can be found which meets the criteria for a particular site, a special ad called Default Ad will be displayed. To prevent this ad from being selected in the usual course of events, change it's status to Default
Why do I get a browser message complaining about insecure items on a page?
If the page containing the banner ad is secure, i.e. accessed using https protocol, then you must ensure that the SRC parameter specifying the banner ad location also uses https rather than http protocol. Otherwise browsers will complain that there is a mix of secure and insecure items on the same page.
How and why do I use local caching?
Sending files to browsers from within Notes documents is usually always slower than retrieving them from the server's native file system. With local caching, Banner Ad will copy files into a specified server file directory, and serve images to browser clients from there. This can give you a boost to perceived client performance, and reduce the workload on your server.
Configure caching in the Settings document. You must:-
1. Switch caching on
2. Supply the cache URL path
3. Supply the native server file system path.
See the lesson below for help on how the two types of Domino paths work.
Domino Banner Ad will automatically cache files as required, creating unique sub-directories for each ad so that there will be no clash between files of the same name used in different ads. Whenever you make a change to the Ad document, the Recache checkbox will be ticked to indicate that the next time this Ad is required, Banner Ad will reload the cache from the files stored in the Ad document.
It also allows whole groups of files - e.g. for Java ads - to be cached together. Banner Ad will automatically adjust the CODEBASE of Java ads to take account of the cached file locations of its support files.
To clear the cache down periodically, you can use the scheduled Purge Cache agent to remove all the cached directories and files.
| Short Lesson on Domino Paths |
Domino serves two types of content - rendered Notes documents from databases (NSF files) stored in the server's Notes Data directory (e.g. c:\notes\data), and native file system files from a directory structure which usually sits beneath the Notes Data directory. In this second mode, it operates in the same fashion as any vanilla HTTP server, simply serving up GIF, JPEG and HTML files, but including abilities such as Server Side Includes.
The Domino server installation program creates the domino directory structure automatically, with standard sub-directories domino\html, domino\icons, domino\adm-bin, domino\cgi-bin and domino\cache. Web files are stored within the domino\html directory, which may itself have a whole struture of subdirectories beneath it.
For example, on an NT server if the server Notes Data directory is d:\notes\data, the web file directory would be d:\notes\data\domino\html. Other operating systems follow a similar pattern, e.g. /opt/lotus/domino/data/domino/html.
Caveat: it is possible to override these default locations for the domino subdirectories in the Server document of the Name and Address book (a.k.a. in R5 as the Domino Directory database).
Key Point: As far as a client browser is concerned, domino/html is the root directory of the web server.
Hence, if your Domino server is called www.mycorp.com and the HTML directory is d:\notes\data\domino\html, the native file d:\notes\data\domino\html\web\index.html will appear to the web browser as http://www.mycorp.com/web/index.html. Note too that web directory will always be in forward slashes, but the file system directory will depend on your server operating system (backslashes for NT, forward slashes for Unix). |
For updates to Domino Banner Ad, check:-
http://www.rhizomatics.demon.co.uk/
LIMITED WARRANTY
Domino BannerAd is provided working as-is for live evaluation, and will continue to work for an unrestricted period. During this time there are no restrictions in the code. Rhizomatics reserve the right to charge for future upgrades or maintenance of this product. This licence entitles the user to run the software, but not to reverse-engineer, alter or sell onto other parties. The cost or guarantee of support is not included in the license. Rhizomatics will make reasonable effort attempt to fix problems reported, and enhance functionality where requested.
Rhizomatics shall not be liable for material, equipment, data or time loss, caused directly or indirectly by proper or improper use of the Domino BannerAd software. In cases of loss, destruction, or corruption of data, Rhizomatics shall not be liable. Rhizomatics does not take any other responsibility. Rhizomatics makes no other warranty.
COPYRIGHT AND LICENSE
Domino BannerAd is the property of Rhizomatics and may be copied other than for purposes of backup only as an intact ZIP file with this document.
Proprietary Rights - This software and documentation are copyrighted by and proprietary to Rhizomatics. You acknowledge that the Software and Documentation contain valuable trade secrets and other proprietary information belonging to Rhizomatics You agree to hold the software in confidence and undertake not to disclose registration numbers to another party.
NO REVERSE COMPILATION IS ALLOWED - You may not modify, translate, disassemble, or decompile the software, or of any copy, in whole or in part.
This software is licensed as stated above. The license does not constitute ownership of the software, only the right to use it. Domino BannerAd is copyrighted under international intellectual property laws.
Acknowledgements
----------------
Domino is a registered trademark of Lotus, a subsidiary of IBM
