django-visitor-tracker 0.1.0

Visitor tracking middleware for Django with admin charts

django-visitor-tracker

How Users Can Use the Package (After Installing from PyPI)

Assumption:
The user has already installed the package using:

pip install django-visitor-tracker  

1. Enable in settings.py

INSTALLED_APPS = [
    ...,
    'django_visitor_tracker',   # note the underscore
]

MIDDLEWARE = [
    # If you want to record request.user, place this middleware after AuthenticationMiddleware
    'django.contrib.auth.middleware.AuthenticationMiddleware',
    ...,
    'django_visitor_tracker.middleware.RequestLoggingMiddleware',
]

Note:
The module/app name inside Django is django_visitor_tracker (with an underscore).
The PyPI package name is django-visitor-tracker (with a dash).

2. Add URLs (for API endpoints)

project/urls.py:

from django.urls import path, include
from django.contrib import admin

urlpatterns = [
    path('admin/', admin.site.urls),
    path('visitor-tracker/', include('django_visitor_tracker.urls')),
]

Available endpoints:

Endpoint Description
GET /visitor-tracker/stats/?period=day&span=30 Returns time-series data (JSON)
GET /visitor-tracker/counts/ Returns summary counts for today/week/month/year (JSON)

3. Run Migrations

python manage.py makemigrations django_visitor_tracker
python manage.py migrate

4. Local Testing

Start your development server:

python manage.py runserver  

Then open the Django Admin (/admin/) →
You’ll see the Visitor Log model (or whatever the model name is).
The change-list page will include charts generated by Matplotlib (as base64-encoded PNGs).

How it Works in the Admin Panel (Detailed Explanation)

The package defines a custom LogEntryAdmin in admin.py that overrides the changelist_view method.
Here’s what happens internally:

It fetches log data from the LogEntry table (based on timestamp, OS, IP, etc.).

It creates two Matplotlib charts:

A time-based chart (unique IPs over time)

An OS distribution chart

The charts are encoded in base64 and passed to the admin template.

The template (templates/admin/django_visitor_tracker/logentry/change_list.html) renders them as inline images:

<img src="data:image/png;base64,{{ chart_base64 }}">

This means the user doesn’t need any extra configuration to view the charts —
as long as APP_DIRS = True in Django’s template settings so that the built-in templates are discovered.

How to Use It in the Frontend (Simple Examples)

A) Fetch Summary Counts (for KPI Display)

JavaScript Example:

fetch('/visitor-tracker/counts/')
  .then(r => r.json())
  .then(data => {
    const c = data.summary;
    document.getElementById('vis-today').textContent = c.today;
    document.getElementById('vis-week').textContent = c.week;
    document.getElementById('vis-month').textContent = c.month;
    document.getElementById('vis-year').textContent = c.year;
  });

HTML Example:

<div>
  <div>Today: <span id="vis-today">…</span></div>
  <div>This week: <span id="vis-week">…</span></div>
  <div>This month: <span id="vis-month">…</span></div>
  <div>This year: <span id="vis-year">…</span></div>
</div>

B) Fetch Time-Series Data and Plot with Chart.js (Client-Side)

The Django Admin uses Matplotlib internally,
but on the frontend you can display the same data using Chart.js.

HTML + JS Example:

<canvas id="visChart" width="800" height="250"></canvas>
<script src="https://cdn.jsdelivr.net/npm/chart.js"></script>
<script>
fetch('/visitor-tracker/stats/?period=day&span=30')
  .then(r => r.json())
  .then(payload => {
    const labels = payload.data.map(d => new Date(d.period).toLocaleDateString());
    const values = payload.data.map(d => d.unique_ips);
    new Chart(document.getElementById('visChart'), {
      type: 'line',
      data: {
        labels: labels,
        datasets: [{ label: 'Unique IPs', data: values, fill: false }]
      },
      options: {}
    });
  });
</script>

✅ In summary:
Once installed and added to INSTALLED_APPS,
the package automatically logs each request (IP, browser, OS, user),
provides ready-to-use API endpoints, and shows built-in charts in the admin panel —
no extra setup required.