Clickthrough Package Requirements Template

I. Introduction

II. Vision Statement

The Clickthrough package provides a service that allows a site or subsite to monitor how its users exit the site, by recording which links are followed to external sites. Any link can be clickthrough-enabled by embedding special information in its destination address.

Clickthrough collects information about each pair of local (origin) and foreign (destination) addresses, including a daily count of clickthroughs between each such pair of addresses.

This clickthrough log can be used to provide external sites with a measure of how much traffic originated from the local site, which can be useful for auditing or confirming revenue generating clickthroughs (e.g., referrals).

III. Clickthrough Package Overview

The Clickthrough package is subsite aware and can be mounted under any other package mount point to provide clickthrough logging service for that package (such a package becomes the parent package). If site-wide clickthrough logging is desired, a Clickthrough instance can be mounted under the site root. Namely, this can be done to emulate the functionality and behavior of the legacy clickthrough module, which used /ct/ as its "mount point".

The allowed transitions in the Clickthrough package are:

• user level:
  • recording information about the clickthrough (origin, destination, date, parent package), by incrementing the appropriate click count for each clickthrough-enabled link that the user clicks on;
• Clickthrough administrator level:
  • obtaining reports about the collected information, including all clickthroughs to and from specific addresses, by date, for each specific parent package.

Embedding links in static HTML pages, although supported in previous versions, is no longer a requirement for this version of Clickthrough. In fact, the embedded link would have to contain hardcoded clickthrough information. This has the disadvantage of making such a clickthrough-enabled link dependent on the location (the mount point) of the Clickthrough instance.

IV. Use-cases and User-scenarios

• Developers or designers (collectively referred to as "developers"), who embed clickthrough-enabled links into dynamic pages;
• End-users (referred to simply as "users"), who follow clickthrough-enabled links to external sites;
• Clickthrough administrators (referred to "admins"), who use the admin pages to obtain information about the clickthroughs from the site to external addresses.

Clickthrough-enabling links

To clickthrough-enable a link in a dynamic page (e.g., a Tcl or ADP page), David wraps the href part of the link as an argument to a procedure that automatically provides all the necessary information for the clickthrough to be logged, namely the location of the local page (i.e., the origin of the clickthrough), as well as the location of the appropriate clickthrough instance in the sitemap. In this case, David does not need to be aware of the final location of the page he's writing nor be aware of whether and where the clickthrough instance will be mounted on the sitemap, because he does not need to provide any information to the procedure other than the destination URL.

Following clickthrough-enabled links

Obtaining reports about clickthroughs

V. Related Links

• System/Package "coversheet" - where all documentation for this software is linked off of
• Design document
• Developer's guide
• User's guide
• Other-cool-system-related-to-this-one document
• Test plan
• Competitive system(s)

VI.A Requirements: Data Model

• 10.10.0 Clickthrough log
  • 10.10.10 Each clickthrough log record refers to a unique local-URL/foreign-URL pair and to a parent package instance.
  • 10.10.20 No more than one clickthrough log record for each local-URL/foreign-URL pair will exist for any single day.
  • 10.10.30 Each clickthrough log record contains an incremental count of the clickthroughs for the local-URL/foreign-URL pair, the package instance and the day it refers to.

VI.B Requirements: Developer Support

• 20.10.0 Format of clickthrough-enabled links
  • 20.10.10 A clickthrough-enabled link will have the following format: /parent-package/clickthrough-package/relative-path-of-local-file-under-parent-package?send_to=foreign-url, in which parent-package represents the mounting point of the parent package, clickthrough-package represents the mounting point of the Clickthrough instance underneath the parent package, relative-path-of-local-file-under-parent-package represents the path to the local file that contains the clickthrough-enabled link, relative to the parent package, and foreign-url represents the URL of the external site.

    As an example, /doc/click/basics/file.html?send_to=http://www.adomain.com/adir/afile.html will record clickthroughs from a file named file.html, located under /doc/basics (/doc being the mounting point for the ACS Core Documents package and basics being a subdirectory within that package) to the http://www.adomain.com/adir/afile.html external page.

• 20.20.0 Clickthrough-enabling links
  • 20.20.10.0 Clickthrough-enabling links in dynamic pages
    • 20.20.10.10 A developer shall be able to build a clickthrough-enabled link in a dynamic page (e.g., Tcl or ADP pages) just by passing the destination, or foreign, URL to a procedure. This procedure will return the content of the href attribute of an <a> tag. Such content will be determined at run-time and will correspond either to a plain link to the provided URL or to a clickthrough-enabled link to that same address, depending on whether a Clickthrough package is mounted under the package to which the page belongs, or not.

VI.C Requirements: Internal Transactions

• 30.10.0 Recording clickthroughs
  • 30.10.10 Clickthrough logging should use a caching mechanism in order to avoid incurring a database hit for every link that is followed.

VI.D Requirements: Administrator Interface

• 40.10.0 Raw data
  • 40.10.10 The admin will be able to see a list of all clickthroughs from a local URL.
  • 40.10.20 The admin will be able to see a list of all clickthroughs to a foreign URL.
  • 40.10.30 For each local-URL/foreign-URL pair, the admin will be shown a daily count of clickthroughs.

• 40.20.0 Aggregated data (summary reports)
  • 40.10.10 The admin will be able to see a list of all clickthroughs, grouped by local URL, along with a total count of clickthroughs for each URL pair.
  • 40.10.20 The admin will be able to see a list of all clickthroughs, grouped by foreign URL, along with a total count of clickthroughs for each URL pair.
  • 40.10.30 For each local-URL/foreign-URL pair, the admin will be shown a daily count of clickthroughs.

VII. Revision History