Linkanalytics is a Django app that tracks web accesses by particular visitors. Each tracked URL contains a unique identifier which opaquely identifies both the visitor and the web resource being visited. The URLs also contain a hash value which ensures that only URLs generated by Linkanalytics are tracked--a URL cannot be modified outside of Linkanalytics without rendering it invalid.

This allows, for instance, links to be sent out and then accesses via those links to be counted.

The Linkanalytics model is based around four concepts: the Visitor, the Tracker, a TrackedInstance, and an Access.

The Visitor is typically the person or group of people who access a Linkanalytics tracked URL. The Tracker is the resource or resources that are retrieved via a tracked URL. So if Alice visits a tracked URL to an online newsletter, in this case Alice is the Visitor and the online newsletter is the Tracker. However, each can also represent more general concepts--a Visitor need not be an individual, and a Tracker need not be a single resource.

A TrackedInstance is a combination of one Visitor and one Tracker. It is in the TrackedInstance that access statistics are actually kept. It is also in the TrackedInstance that the unique identifier that marks URLs is kept.

An Access is generated, not surprisingly, whenever a tracked URL is accessed. It is created whether the access was successful or not. Even if the unique identifier or hash value are invalid, an access is saved, but in this case the target resource is not returned and the failure is noted.

When a tracked URL is visited, some resource must be returned. This is done using a Django view function and the appropriate function is called by querying a urlconf. (This urlconf may be set using the LINKANALYTICS_TARGETS_URLCONF setting.) The Linkanalytics term for the resource is a target, and the views module is called targetviews. By default, the urls for a target are stored within the project's normal urlconf files.

A Linkanalytics tracked URL is in the following format:

<URLBASE>/<HASH>/<UUID>/<URLTAIL>

URLBASE:

The beginning of the URL and one that does not factor in Linkanalytics tracking. This includes everything from http:// until immediately before linkanalytics. This is defined by the setting LINKANALYTICS_URLBASE.

HASH:

A hash value based on the SECRET_KEY provided by Django, the UUID, and the URLTAIL. (A different secret key can be used by defining LINKANALYTICS_SECRET_KEY in settings.)

UUID:

An identifier that uniquely identifies a Visitor, Tracker pair. This determines where access statistics for this tracked URL are kept.

URLTAIL:

The URL that the targeturls module evaluates and determines which targetview function is called.

Hopefully you'll find Linkanalytics installation to be relatively simple. There are a few main steps but each should be relatively short. These steps assume you already have Linkanalytics in the right location (generally a subdirectory of your project directory). As with every other Django app, you will need to set the INSTALLED_APPS setting to include Linkanalytics.

Once you have the Linkanalytics package in the right location, you will need to define one setting, and have the option to define many others. Those others fall back to suitable defaults otherwise.

The setting you must define in your settings.py module is LINKANALYTICS_URLBASE. This is should contain everything that comes before "/linknalytics" in your URLs. For example, if the app can be accessed at "http://www.example.com/linkanalytics", you would need to set LINKANALYTICS_URLBASE to "http://www.example.com". It must not contain a trailing slash.

Linkanalytics must be able to respond to tracked URLs so it can forward them to targets. Like any other Django app, this is accomplished through the urlconf. Linkanalytics makes this easy by providing a variable that you can place directly in your root urls.py file:

...
import linkanalytics.urlsaccess
...
urlpatterns = patterns('',
    ... 
    linkanalytics.urlsaccess.URLCONF_TUPLE,
    (r'^linkanalytics/', include('linkanalytics.urls')),
    ... 
)

This will forward anything matching a Linkanalytics tracked URL to the appropriate targetview.

This should normally be placed in your root urlconf. When Linkanalytics creates a tracked URL, the LINKANALYTICS_URLBASE is always the first part of it. Therefore, technically, the URLCONF_TUPLE variable should be placed in the urls.py file such that all URLs to it will be interpreted as beginning with the LINKANALYTICS_URLBASE--this is normally the root urlconf.

The <URLTAIL> portion of a tracked URL (see URL Structure) determines to which view Linkanalytics will forward a request. Such views are called targetviews. Linkanalytics comes with a few such targetviews, mostly having to deal with the needs of the Email app. However, the system is fully extensible and you are free to add more targetviews of your own.

A targetview function can do anything a normal view can do. And it must also return a Django response. However it does have an extra required parameter and it must have a decorator. Here is the outline of a targetview:

from django.http import HttpResponse
from linkanalytics import decorators

@decorators.targetview()
def my_targetview(request, uuid):
    html = "<html><body>This is my targetview.</body></html>"
    return HttpResponse(html)

The uuid parameter is the uuid that was contained in the tracked URL. Any extra parameters that are in the urlconf pattern will follow uuid just like normal views.

The decorator provides a simple mechanism that allows only tracked URLs redirect to targetviews. If someone tries to access a targetview with an untracked URL, they will receive a HTTP 404 error. If this behavior is not desired, you can allow access via tracked and untracked with the allow_all argument:

@decorators.targetview(allow_all=True)
def my_targetview(request, uuid):
    html = "<html><body>This is my targetview.</body></html>"
    return HttpResponse(html)

The email app contained within is built on top of Linkanalytics. It allows one to send emails which, with the help of cooperative recipients, allows the sender to know they were received. It both embeds an invisible image and includes links--all of which are tracked. Of course, all email clients today block such images by default, and recipients are wary of following links from unknown senders, so this is intended for use within organizations or other groups where the recipients already have a prior relationship with the sender.

One can write emails within the app using the Compose interface. Drafts of emails can be saved and edited later. Once sent, they may not be modified except to send them to more contacts.

Once sent, one may find out which recipients have acknowledged that they read the email and which have not.

This is the alpha release.