Name | django-silent-mammoth-whistle JSON |
Version |
1.2.5
JSON |
| download |
home_page | None |
Summary | A super-simple user analytics tool that tracks user behaviour based on web requests to your Django app. |
upload_time | 2024-09-18 08:43:33 |
maintainer | None |
docs_url | None |
author | None |
requires_python | >=3.10 |
license | BSD-2-Clause |
keywords |
analytics
user
tracking
|
VCS |
|
bugtrack_url |
|
requirements |
No requirements were recorded.
|
Travis-CI |
No Travis.
|
coveralls test coverage |
No coveralls.
|
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": "analytics, user, tracking",
"author": null,
"author_email": "Ben Michie <benopotamus@tinku.net>",
"download_url": "https://files.pythonhosted.org/packages/67/ec/f5c0389a2aa8e2ee59f7c9dacc6abd206bca4eb4bbc6a1694276a05179e4/django_silent_mammoth_whistle-1.2.5.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": "1.2.5",
"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": [
"analytics",
" user",
" tracking"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "4a83c08dcd428ca1f1a21a0d325e0abd150e176f41af4666c7438de0b5abb0b2",
"md5": "818447513c0290ede8fbb301459596b8",
"sha256": "80a5f4a82fc6581305945958ec8e371757d643fb9c9b2e3496990c1294766cc2"
},
"downloads": -1,
"filename": "django_silent_mammoth_whistle-1.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "818447513c0290ede8fbb301459596b8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 143817,
"upload_time": "2024-09-18T08:43:31",
"upload_time_iso_8601": "2024-09-18T08:43:31.676071Z",
"url": "https://files.pythonhosted.org/packages/4a/83/c08dcd428ca1f1a21a0d325e0abd150e176f41af4666c7438de0b5abb0b2/django_silent_mammoth_whistle-1.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "67ecf5c0389a2aa8e2ee59f7c9dacc6abd206bca4eb4bbc6a1694276a05179e4",
"md5": "81ee05ced40c87e021d24c507fd22dd1",
"sha256": "610a7d143c0dd832f3892bfb406fd8f4bd348ae8bd184e832b3d67626ca56ed1"
},
"downloads": -1,
"filename": "django_silent_mammoth_whistle-1.2.5.tar.gz",
"has_sig": false,
"md5_digest": "81ee05ced40c87e021d24c507fd22dd1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 138941,
"upload_time": "2024-09-18T08:43:33",
"upload_time_iso_8601": "2024-09-18T08:43:33.964806Z",
"url": "https://files.pythonhosted.org/packages/67/ec/f5c0389a2aa8e2ee59f7c9dacc6abd206bca4eb4bbc6a1694276a05179e4/django_silent_mammoth_whistle-1.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-09-18 08:43:33",
"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"
}