Django Silent Mammoth Whistle
#############################
A super-simple user analytics tool that tracks user behaviour based on web requests to your Django app.
It's intended for use with libraries such as `htmx <https://htmx.org>`_, which generally make a web request for each user interaction. It also includes a JavaScript function for tracking purely client-side actions (e.g. things you might use `Alpine.js <https://alpinejs.dev/>`_ for). The UI is designed for small projects where understanding individual user behaviour is useful.
Features
========
* (optional) Automatic tracking of all web requests - no additional code needed in your project
* JavaScript function for tracking client-side actions
* Separate reporting of authenticated and anonymous sessions
* Shows top platforms, top user-agents (using `user-agents <https://pypi.org/project/user-agents/>`_), top viewport sizes, and new users, for each month
* Tracking cookies can be disabled (you just won't see viewport size data)
* All data is stored in a single table with no relations to your project's tables
Requirements
============
Django 4.2+ and Python 3.8+
Installation
============
1. ``pip install django-silent-mammoth-whistle``
2. Add to ``INSTALLED_APPS`` setting - ideally just above the main app::
INSTALLED_APPS = [
...,
"silent_mammoth_whistle",
...,
]
3. Add middleware. At the end is fine::
MIDDLEWARE = [
...,
'silent_mammoth_whistle.middleware.SilentMammothWhistleMiddleware',
]
4. Include the silent mammoth whistle URLconf in your project urls.py. The URL (e.g. ``/mammoth``) can be anything you like::
urlpatterns = [
...,
path('/mammoth', include('silent_mammoth_whistle.urls')),
...,
]
5. Add ``<script src="{% static 'silent_mammoth_whistle/js/whistle.js' %}"></script>`` to your templates
6. Run ``migrations ./manage.py migrate silent_mammoth_whistle``
Configuration
=============
All configuration is optional
settings.py
-----------
``WHISTLE_USER_ID_FIELD``
Defaults to ``'id'``
The name of a ``User`` model attribute that is used as the unqiue user identifier. It is displayed in the UI and is used for determining which web requests belong to which users.
``WHISTLE_AUTO_LOG``
Defaults to ``True``
When True, all web requests are tracked. Disable this feature if you want to record only specific requests.
``WHISTLE_CLIENT_EVENT_PATH``
Defaults to ``'/whistle'``
The url used by the ``whistle`` function in ``whistle.js`` to make web requests using JavaScript.
``WHISTLE_COOKIES``
Defaults to ``True``
When True, a cookie is added to clients and is used with some JavaScript to record viewport dimensions. I don't think this constitutes a "tracking cookie", but if you think it does, and you don't want that, just set this to ``False``.
Usage
=====
By default, silent mammoth whistle will record all web requests (specifically the HTTP method and the URL for each).
You can also record additional data for a request.
.. code-block:: python
request.whistle.request('put a string here')
You can record as much data as you like, and you can make as many of these ``request.whistle.request()`` calls as you like. Silent mammoth whistle is super-simple and all data is cast to strings using ``str()`` before saving. Silent mammoth whistle will merge the strings from all the calls into a single string, separated by a tab when rendered.
Practical example time! This line will record the fields present in a POST request. This could be useful if your form has many optional fields and you want to know which ones were included by the user.
.. code-block:: python
request.whistle.request('fields=' + ", ".join(request.POST.dict().keys()))
When viewing session details in silent mammoth whistle, you'll see 3 columns: time, request, and response. Request is the obvious column to use, but you might like to separate tracking of what the user requested from how the server responded. E.g.
.. code-block:: python
request.whistle.response('fields in error=' + ", ".join(form.errors.dict().keys()))
These calls all start with ``request.`` because silent mammoth whistle adds a ``whistle`` object to the standard Django ``request`` object.
The JavaScript API is similar
.. code-block:: javascript
whistle('Edit dialog box open')
Raw data
{
"_id": null,
"home_page": null,
"name": "django-silent-mammoth-whistle",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "django, analytics, user, tracking",
"author": null,
"author_email": "Ben Michie <benopotamus@tinku.net>",
"download_url": "https://files.pythonhosted.org/packages/16/28/6f06670a38c7e681a0ffcafef9e522e8ddc40b79a2ae822aa7e48db66343/django_silent_mammoth_whistle-2.0.0.tar.gz",
"platform": null,
"description": "Django Silent Mammoth Whistle\n#############################\n\nA super-simple user analytics tool that tracks user behaviour based on web requests to your Django app.\n\nIt's intended for use with libraries such as `htmx <https://htmx.org>`_, which generally make a web request for each user interaction. It also includes a JavaScript function for tracking purely client-side actions (e.g. things you might use `Alpine.js <https://alpinejs.dev/>`_ for). The UI is designed for small projects where understanding individual user behaviour is useful.\n\nFeatures\n========\n\n* (optional) Automatic tracking of all web requests - no additional code needed in your project\n* JavaScript function for tracking client-side actions\n* Separate reporting of authenticated and anonymous sessions\n* Shows top platforms, top user-agents (using `user-agents <https://pypi.org/project/user-agents/>`_), top viewport sizes, and new users, for each month\n* Tracking cookies can be disabled (you just won't see viewport size data)\n* All data is stored in a single table with no relations to your project's tables\n\nRequirements\n============\n\nDjango 4.2+ and Python 3.8+\n\nInstallation\n============\n\n1. ``pip install django-silent-mammoth-whistle``\n\n2. Add to ``INSTALLED_APPS`` setting - ideally just above the main app::\n\n\t\tINSTALLED_APPS = [\n\t\t\t...,\n\t\t\t\"silent_mammoth_whistle\",\n\t\t\t...,\n\t\t]\n\n3. Add middleware. At the end is fine::\n\t\n\t\tMIDDLEWARE = [\n\t\t\t...,\n\t\t\t'silent_mammoth_whistle.middleware.SilentMammothWhistleMiddleware',\n\t\t]\n\t\n4. Include the silent mammoth whistle URLconf in your project urls.py. The URL (e.g. ``/mammoth``) can be anything you like::\n\t\n\t\turlpatterns = [\n\t\t\t...,\n\t\t\tpath('/mammoth', include('silent_mammoth_whistle.urls')),\n\t\t\t...,\n\t\t]\n\t\n5. Add ``<script src=\"{% static 'silent_mammoth_whistle/js/whistle.js' %}\"></script>`` to your templates\n\n6. Run ``migrations ./manage.py migrate silent_mammoth_whistle``\n\nConfiguration\n=============\n\nAll configuration is optional\n\nsettings.py\n-----------\n\n``WHISTLE_USER_ID_FIELD``\n\n\tDefaults to ``'id'``\n\n\tThe name of a ``User`` model attribute that is used as the unqiue user identifier. It is displayed in the UI and is used for determining which web requests belong to which users.\n\n\n``WHISTLE_AUTO_LOG``\n\n\tDefaults to ``True``\n\n\tWhen True, all web requests are tracked. Disable this feature if you want to record only specific requests.\n\n\n``WHISTLE_CLIENT_EVENT_PATH``\n\n\tDefaults to ``'/whistle'``\n\n\tThe url used by the ``whistle`` function in ``whistle.js`` to make web requests using JavaScript.\n\n\n``WHISTLE_COOKIES``\n\n\tDefaults to ``True``\n\n\tWhen True, a cookie is added to clients and is used with some JavaScript to record viewport dimensions. I don't think this constitutes a \"tracking cookie\", but if you think it does, and you don't want that, just set this to ``False``.\n\n\nUsage\n=====\n\nBy default, silent mammoth whistle will record all web requests (specifically the HTTP method and the URL for each).\n\nYou can also record additional data for a request.\n\n.. code-block:: python\n\n\trequest.whistle.request('put a string here')\n\nYou can record as much data as you like, and you can make as many of these ``request.whistle.request()`` calls as you like. Silent mammoth whistle is super-simple and all data is cast to strings using ``str()`` before saving. Silent mammoth whistle will merge the strings from all the calls into a single string, separated by a tab when rendered.\n\nPractical example time! This line will record the fields present in a POST request. This could be useful if your form has many optional fields and you want to know which ones were included by the user.\n\n.. code-block:: python\n\n\trequest.whistle.request('fields=' + \", \".join(request.POST.dict().keys()))\n\nWhen viewing session details in silent mammoth whistle, you'll see 3 columns: time, request, and response. Request is the obvious column to use, but you might like to separate tracking of what the user requested from how the server responded. E.g.\n\n.. code-block:: python\n\n\trequest.whistle.response('fields in error=' + \", \".join(form.errors.dict().keys()))\n\nThese calls all start with ``request.`` because silent mammoth whistle adds a ``whistle`` object to the standard Django ``request`` object.\n\nThe JavaScript API is similar\n\n.. code-block:: javascript\n\n\twhistle('Edit dialog box open')\n",
"bugtrack_url": null,
"license": "BSD-2-Clause",
"summary": "A super-simple user analytics tool that tracks user behaviour based on web requests to your Django app.",
"version": "2.0.0",
"project_urls": {
"Bug Tracker": "https://github.com/benopotamus/django-silent-mammoth-whistle/issues",
"Changelog": "https://github.com/benopotamus/django-silent-mammoth-whistle/blob/main/CHANGELOG.rst",
"Documentation": "https://github.com/benopotamus/django-silent-mammoth-whistle/blob/main/README.rst",
"Homepage": "https://github.com/benopotamus/django-silent-mammoth-whistle",
"Repository": "https://github.com/benopotamus/django-silent-mammoth-whistle"
},
"split_keywords": [
"django",
" analytics",
" user",
" tracking"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "d03d12223ec9ba5488b370e09a6dac7fffd08ab53de09599495d9ddcbd7508b9",
"md5": "458c381994097bca29b5702723c4b609",
"sha256": "250f91929761f5a7131f04eab4a6ae4d541a60205a1d69642f7fb730ddcd813d"
},
"downloads": -1,
"filename": "django_silent_mammoth_whistle-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "458c381994097bca29b5702723c4b609",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 144265,
"upload_time": "2024-10-10T04:40:10",
"upload_time_iso_8601": "2024-10-10T04:40:10.766095Z",
"url": "https://files.pythonhosted.org/packages/d0/3d/12223ec9ba5488b370e09a6dac7fffd08ab53de09599495d9ddcbd7508b9/django_silent_mammoth_whistle-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16286f06670a38c7e681a0ffcafef9e522e8ddc40b79a2ae822aa7e48db66343",
"md5": "c2aadf773d109255556c821c1e1c7520",
"sha256": "67299c3404f8a3a7244fc52d5c2217611a62005307026ee771bcb29a98fefdf0"
},
"downloads": -1,
"filename": "django_silent_mammoth_whistle-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "c2aadf773d109255556c821c1e1c7520",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 139470,
"upload_time": "2024-10-10T04:40:13",
"upload_time_iso_8601": "2024-10-10T04:40:13.539764Z",
"url": "https://files.pythonhosted.org/packages/16/28/6f06670a38c7e681a0ffcafef9e522e8ddc40b79a2ae822aa7e48db66343/django_silent_mammoth_whistle-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-10 04:40:13",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "benopotamus",
"github_project": "django-silent-mammoth-whistle",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "django-silent-mammoth-whistle"
}
JSON
