Metadata-Version: 2.4
Name: django-visitor-tracker
Version: 0.1.0
Summary: Visitor tracking middleware for Django with admin charts
Home-page: https://github.com/ventuno-21/django-visitor-tracker
Author: Ventuno
Classifier: Framework :: Django
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Requires-Dist: matplotlib
Requires-Dist: user-agents
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# 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.  
