Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bashu/django-tracking

Simple attempt at keeping track of visitors to django-powered web sites
https://github.com/bashu/django-tracking

Last synced: 10 months ago
JSON representation

Simple attempt at keeping track of visitors to django-powered web sites

Awesome Lists containing this project

README 

          
``django-tracking`` is a simple attempt at keeping track of visitors to

Django-powered Web sites.  It also offers basic blacklisting capabilities.



The offial repository for ``django-tracking`` is at

http://bitbucket.org/codekoala/django-tracking.  Please file any tickets there.



Features

========



* Tracks the following information about your visitors:



    * Session key

    * IP address

    * User agent

    * Whether or not they are a registered user and logged in

    * Where they came from (http-referer)

    * What page on your site they last visited

    * How many pages on your site they have visited



* Allows user-agent filtering for visitor tracking

* Automatic clean-up of old visitor records

* Can ban certain IP addresses, rendering the site useless to visitors from

  those IP's (great for stopping spam)

* The ability to have a live feed of active users on your website

* Template tags to:



    * display how many active users there are on your site

    * determine how many active users are on the same page within your site



* Optional "Active Visitors Map" to see where visitors are in the world



Requirements

============



As far as I am aware, the only requirement for django-tracking to work is a

modern version of Django.  I developed the project on Django 1.0 alpha 2 and

beta 1.  It is designed to work with the newforms-admin functionality.



If you wish to use a Google Map to display where your visitors are probably at,

you must have a `Google Maps API key

`_, which is free.  You

are required to have the `GeoIP C API library

`_ installed.

You might want to grab the `GeoLite City binary

`_ unless you are a paying MaxMind

customer.  This is the data file that ``django-tracking`` uses to translate an

IP into a location on the planet.  Configuring this feature is discussed later.



Installation

============



Download ``django-tracking`` using *one* of the following methods:



pip

---



You can download the package from the `CheeseShop

`_ or use::



    pip install django-tracking



to download and install ``django-tracking``.



easy_install

------------



You can download the package from the `CheeseShop `_ or use::



    easy_install django-tracking



to download and install ``django-tracking``.



Checkout from BitBucket/GitHub/Google Code

------------------------------------------



Use one of the following commands::



    hg clone http://bitbucket.org/codekoala/django-tracking

    git clone http://github.com/codekoala/django-tracking.git

    hg clone http://django-tracking.googlecode.com/hg/ django-tracking



Package Download

================



Download the latest ``.tar.gz`` file from the downloads section and extract it

somewhere you'll remember.



Configuration

=============



First of all, you must add this project to your list of ``INSTALLED_APPS`` in

``settings.py``::



    INSTALLED_APPS = (

        'django.contrib.admin',

        'django.contrib.auth',

        'django.contrib.contenttypes',

        'django.contrib.sessions',

        'django.contrib.sites',

        ...

        'tracking',

        ...

    )



Run ``manage.py syncdb``.  This creates a few tables in your database that are

necessary for operation.



Depending on how you wish to use this application, you have a few options:



Visitor Tracking

----------------



Add ``tracking.middleware.VisitorTrackingMiddleware`` to your

``MIDDLEWARE_CLASSES`` in ``settings.py``.  It must be underneath the

``AuthenticationMiddleware``, so that ``request.user`` exists.



Automatic Visitor Clean-Up

++++++++++++++++++++++++++



If you want to have Django automatically clean past visitor information out

your database, put ``tracking.middleware.VisitorCleanUpMiddleware`` in your

``MIDDLEWARE_CLASSES``.



IP Banning

----------



Add ``tracking.middleware.BannedIPMiddleware`` to your ``MIDDLEWARE_CLASSES``

in ``settings.py``.  I would recommend making this the very first item in

``MIDDLEWARE_CLASSES`` so your banned users do not have to drill through any

other middleware before Django realizes they don't belong on your site.



Visitors on Page (template tag)

-------------------------------



Make sure that ``django.core.context_processors.request`` is somewhere in your

``TEMPLATE_CONTEXT_PROCESSORS`` tuple.  This context processor makes the

``request`` object accessible to your templates.  This application uses the

``request`` object to determine what page the user is looking at in a template

tag.



Active Visitors Map

===================



If you're interested in seeing where your visitors are at a given point in

time, you might enjoy the active visitor map feature.  Be sure you have added a

line to your main URLconf, as follows::



    from django.conf.urls.defaults import *



    urlpatterns = patterns('',

        ....

        (r'^tracking/', include('tracking.urls')),

        ....

    )



Next, set a couple of settings in your ``settings.py``:



* ``GOOGLE_MAPS_KEY``: Your very own Google Maps API key

* ``TRACKING_USE_GEOIP``: set this to ``True`` if you want to see markers on

  the map

* ``GEOIP_PATH``: set this to the absolute path on the filesystem of your

  ``GeoIP.dat`` or ``GeoIPCity.dat`` or whatever file.  It's usually something

  like ``/usr/local/share/GeoIP.dat`` or ``/usr/share/GeoIP/GeoIP.dat``.

* ``GEOIP_CACHE_TYPE``: The type of caching to use when dealing with GeoIP data:



    * ``0``: read database from filesystem, uses least memory.

    * ``1``: load database into memory, faster performance but uses more

      memory.

    * ``2``: check for updated database.  If database has been updated, reload

      filehandle and/or memory cache.

    * ``4``: just cache the most frequently accessed index portion of the

      database, resulting in faster lookups than ``GEOIP_STANDARD``, but less

      memory usage than ``GEOIP_MEMORY_CACHE`` - useful for larger databases

      such as GeoIP Organization and GeoIP City.  Note, for GeoIP Country,

      Region and Netspeed databases, ``GEOIP_INDEX_CACHE`` is equivalent to

      ``GEOIP_MEMORY_CACHE``. *default*



* ``DEFAULT_TRACKING_TEMPLATE``: The template to use when generating the

  visitor map.  Defaults to ``tracking/visitor_map.html``.



When that's done, you should be able to go to ``/tracking/map/`` on your site

(replacing ``tracking`` with whatever prefix you chose to use in your URLconf,

obviously).  The default template relies upon jQuery for its awesomeness, but

you're free to use whatever you would like.



Usage

=====



To display the number of active users there are in one of your templates, make

sure you have ``{% load tracking_tags %}`` somewhere in your template and do

something like this::



    {% visitors_on_site as visitors %}

    


        {{ visitors }} active user{{ visitors|pluralize }}

    



If you also want to show how many people are looking at the same page::



    {% visitors_on_page as same_page %}

    


        {{ same_page }} of {{ visitors }} active user{{ visitors|pluralize }}

        {{ same_page|pluralize:"is,are" }} reading this page

    



If you don't want particular areas of your site to be tracked, you may define a

list of prefixes in your ``settings.py`` using the ``NO_TRACKING_PREFIXES``.  For

example, if you didn't want visits to the ``/family/`` section of your website,

set ``NO_TRACKING_PREFIXES`` to ``['/family/']``.



If you don't want to count certain user-agents, such as Yahoo!'s Slurp and

Google's Googlebot, you may add keywords to your visitor tracking in your

Django administration interface.  Look for "Untracked User-Agents" and add a

keyword that distinguishes a particular user-agent.  Any visitors with the

keyword in their user-agent string will not be tracked.



By default, active users include any visitors within the last 10 minutes.  If

you would like to override that setting, just set ``TRACKING_TIMEOUT`` to however

many minutes you want in your ``settings.py``.



For automatic visitor clean-up, any records older than 24 hours are removed by

default.  If you would like to override that setting, set

``TRACKING_CLEANUP_TIMEOUT`` to however many hours you want in your

``settings.py``.



Good luck!  Please contact me with any questions or concerns you have with the

project!