# Django Amplitude
Integration between Django and [Amplitude.com](https://amplitude.com/) to help send events via the [Amplitude HTTP API (v2)](https://developers.amplitude.com/docs/http-api-v2)
## Quick start
### Installation
```bash
pip install django-amplitude
```
Add `amplitude` to your `INSTALLED_APPS`. If they are not already the Django `sessions` app must also be added:
```python
INSTALLED_APPS = [
...
'django.contrib.sessions',
...
'amplitude',
]
```
If you do not have it already you must also add the Django `django.contrib.sessions.middleware.SessionMiddleware`. Then add the ampliturde `SessionInfo` middleware after the `SessionMiddleware`:
```python
MIDDLEWARE = [
...
'django.contrib.sessions.middleware.SessionMiddleware',
...
'amplitude.middleware.SessionInfo',
]
```
Now set your Amplitude API key and user / group options in your `settings.py`:
```python
# Settings > Projects > <Your project> > General > API Key
AMPLITUDE_API_KEY = '<amplitude-project-api-key>'
# You can also choose if you want to include user and group data (Default False)
AMPLITUDE_INCLUDE_USER_DATA = False
AMPLITUDE_INCLUDE_GROUP_DATA = False
```
*Note: If you want to include user or group data you must ensure the [Django auth is setup correctly](https://docs.djangoproject.com/en/3.0/topics/auth/#installation). This includes adding `django.contrib.auth` and `django.contrib.contenttypes` to `INSTALLED_APPS` and `django.contrib.auth.middleware.AuthenticationMiddleware` to `MIDDLEWARE`*.
For more information on the above settings see the [configuration settings](#configuration-settings) section.
## Usage
### Page view events
If you want to send an event to Amplitude on every page view you can use the django-amplitude `SendPageViewEvent` middleware to your `MIDDLEWARE` in your Django settings.
This will automatically create an event called `Page view` with all the information it's possible to pull from the Django request object such as URL path and parameters, user agent info, IP info, user info etc.
It must be placed after the `amplitude.middleware.SessionInfo` middleware:
```python
MIDDLEWARE = [
'django.contrib.sessions.middleware.SessionMiddleware',
...
'amplitude.middleware.SessionInfo',
'amplitude.middleware.SendPageViewEvent',
]
```
While using `SendPageViewEvent` if there are certain URLs that you do not want to update Amplitude with you can use the `AMPLITUDE_IGNORE_URLS` setting. This setting take a list of relative urls or URL names. Relative URLS most match exactly so need to start with a forward slash (`/`)
```python
AMPLITUDE_IGNORE_URLS = ['my_url_name', '/testurl']
```
### Sending events manually
If you want to send your own events:
```python
from amplitude import Amplitude
amplitude = Amplitude()
event_data = amplitude.build_event_data(
event_type='Some event type',
request=request,
)
amplitude.send_events([event_data])
```
The above request will include URL and HTTP header info in the `event_properties`. If you want to override the event properties you can pass them through to `build_event_data`:
```python
event_data = amplitude.build_event_data(
event_type='User purchase',
request=request,
event_properties={'products': ['laptop', 'phone']}
)
```
### build_event_data missing event data keys
The `build_event_data` method (and in extension the `SendPageViewEvent` middleware) currently does not send the following keys from `UploadRequestBody` type in [Amplitude HTTP API (v2)](https://developers.amplitude.com/docs/http-api-v2):
* event_id
* app_version
* carrier
* price
* quantity
* revenue
* productId
* revenueType
* idfa
* idfv
* adid
* android_id
* dma
* insert_id
If you want to record an event in Amplitude with any of these keys you must use build and send your own event data using `amplitude.build_event_data` where you can pass any of the above as kwargs:
```python
amplitude = Amplitude()
event_data = amplitude.build_event_data(
event_type='Some event type',
request=request,
app_version='1.0.0',
)
amplitude.send_events([event_data])
```
### Building you own event
If you are not happy with the data from `build_event_data` you can build you own event data based on the `UploadRequestBody` type in [Amplitude HTTP API (v2)](https://developers.amplitude.com/docs/http-api-v2). If you want to do this There are a few helper functions to build different parts of the event data from the Django request object:
```python
amplitude.event_properties_from_request(request) # Gets URL and HTTP header data
amplitude.device_data_from_request(request) # Gets device info from user agent
amplitude.user_properties_from_request(request) # Gets info from user model
amplitude.group_from_request(request) # Gets the list of groups a user is in
amplitude.location_data_from_ip_address(ip_address) # Gets location data from IP if GeoIP2 is setup
```
* `user_properties_from_request` will return an empty dict if `AMPLITUDE_INCLUDE_USER_DATA` is `False`
* `group_from_request` will return an empty dict if `AMPLITUDE_INCLUDE_GROUP_DATA` is `False`
#### Configuration settings
Below are the different settings that can be overridden. To do so place the setting into your `settings.py`.
```python
# This variable is required when amplitude is added to INSTALLED_APPS
AMPLITUDE_API_KEY = '<amplitude-project-api-key>'
# If the users Django user information is included in the Amplitude event.
# This includes - username, email, full_name, is_staff, is_superuser
AMPLITUDE_INCLUDE_USER_DATA = False
# If the groups the user is a member of is included in the Amplitude event.
# A list of the group names will be sent in the request.
AMPLITUDE_INCLUDE_GROUP_DATA = False
# A list of URLs which `SendPageViewEvent` middleware should not run for.
# Each item in the list can be either a URL or url name
AMPLITUDE_IGNORE_URLS = ['home', '/please/ignore/']
# The minimum permitted length for user_id & device_id fields
# https://developers.amplitude.com/docs/http-api-v2#properties-2
AMPLITUDE_MIN_ID_LENGTH = None
```
Raw data
{
"_id": null,
"home_page": "https://github.com/pyepye/django-amplitude",
"name": "django-amplitude",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6,<4.0",
"maintainer_email": "",
"keywords": "amplitude,analytics,product analytics,saas",
"author": "Matt Pye",
"author_email": "pyematt@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/02/8e/7fdedbe6f6e102ae46cfe02d64cbc94a2e41b9f432daa8d51f16d8117aa5/django_amplitude-0.8.0.tar.gz",
"platform": null,
"description": "# Django Amplitude\n\nIntegration between Django and [Amplitude.com](https://amplitude.com/) to help send events via the [Amplitude HTTP API (v2)](https://developers.amplitude.com/docs/http-api-v2)\n\n\n## Quick start\n\n### Installation\n\n```bash\npip install django-amplitude\n```\n\nAdd `amplitude` to your `INSTALLED_APPS`. If they are not already the Django `sessions` app must also be added:\n\n```python\nINSTALLED_APPS = [\n ...\n 'django.contrib.sessions',\n ...\n 'amplitude',\n]\n```\n\nIf you do not have it already you must also add the Django `django.contrib.sessions.middleware.SessionMiddleware`. Then add the ampliturde `SessionInfo` middleware after the `SessionMiddleware`:\n```python\nMIDDLEWARE = [\n ...\n 'django.contrib.sessions.middleware.SessionMiddleware',\n ...\n 'amplitude.middleware.SessionInfo',\n]\n```\n\nNow set your Amplitude API key and user / group options in your `settings.py`:\n```python\n# Settings > Projects > <Your project> > General > API Key\nAMPLITUDE_API_KEY = '<amplitude-project-api-key>'\n\n# You can also choose if you want to include user and group data (Default False)\nAMPLITUDE_INCLUDE_USER_DATA = False\nAMPLITUDE_INCLUDE_GROUP_DATA = False\n```\n\n*Note: If you want to include user or group data you must ensure the [Django auth is setup correctly](https://docs.djangoproject.com/en/3.0/topics/auth/#installation). This includes adding `django.contrib.auth` and `django.contrib.contenttypes` to `INSTALLED_APPS` and `django.contrib.auth.middleware.AuthenticationMiddleware` to `MIDDLEWARE`*.\n\n\nFor more information on the above settings see the [configuration settings](#configuration-settings) section.\n\n\n\n## Usage\n\n### Page view events\n\nIf you want to send an event to Amplitude on every page view you can use the django-amplitude `SendPageViewEvent` middleware to your `MIDDLEWARE` in your Django settings.\n\nThis will automatically create an event called `Page view` with all the information it's possible to pull from the Django request object such as URL path and parameters, user agent info, IP info, user info etc.\n\nIt must be placed after the `amplitude.middleware.SessionInfo` middleware:\n\n```python\nMIDDLEWARE = [\n 'django.contrib.sessions.middleware.SessionMiddleware',\n ...\n 'amplitude.middleware.SessionInfo',\n 'amplitude.middleware.SendPageViewEvent',\n]\n```\n\nWhile using `SendPageViewEvent` if there are certain URLs that you do not want to update Amplitude with you can use the `AMPLITUDE_IGNORE_URLS` setting. This setting take a list of relative urls or URL names. Relative URLS most match exactly so need to start with a forward slash (`/`)\n\n```python\nAMPLITUDE_IGNORE_URLS = ['my_url_name', '/testurl']\n```\n\n\n### Sending events manually\n\nIf you want to send your own events:\n```python\nfrom amplitude import Amplitude\n\namplitude = Amplitude()\nevent_data = amplitude.build_event_data(\n event_type='Some event type',\n request=request,\n)\namplitude.send_events([event_data])\n```\n\nThe above request will include URL and HTTP header info in the `event_properties`. If you want to override the event properties you can pass them through to `build_event_data`:\n\n```python\nevent_data = amplitude.build_event_data(\n event_type='User purchase',\n request=request,\n event_properties={'products': ['laptop', 'phone']}\n)\n```\n\n### build_event_data missing event data keys\n\nThe `build_event_data` method (and in extension the `SendPageViewEvent` middleware) currently does not send the following keys from `UploadRequestBody` type in [Amplitude HTTP API (v2)](https://developers.amplitude.com/docs/http-api-v2):\n\n* event_id\n* app_version\n* carrier\n* price\n* quantity\n* revenue\n* productId\n* revenueType\n* idfa\n* idfv\n* adid\n* android_id\n* dma\n* insert_id\n\nIf you want to record an event in Amplitude with any of these keys you must use build and send your own event data using `amplitude.build_event_data` where you can pass any of the above as kwargs:\n\n```python\namplitude = Amplitude()\nevent_data = amplitude.build_event_data(\n event_type='Some event type',\n request=request,\n app_version='1.0.0',\n)\namplitude.send_events([event_data])\n```\n\n\n### Building you own event\n\nIf you are not happy with the data from `build_event_data` you can build you own event data based on the `UploadRequestBody` type in [Amplitude HTTP API (v2)](https://developers.amplitude.com/docs/http-api-v2). If you want to do this There are a few helper functions to build different parts of the event data from the Django request object:\n\n```python\namplitude.event_properties_from_request(request) # Gets URL and HTTP header data\namplitude.device_data_from_request(request) # Gets device info from user agent\namplitude.user_properties_from_request(request) # Gets info from user model\namplitude.group_from_request(request) # Gets the list of groups a user is in\n\namplitude.location_data_from_ip_address(ip_address) # Gets location data from IP if GeoIP2 is setup\n```\n\n* `user_properties_from_request` will return an empty dict if `AMPLITUDE_INCLUDE_USER_DATA` is `False`\n* `group_from_request` will return an empty dict if `AMPLITUDE_INCLUDE_GROUP_DATA` is `False`\n\n\n#### Configuration settings\n\nBelow are the different settings that can be overridden. To do so place the setting into your `settings.py`.\n\n```python\n# This variable is required when amplitude is added to INSTALLED_APPS\nAMPLITUDE_API_KEY = '<amplitude-project-api-key>'\n\n# If the users Django user information is included in the Amplitude event.\n# This includes - username, email, full_name, is_staff, is_superuser\nAMPLITUDE_INCLUDE_USER_DATA = False\n\n# If the groups the user is a member of is included in the Amplitude event.\n# A list of the group names will be sent in the request.\nAMPLITUDE_INCLUDE_GROUP_DATA = False\n\n# A list of URLs which `SendPageViewEvent` middleware should not run for.\n# Each item in the list can be either a URL or url name\nAMPLITUDE_IGNORE_URLS = ['home', '/please/ignore/']\n\n# The minimum permitted length for user_id & device_id fields\n# https://developers.amplitude.com/docs/http-api-v2#properties-2\nAMPLITUDE_MIN_ID_LENGTH = None\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Integration between Django and Amplitude",
"version": "0.8.0",
"project_urls": {
"Homepage": "https://github.com/pyepye/django-amplitude",
"Repository": "https://github.com/pyepye/django-amplitude"
},
"split_keywords": [
"amplitude",
"analytics",
"product analytics",
"saas"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "2a82c96809ba1dec361f0ad8066640a2866d1266eaa0b5644b79803551a9fa86",
"md5": "e835c2fda3a703774134a1b174f8687b",
"sha256": "5c65ebcae8fe594b3488fc2a4d3a1d4dc19937b4078356361e2dd9ab21b8a8a8"
},
"downloads": -1,
"filename": "django_amplitude-0.8.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e835c2fda3a703774134a1b174f8687b",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6,<4.0",
"size": 9191,
"upload_time": "2023-07-13T02:28:55",
"upload_time_iso_8601": "2023-07-13T02:28:55.925144Z",
"url": "https://files.pythonhosted.org/packages/2a/82/c96809ba1dec361f0ad8066640a2866d1266eaa0b5644b79803551a9fa86/django_amplitude-0.8.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "028e7fdedbe6f6e102ae46cfe02d64cbc94a2e41b9f432daa8d51f16d8117aa5",
"md5": "7ebf07224099d1fa5d836599bd299913",
"sha256": "0a7cf92dace22df5f0ba6afa344e2e609870083d452083db2c796902397bea34"
},
"downloads": -1,
"filename": "django_amplitude-0.8.0.tar.gz",
"has_sig": false,
"md5_digest": "7ebf07224099d1fa5d836599bd299913",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6,<4.0",
"size": 9203,
"upload_time": "2023-07-13T02:28:57",
"upload_time_iso_8601": "2023-07-13T02:28:57.516425Z",
"url": "https://files.pythonhosted.org/packages/02/8e/7fdedbe6f6e102ae46cfe02d64cbc94a2e41b9f432daa8d51f16d8117aa5/django_amplitude-0.8.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-13 02:28:57",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pyepye",
"github_project": "django-amplitude",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "django-amplitude"
}
JSON
