{"id":8110,"library":"django-push-notifications","title":"Django Push Notifications","description":"django-push-notifications is a Django library for sending push notifications to mobile devices via services like FCM (Firebase Cloud Messaging), APNS (Apple Push Notification service), and to WebPush-enabled browsers (Chrome, Firefox, Opera). It simplifies device registration and message sending within a Django project. The current version is 3.3.0, and the project maintains an active release cadence with regular updates.","status":"active","version":"3.3.0","language":"en","source_language":"en","source_url":"https://github.com/jazzband/django-push-notifications","tags":["django","push notifications","fcm","apns","webpush","mobile"],"install":[{"cmd":"pip install django-push-notifications","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Optional, required for FCM v1 API.","package":"firebase-admin","optional":true},{"reason":"Required for APNS (async). Pinned to <4.0 in version 3.3.0 due to breaking changes in aioapns v4.","package":"aioapns","optional":false}],"imports":[{"symbol":"GCMDevice","correct":"from push_notifications.models import GCMDevice"},{"symbol":"APNSDevice","correct":"from push_notifications.models import APNSDevice"},{"symbol":"WebPushDevice","correct":"from push_notifications.models import WebPushDevice"}],"quickstart":{"code":"import os\nfrom django.conf import settings\nfrom django.apps import apps\nfrom push_notifications.models import GCMDevice, APNSDevice\n\n# --- Minimal Django settings for standalone execution ---\n# In a real Django project, these settings would be in your settings.py\n# and you would simply import and use the Device models after Django is initialized.\nif not apps.ready:\n    settings.configure(\n        INSTALLED_APPS=[\n            'django.contrib.auth',\n            'django.contrib.contenttypes',\n            'push_notifications'\n        ],\n        # Minimal database settings for demo\n        DATABASES={'default': {'ENGINE': 'django.db.backends.sqlite3', 'NAME': ':memory:'}},\n        PUSH_NOTIFICATIONS_SETTINGS={\n            \"APNS_AUTH_KEY_PATH\": os.environ.get(\"APNS_AUTH_KEY_PATH\", \"/path/to/apns_key.p8\"),\n            \"APNS_AUTH_KEY_ID\": os.environ.get(\"APNS_AUTH_KEY_ID\", \"YOUR_APNS_KEY_ID\"),\n            \"APNS_TEAM_ID\": os.environ.get(\"APNS_TEAM_ID\", \"YOUR_APNS_TEAM_ID\"),\n            \"APNS_APP_ID\": os.environ.get(\"APNS_APP_ID\", \"com.example.app\"),\n            \"GCM_API_KEY\": os.environ.get(\"GCM_API_KEY\", \"YOUR_LEGACY_FCM_SERVER_KEY\"), # For legacy GCM\n            \"FCM_API_KEY\": os.environ.get(\"FCM_API_KEY\", \"/path/to/fcm_v1_credentials.json\"), # For FCM v1\n        },\n        DEFAULT_AUTO_FIELD='django.db.models.BigAutoField', # Recommended for Django 3.2+\n    )\n    apps.populate(settings.INSTALLED_APPS)\n# --- End of minimal Django settings ---\n\nprint(\"Registering a GCM (FCM) device and sending a message...\")\n# Replace 'your_fcm_device_token' with an actual device token\ndevice_gcm, created_gcm = GCMDevice.objects.get_or_create(\n    registration_id=\"your_fcm_device_token\",\n    active=True,\n    user=None # Link to a Django User object if applicable\n)\n\nif created_gcm:\n    print(f\"Created new GCM device: {device_gcm}\")\nelse:\n    print(f\"Found existing GCM device: {device_gcm}\")\n\ntry:\n    response_gcm = device_gcm.send_message(\n        \"Hello from FCM!\",\n        badge=1,\n        extra={\"custom_data\": \"value\"}\n    )\n    print(f\"FCM message sent. Response: {response_gcm}\")\nexcept Exception as e:\n    print(f\"Error sending FCM message: {e}\")\n\nprint(\"\\nRegistering an APNS device and sending a message...\")\n# Replace 'your_apns_device_token' with an actual device token\ndevice_apns, created_apns = APNSDevice.objects.get_or_create(\n    registration_id=\"your_apns_device_token\",\n    active=True,\n    user=None\n)\n\nif created_apns:\n    print(f\"Created new APNS device: {device_apns}\")\nelse:\n    print(f\"Found existing APNS device: {device_apns}\")\n\ntry:\n    response_apns = device_apns.send_message(\n        message=\"Hello from APNS!\",\n        badge=1,\n        sound=\"default\",\n        category=\"my_category\",\n        mutable_content=1, # Note: integer 1 or 0 for >=3.2.1\n        extra={\"custom_data\": \"value\"}\n    )\n    print(f\"APNS message sent. Response: {response_apns}\")\nexcept Exception as e:\n    print(f\"Error sending APNS message: {e}\")\n\n# For WebPush, you would typically handle subscription via JavaScript in the frontend\n# and then create/use a WebPushDevice instance similarly to send notifications.","lang":"python","description":"This quickstart demonstrates how to configure settings, register devices, and send notifications using both FCM (Firebase Cloud Messaging, via GCMDevice) and APNS (Apple Push Notification service) models. Note: The `settings.configure` and `apps.populate` lines are for running this example script standalone. In a typical Django project, you'd configure `settings.py` and then directly import and use the device models."},"warnings":[{"fix":"Ensure `aioapns` is installed at a version less than 4.0. You may need to reinstall `django-push-notifications` to get the correct transitive dependency (`pip install -U django-push-notifications`).","message":"The `aioapns` dependency was pinned to `<4.0` in `django-push-notifications` version 3.3.0 to prevent breaking changes introduced in `aioapns` v4. If you have `aioapns` v4 installed, this could lead to import errors or unexpected behavior.","severity":"breaking","affected_versions":">=3.3.0"},{"fix":"Update your APNS send calls to pass `mutable_content=1` instead of `mutable_content=True` (or `mutable_content=0` instead of `mutable_content=False`).","message":"The `mutable_content` field type for APNS messages changed from boolean `True` to integer `1` (or `0` for `False`) in version 3.2.1. Passing a boolean will raise a `TypeError`.","severity":"breaking","affected_versions":">=3.2.1"},{"fix":"It is best practice to ensure `DEFAULT_AUTO_FIELD` is set in your Django `settings.py` (e.g., `DEFAULT_AUTO_FIELD = 'django.db.models.BigAutoField'`) for Django 3.2+ projects.","message":"Version 3.3.0 introduced an explicit Django `AppConfig` and sets `default_auto_field`. For older Django versions (pre-3.2) or custom configurations, you might encounter `AutoField` related warnings if `DEFAULT_AUTO_FIELD` is not explicitly set in your Django project.","severity":"gotcha","affected_versions":"All"},{"fix":"Configure `PUSH_NOTIFICATIONS_SETTINGS` to use `FCM_API_KEY` with your Firebase service account credentials for FCM v1. Consult the official documentation for detailed FCM v1 setup instructions.","message":"FCM v1 API support was added in version 3.1.0. The legacy GCM API is deprecated by Google and may be removed in future `django-push-notifications` versions. It is highly recommended to migrate to FCM v1.","severity":"deprecated","affected_versions":">=3.1.0"},{"fix":"Ensure your project runs on Python 3.7 or newer before upgrading to recent versions of `django-push-notifications`.","message":"Support for Python versions less than 3.4 was dropped in version 1.4.0. The library currently requires Python 3.7+.","severity":"breaking","affected_versions":"<1.4.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Add `'push_notifications'` to your `INSTALLED_APPS` in `settings.py`. Ensure any code interacting with `push_notifications` models runs within a properly initialized Django environment (e.g., within a Django management command or web request).","cause":"`push_notifications` is not listed in `INSTALLED_APPS` or Django's app registry has not initialized when models are accessed.","error":"django.core.exceptions.AppRegistryNotReady: Apps aren't loaded yet."},{"fix":"Provide all necessary `PUSH_NOTIFICATIONS_SETTINGS` in your Django `settings.py` as outlined in the `django-push-notifications` documentation for each service (APNS, FCM/GCM, WebPush).","cause":"Required push service credentials (e.g., APNS key path, FCM API key) are missing from the `PUSH_NOTIFICATIONS_SETTINGS` dictionary in your `settings.py`.","error":"KeyError: 'APNS_AUTH_KEY_PATH' or ImproperlyConfigured: The GCM_API_KEY must be set in PUSH_NOTIFICATIONS_SETTINGS."},{"fix":"Update your APNS `send_message` calls to use `mutable_content=1` or `mutable_content=0` instead of `mutable_content=True` or `mutable_content=False`.","cause":"In `django-push-notifications` versions 3.2.1 and later, the `mutable_content` parameter for APNS requires an integer (1 or 0) instead of a boolean (True or False).","error":"TypeError: 'bool' object is not subscriptable (when sending APNS mutable_content)"},{"fix":"Instead of importing and using `gcm_send_message`, retrieve a `GCMDevice` object and call its `send_message` method: `from push_notifications.models import GCMDevice; device = GCMDevice.objects.get(pk=1); device.send_message('Hello!')`.","cause":"Direct utility functions like `gcm_send_message` (and similar for APNS) are considered legacy. The recommended way to send messages is via the `send_message` method on `GCMDevice` (or `APNSDevice`, `WebPushDevice`) instances.","error":"ImportError: cannot import name 'gcm_send_message' from 'push_notifications.gcm'"}]}