Metadata-Version: 2.4
Name: djinsight
Version: 0.1.8
Summary: A Django/Wagtail package for tracking page view statistics with Redis and async processing
Home-page: https://github.com/krystianmagdziarz/djinsight
Author: MDigital
Author-email: MDigital <kontakt@mdigital.com.pl>
Maintainer-email: MDigital <kontakt@mdigital.com.pl>
License: MIT License
        
        Copyright (c) 2023 Your Name
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/krystianmagdziarz/djinsight
Project-URL: Documentation, https://djinsight.readthedocs.io/
Project-URL: Repository, https://github.com/krystianmagdziarz/djinsight.git
Project-URL: Bug Tracker, https://github.com/krystianmagdziarz/djinsight/issues
Project-URL: Changelog, https://github.com/krystianmagdziarz/djinsight/blob/main/CHANGELOG.md
Keywords: django,wagtail,analytics,statistics,page-views,redis,celery
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Django
Classifier: Framework :: Django :: 3.2
Classifier: Framework :: Django :: 4.0
Classifier: Framework :: Django :: 4.1
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.0
Classifier: Framework :: Wagtail
Classifier: Framework :: Wagtail :: 3
Classifier: Framework :: Wagtail :: 4
Classifier: Framework :: Wagtail :: 5
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: Django>=3.2
Requires-Dist: wagtail>=3.0
Requires-Dist: redis>=4.0.0
Requires-Dist: celery>=5.0.0
Requires-Dist: django-redis>=5.0.0
Requires-Dist: django-environ>=0.9.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-django>=4.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0; extra == "dev"
Requires-Dist: black>=22.0; extra == "dev"
Requires-Dist: flake8>=4.0; extra == "dev"
Requires-Dist: isort>=5.0; extra == "dev"
Requires-Dist: mypy>=0.900; extra == "dev"
Requires-Dist: factory-boy>=3.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-django>=4.0; extra == "test"
Requires-Dist: pytest-cov>=3.0; extra == "test"
Requires-Dist: factory-boy>=3.0; extra == "test"
Requires-Dist: coverage>=6.0; extra == "test"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 📊 djinsight

A high-performance Django/Wagtail package for real-time page view analytics with Redis and Celery.

[![Django](https://img.shields.io/badge/Django-3.2%20%7C%204.0%20%7C%204.1%20%7C%204.2%20%7C%205.0%20%7C%205.1%20%7C%205.2-092E20?style=flat&logo=django&logoColor=white)](https://www.djangoproject.com/)
[![Wagtail](https://img.shields.io/badge/Wagtail-3.0%20%7C%204.0%20%7C%205.0%20%7C%206.0%20%7C%207.0-43B1B0?style=flat&logo=wagtail&logoColor=white)](https://wagtail.org/)
[![Python](https://img.shields.io/badge/Python-3.8%2B-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![PyPI](https://img.shields.io/pypi/v/djinsight?color=blue&logo=pypi&logoColor=white)](https://pypi.org/project/djinsight/)
[![License](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Published on Django Packages](https://img.shields.io/badge/Published%20on-Django%20Packages-0c3c26)](https://djangopackages.org/packages/p/djinsight/)


## 🚀 Live Demo Screenshots

See djinsight in action with our comprehensive example application:

### Articles List
![djinsight Dashboard](docs/images/1.png)
*Main articles list with counters*

### Article Analytics 
![Article Detail View](docs/images/2.png)
*Individual article page with live view counters and modular statistics components*

### Analytics Demo
![Analytics Components](docs/images/3.png)
*Demonstration of djinsight's modular template tags and live statistics counter*

### E-commerce Integration
![Product Analytics](docs/images/4.png)
*Product pages with analytics tracking showing cross-content type support*

### Popular Content Overview
![Popular Content](docs/images/5.png)
*Dashboard showing most popular articles, products, and courses with real-time view counts*

---

## 🔧 How It Works

djinsight implements a **two-tier architecture** for maximum performance and reliability:

### 🚀 Tier 1: Real-time Data Collection (Redis)
- **Instant Tracking**: When a user visits a page, JavaScript sends an async request to djinsight's API
- **Redis Storage**: View data is immediately stored in Redis with sub-millisecond write times
- **Session Management**: Unique visitors are tracked using Django's session framework
- **Smart Key Structure**: Uses content-type specific Redis keys (`djinsight:counter:blog.article:123`)
- **No Database Blocking**: Zero impact on page load times - all writes go to Redis first

### 🔄 Tier 2: Background Processing (Celery)
- **Batch Processing**: Celery tasks periodically move data from Redis to PostgreSQL/MySQL
- **Data Aggregation**: Daily summaries are generated for efficient historical queries  
- **Automatic Cleanup**: Old detailed logs are cleaned up while preserving summaries
- **Fault Tolerance**: If database is down, data accumulates safely in Redis

### 🛡️ Reliability Features
- **Backward Compatibility**: Supports both new and legacy Redis key formats
- **Graceful Degradation**: Works even if Celery workers are temporarily down
- **Error Recovery**: Failed batch processing can be retried without data loss
- **Conflict Resolution**: Content-type separation prevents ID conflicts between models

## ✨ Features

- **🌐 Universal Model Support**: Works with any Django model via mixin inheritance
- **🧩 Modular Template Tags**: Individual components for flexible UI design
- **⚡ Real-time Tracking**: JavaScript-based view counting with async Redis storage
- **🚄 High Performance**: Redis pipeline for fast data writes, Celery for background processing
- **👥 Session-based Unique Visitors**: Accurate unique view counting using Django sessions
- **🔒 Permission Control**: Configurable access restrictions for statistics
- **🏷️ Template Tags**: Easy integration with simple template tags
- **📈 Live Statistics**: Real-time stats display with auto-refresh
- **🔄 Automatic Data Processing**: Background tasks for Redis → Database sync
- **🧹 Data Cleanup**: Automatic cleanup of old tracking data
- **🔧 Admin Interface**: Django admin integration for viewing statistics

## 📋 Metrics & Functions

### 📊 Core Metrics Collected
- **📈 Total Views**: Complete view count across all time
- **👥 Unique Views**: Session-based unique visitor tracking
- **📅 Time-based Views**: Today, this week, this month counters
- **⏰ Timestamps**: First view and last view tracking
- **🔗 URL Tracking**: Full request path and referrer information
- **📱 User Agent**: Browser and device information
- **🌍 IP Address**: Geographic tracking (privacy-compliant)

### 🛠️ Key Functions
- **⚡ Live Counters**: Real-time updating statistics with configurable refresh rates
- **📊 Historical Analysis**: Daily/weekly/monthly trend analysis
- **🔍 Content Performance**: Compare performance across different content types
- **📈 Popular Content**: Identify trending and top-performing pages
- **👥 Visitor Patterns**: Unique vs returning visitor analysis
- **🕐 Time Series Data**: View patterns over time with granular control
- **🔄 Data Export**: Export analytics data for external analysis
- **📱 API Access**: REST API for custom integrations and dashboards

### 🏷️ Template Components
- **📊 `total_views_stat`**: Display total view counts
- **👥 `unique_views_stat`**: Show unique visitor numbers  
- **⏰ `last_viewed_stat`**: Last visit timestamp
- **🎯 `first_viewed_stat`**: First view tracking
- **📅 `views_today_stat`**: Today's view count
- **📆 `views_week_stat`**: Weekly view statistics
- **📊 `views_month_stat`**: Monthly performance
- **🔄 `live_stats_counter`**: Auto-refreshing live counter

## 🆚 djinsight vs Google Analytics

### 🏆 **djinsight Advantages**

| Feature | 📊 djinsight | 📈 Google Analytics |
|---------|-------------|-------------------|
| **🚀 Performance** | Sub-millisecond Redis writes | ~100-500ms external requests |
| **🔒 Privacy** | Your servers, full control | Google's servers, limited control |
| **📱 Real-time** | Instant live counters | 24-48h delay for reports |
| **🎨 Customization** | Full template control | Limited widget customization |
| **💾 Data Ownership** | Your database, permanent | Google's data, subject to changes |
| **🛡️ GDPR Compliance** | Built-in privacy controls | Requires complex cookie consent |
| **📊 Granular Control** | Per-model, per-object tracking | Page-level only |
| **🔧 Integration** | Native Django/Wagtail | JavaScript embed only |
| **💰 Cost** | Open source, free | Free tier limitations |

### 📈 **Google Analytics Advantages**

| Feature | 📈 Google Analytics | 📊 djinsight |
|---------|-------------------|-------------|
| **🌍 External Traffic Analysis** | Full referrer tracking | Basic referrer only |
| **🎯 Advanced Segmentation** | Extensive user segments | Session-based only |
| **📊 E-commerce Tracking** | Built-in funnel analysis | Manual implementation |
| **🔍 Search Console Integration** | SEO data integration | No SEO features |
| **📱 Mobile App Tracking** | Native mobile support | Web-only focus |
| **🤖 Machine Learning** | AI-powered insights | Manual analysis |

### 🤝 **Best Practice: Use Both**

Many sites use **djinsight + Google Analytics** together:

- **📊 djinsight**: Internal dashboards, real-time stats, GDPR-compliant tracking
- **📈 Google Analytics**: Marketing analysis, SEO insights, external traffic sources
- **🔄 Hybrid Approach**: djinsight for app performance, GA for marketing metrics

## 📦 Quick Installation

```bash
pip install djinsight
```

Add to your Django settings and URLs:

```python
# settings.py
INSTALLED_APPS = [
    # ... other apps
    'djinsight',
]

# urls.py  
urlpatterns = [
    # ... other URLs
    path('djinsight/', include('djinsight.urls')),
]
```

Add analytics to your models:

```python
from djinsight.models import PageViewStatisticsMixin

class Article(models.Model, PageViewStatisticsMixin):
    title = models.CharField(max_length=200)
    # ... your fields
```

Add tracking to your templates:

```html
{% load djinsight_tags %}
{% page_view_tracker obj=article %}
<p>Views: {% total_views_stat obj=article %}</p>
```

## 📚 Documentation

- **📖 [Complete Documentation](docs/README.md)** - Full documentation index
- **📦 [Installation Guide](docs/installation.md)** - Step-by-step setup
- **⚡ [Quick Start](docs/quick-start.md)** - Get running in 5 minutes
- **🔒 [Permission Control](docs/permission-control.md)** - Access control and security
- **🏷️ [Template Tags](docs/template-tags.md)** - Complete reference
- **🎨 [Template Examples](docs/template-examples.md)** - Implementation examples
- **🔧 [Configuration](docs/configuration.md)** - Advanced settings
- **📊 [Analytics Usage](docs/analytics.md)** - Advanced features
- **🚄 [Performance](docs/performance.md)** - Optimization tips
- **🔑 [Redis Structure](docs/redis-structure.md)** - Understanding Redis keys
- **⚙️ [Management Commands](docs/management-commands.md)** - CLI tools

## 👨‍💻 Development

- **🤝 [Contributing Guide](docs/contributing.md)** - How to contribute
- **📄 [License](docs/license.md)** - MIT License details
- **🔄 [Changelog](CHANGELOG.md)** - Version history
- **🖼️ [Demo Gallery](docs/demo-gallery.md)** - Visual showcase

## 📋 Requirements

- 🐍 Python 3.8+
- 🎯 Django 3.2+
- 🚀 Redis 4.0+
- 🔄 Celery 5.0+
- 📦 django-redis
- 🌍 django-environ (for environment variable configuration)
- 🌐 Optional: Wagtail 3.0+ (for Wagtail integration)

## 🔗 Links

- **📦 [PyPI Package](https://pypi.org/project/djinsight/)**
- **🐙 [GitHub Repository](https://github.com/krystianmagdziarz/djinsight)**
- **🐛 [Issue Tracker](https://github.com/krystianmagdziarz/djinsight/issues)**
- **💬 [Discussions](https://github.com/krystianmagdziarz/djinsight/discussions)**

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.
