djangocms-ab-testing 0.1.0__tar.gz

djangocms_ab_testing-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergei Gordeichuk
+
+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.

djangocms_ab_testing-0.1.0/PKG-INFO

@@ -0,0 +1,205 @@
+Metadata-Version: 2.4
+Name: djangocms-ab-testing
+Version: 0.1.0
+Summary: A/B testing plugin for django CMS with round-robin assignment, cookie-based persistence, event tracking, and an admin dashboard.
+Author: Sergei Gordeichuk
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/sgordeychuk/djangocms-ab-testing
+Project-URL: Documentation, https://github.com/sgordeychuk/djangocms-ab-testing#readme
+Project-URL: Repository, https://github.com/sgordeychuk/djangocms-ab-testing
+Project-URL: Issues, https://github.com/sgordeychuk/djangocms-ab-testing/issues
+Keywords: django-cms,ab-testing,split-testing,conversion-optimization,cms-plugin,django,a-b-testing,multivariate-testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django CMS
+Classifier: Framework :: Django CMS :: 3.11
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django>=3.2
+Requires-Dist: django-cms>=3.11
+Requires-Dist: django-import-export>=3.0
+Requires-Dist: user-agents>=2.0
+Dynamic: license-file
+
+# djangocms-ab-testing
+
+[![PyPI version](https://img.shields.io/pypi/v/djangocms-ab-testing.svg)](https://pypi.org/project/djangocms-ab-testing/)
+[![Python versions](https://img.shields.io/pypi/pyversions/djangocms-ab-testing.svg)](https://pypi.org/project/djangocms-ab-testing/)
+[![Django versions](https://img.shields.io/badge/django-3.2%20%7C%204.2-blue.svg)](https://pypi.org/project/djangocms-ab-testing/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+A full-featured **A/B testing** (split testing) plugin for **django CMS**. Run conversion optimization experiments directly in the CMS page editor with round-robin variant assignment, cookie-based persistence, client-side event tracking, and a built-in admin dashboard with Chart.js visualizations.
+
+## Features
+
+- **CMS plugin-based setup** - Add A/B test containers and variants directly in the django CMS page editor
+- **Round-robin assignment** - Fair variant distribution using an atomic database counter
+- **Cookie persistence** - Visitors see the same variant for 30 days (`ab_variant_<slug>`)
+- **Event tracking API** - POST events to `/api/ab-event/` with CSRF protection
+- **Auto "view" tracking** - Fires automatically when a variant is rendered
+- **Bootstrap modal tracking** - Tracks `shown.bs.modal`, `hidden.bs.modal`, and CTA button clicks
+- **Configurable actions** - Define custom tracking events via `AB_TESTING_VALID_ACTIONS` setting
+- **Admin dashboard** - Chart.js-powered visualizations with summary cards, per-variant stats, daily trends, and conversion rate charts
+- **Distribution breakdowns** - Analyze results by device type, browser, OS, and screen size
+- **Filtering** - Filter dashboard data by date range and device properties
+- **CSV export** - Export event data via django-import-export
+- **Cache control** - Pages with A/B tests automatically get `Cache-Control: private, no-store`
+
+## Screenshots
+
+### Light theme
+![Dashboard - Light theme](docs/ab_test_screenshot_light.png)
+
+### Dark theme
+![Dashboard - Dark theme](docs/ab_test_screenshot_dark.png)
+
+## Installation
+
+```sh
+pip install djangocms-ab-testing
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "djangocms_ab_testing",
+]
+```
+
+Add the middleware (after `SessionMiddleware`):
+
+```python
+MIDDLEWARE = [
+    # ...
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "djangocms_ab_testing.middleware.ABCookieMiddleware",
+    # ...
+]
+```
+
+Add the URL config:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    # ...
+    path("api/", include("djangocms_ab_testing.urls")),
+]
+```
+
+Run migrations:
+
+```sh
+python manage.py migrate djangocms_ab_testing
+```
+
+## Usage
+
+### 1. Create an AB Test
+
+Go to **Django Admin > AB Tests** and create a test with a name and slug.
+
+### 2. Add CMS Plugins
+
+In the django CMS page editor:
+
+1. Add an **A/B Test Container** plugin and link it to your test
+2. Inside the container, add **A/B Test Variant** plugins (e.g. variant key `A`, `B`)
+3. Add your content inside each variant
+
+### 3. Track Events
+
+Include the tracking script in your template:
+
+```html
+<script src="{% static 'djangocms_ab_testing/js/ab_tracking.js' %}"></script>
+```
+
+The script auto-initializes, fires a `view` event when the variant is rendered, and tracks Bootstrap modal events (`shown.bs.modal`, `hidden.bs.modal`). Add the `ab-request-btn` class to CTA buttons inside modals to track conversion clicks.
+
+For custom tracking, call `window.initABTracking()` after dynamic content loads.
+
+### 4. View Results
+
+Open any AB Test in the admin to see the dashboard with:
+
+- Summary cards (total events, unique sessions, counter)
+- Per-variant stats table (views, opens, requests, closes, conversion rate)
+- Daily trends and conversion rate charts
+- Distribution breakdowns by device, browser, OS, screen size
+- Filterable by date range and device properties
+- CSV export via django-import-export
+
+## Configuration
+
+### Custom Tracking Actions
+
+By default, the following actions are tracked: `view`, `opened`, `closed`, `requested`.
+
+To define custom actions, add `AB_TESTING_VALID_ACTIONS` to your Django settings:
+
+```python
+AB_TESTING_VALID_ACTIONS = {"view", "opened", "closed", "requested", "submitted", "purchased"}
+```
+
+The event tracking API will only accept actions in this set. The admin dashboard and seed command will also use these actions automatically.
+
+## How It Works
+
+- **Variant assignment**: Round-robin via atomic database counter
+- **Persistence**: 30-day cookie per test (`ab_variant_<slug>`)
+- **Cache**: Pages with A/B tests get `Cache-Control: private, no-store`
+- **Events**: Tracked via POST to `/api/ab-event/` with CSRF protection
+
+## Management Commands
+
+```sh
+python manage.py seed_ab_data --events 500 --days 30
+```
+
+Generates dummy event data for dashboard testing.
+
+## Publishing to PyPI
+
+1. Install build tools:
+
+```sh
+pip install build twine
+```
+
+2. Build the package:
+
+```sh
+python -m build
+```
+
+3. Upload to TestPyPI first:
+
+```sh
+twine upload --repository testpypi dist/*
+```
+
+4. Upload to PyPI:
+
+```sh
+twine upload dist/*
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/sgordeychuk/djangocms-ab-testing).
+
+## License
+
+MIT

djangocms_ab_testing-0.1.0/README.md

@@ -0,0 +1,174 @@
+# djangocms-ab-testing
+
+[![PyPI version](https://img.shields.io/pypi/v/djangocms-ab-testing.svg)](https://pypi.org/project/djangocms-ab-testing/)
+[![Python versions](https://img.shields.io/pypi/pyversions/djangocms-ab-testing.svg)](https://pypi.org/project/djangocms-ab-testing/)
+[![Django versions](https://img.shields.io/badge/django-3.2%20%7C%204.2-blue.svg)](https://pypi.org/project/djangocms-ab-testing/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+A full-featured **A/B testing** (split testing) plugin for **django CMS**. Run conversion optimization experiments directly in the CMS page editor with round-robin variant assignment, cookie-based persistence, client-side event tracking, and a built-in admin dashboard with Chart.js visualizations.
+
+## Features
+
+- **CMS plugin-based setup** - Add A/B test containers and variants directly in the django CMS page editor
+- **Round-robin assignment** - Fair variant distribution using an atomic database counter
+- **Cookie persistence** - Visitors see the same variant for 30 days (`ab_variant_<slug>`)
+- **Event tracking API** - POST events to `/api/ab-event/` with CSRF protection
+- **Auto "view" tracking** - Fires automatically when a variant is rendered
+- **Bootstrap modal tracking** - Tracks `shown.bs.modal`, `hidden.bs.modal`, and CTA button clicks
+- **Configurable actions** - Define custom tracking events via `AB_TESTING_VALID_ACTIONS` setting
+- **Admin dashboard** - Chart.js-powered visualizations with summary cards, per-variant stats, daily trends, and conversion rate charts
+- **Distribution breakdowns** - Analyze results by device type, browser, OS, and screen size
+- **Filtering** - Filter dashboard data by date range and device properties
+- **CSV export** - Export event data via django-import-export
+- **Cache control** - Pages with A/B tests automatically get `Cache-Control: private, no-store`
+
+## Screenshots
+
+### Light theme
+![Dashboard - Light theme](docs/ab_test_screenshot_light.png)
+
+### Dark theme
+![Dashboard - Dark theme](docs/ab_test_screenshot_dark.png)
+
+## Installation
+
+```sh
+pip install djangocms-ab-testing
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "djangocms_ab_testing",
+]
+```
+
+Add the middleware (after `SessionMiddleware`):
+
+```python
+MIDDLEWARE = [
+    # ...
+    "django.contrib.sessions.middleware.SessionMiddleware",
+    "djangocms_ab_testing.middleware.ABCookieMiddleware",
+    # ...
+]
+```
+
+Add the URL config:
+
+```python
+from django.urls import include, path
+
+urlpatterns = [
+    # ...
+    path("api/", include("djangocms_ab_testing.urls")),
+]
+```
+
+Run migrations:
+
+```sh
+python manage.py migrate djangocms_ab_testing
+```
+
+## Usage
+
+### 1. Create an AB Test
+
+Go to **Django Admin > AB Tests** and create a test with a name and slug.
+
+### 2. Add CMS Plugins
+
+In the django CMS page editor:
+
+1. Add an **A/B Test Container** plugin and link it to your test
+2. Inside the container, add **A/B Test Variant** plugins (e.g. variant key `A`, `B`)
+3. Add your content inside each variant
+
+### 3. Track Events
+
+Include the tracking script in your template:
+
+```html
+<script src="{% static 'djangocms_ab_testing/js/ab_tracking.js' %}"></script>
+```
+
+The script auto-initializes, fires a `view` event when the variant is rendered, and tracks Bootstrap modal events (`shown.bs.modal`, `hidden.bs.modal`). Add the `ab-request-btn` class to CTA buttons inside modals to track conversion clicks.
+
+For custom tracking, call `window.initABTracking()` after dynamic content loads.
+
+### 4. View Results
+
+Open any AB Test in the admin to see the dashboard with:
+
+- Summary cards (total events, unique sessions, counter)
+- Per-variant stats table (views, opens, requests, closes, conversion rate)
+- Daily trends and conversion rate charts
+- Distribution breakdowns by device, browser, OS, screen size
+- Filterable by date range and device properties
+- CSV export via django-import-export
+
+## Configuration
+
+### Custom Tracking Actions
+
+By default, the following actions are tracked: `view`, `opened`, `closed`, `requested`.
+
+To define custom actions, add `AB_TESTING_VALID_ACTIONS` to your Django settings:
+
+```python
+AB_TESTING_VALID_ACTIONS = {"view", "opened", "closed", "requested", "submitted", "purchased"}
+```
+
+The event tracking API will only accept actions in this set. The admin dashboard and seed command will also use these actions automatically.
+
+## How It Works
+
+- **Variant assignment**: Round-robin via atomic database counter
+- **Persistence**: 30-day cookie per test (`ab_variant_<slug>`)
+- **Cache**: Pages with A/B tests get `Cache-Control: private, no-store`
+- **Events**: Tracked via POST to `/api/ab-event/` with CSRF protection
+
+## Management Commands
+
+```sh
+python manage.py seed_ab_data --events 500 --days 30
+```
+
+Generates dummy event data for dashboard testing.
+
+## Publishing to PyPI
+
+1. Install build tools:
+
+```sh
+pip install build twine
+```
+
+2. Build the package:
+
+```sh
+python -m build
+```
+
+3. Upload to TestPyPI first:
+
+```sh
+twine upload --repository testpypi dist/*
+```
+
+4. Upload to PyPI:
+
+```sh
+twine upload dist/*
+```
+
+## Contributing
+
+Contributions are welcome! Please open an issue or submit a pull request on [GitHub](https://github.com/sgordeychuk/djangocms-ab-testing).
+
+## License
+
+MIT

djangocms_ab_testing-0.1.0/djangocms_ab_testing/ab_utils.py

@@ -0,0 +1,42 @@
+from user_agents import parse as ua_parse
+
+from djangocms_ab_testing.models import ABCounter
+
+COOKIE_NAME_PREFIX = "ab_variant_"
+COOKIE_MAX_AGE = 60 * 60 * 24 * 30  # 30 days
+
+
+def get_ab_variant(request, test_name, variant_keys):
+    """
+    Get the variant for this request. Checks cookie first, then round-robin.
+    Queues the cookie to be set in the response via middleware.
+    """
+    cookie_name = COOKIE_NAME_PREFIX + test_name
+    variant_key = request.COOKIES.get(cookie_name)
+
+    if variant_key and variant_key in variant_keys:
+        return variant_key
+
+    # Assign via round-robin
+    variant_key = ABCounter.next_variant(test_name, list(variant_keys))
+
+    # Queue cookie to be set by middleware
+    if not hasattr(request, '_ab_cookies_to_set'):
+        request._ab_cookies_to_set = {}
+    request._ab_cookies_to_set[cookie_name] = variant_key
+
+    return variant_key
+
+
+def get_device_info(request):
+    """Parse device info from User-Agent header."""
+    ua_string = request.META.get('HTTP_USER_AGENT', '')
+    ua = ua_parse(ua_string)
+    return {
+        'device_type': 'mobile' if ua.is_mobile else ('tablet' if ua.is_tablet else 'desktop'),
+        'browser': str(ua.browser.family),
+        'browser_version': str(ua.browser.version_string),
+        'os': str(ua.os.family),
+        'os_version': str(ua.os.version_string),
+        'is_bot': ua.is_bot,
+    }