fcm-django


Namefcm-django JSON
Version 0.2.11 PyPI version JSON
download
home_pagehttps://github.com/xtrinch/fcm-django
SummarySend push notifications to mobile devices & browsers through FCM in Django.
upload_time2017-06-27 15:35:19
maintainer
docs_urlNone
authorxTrinch
requires_python
license
keywords
VCS
bugtrack_url
requirements pyfcm
Travis-CI No Travis.
coveralls test coverage No coveralls.
            fcm-django
=========================


.. image:: https://badge.fury.io/py/fcm-django.svg
    :target: https://badge.fury.io/py/fcm-django

Django app for Firebase Cloud Messaging. Used as an unified platform for sending push notifications to mobile devices & browsers (android / ios / chrome / firefox / ...).

FCMDevice model fields
 - *registration_id* (required - is FCM token)
 - *name* (optional)
 - *active* (default: true)
 - *user* (optional)
 - *device_id* (optional - can be used to uniquely identify devices)
 - *type* ('android', 'web', 'ios')

Functionality:
 - all necessary migrations
 - model admins for django admin
 - admin actions for testing single and bulk notification sending
 - automatic device pruning: devices to which notifications fail to send are marked as inactive
 - devices marked as inactive will not be sent notifications
 - Django rest framework viewsets

Setup
-----
You can install the library directly from pypi using pip:

	$ pip install fcm-django


Edit your settings.py file:

.. code-block:: python

	INSTALLED_APPS = (
		...
		"fcm_django"
	)

	FCM_DJANGO_SETTINGS = {
		"FCM_SERVER_KEY": "[your api key]",
		 # true if you want to have only one active device per registered user at a time
		 # default: False
		"ONE_DEVICE_PER_USER": True/False,
		 # devices to which notifications cannot be sent,
		 # are deleted upon receiving error response from FCM
		 # default: False
		"DELETE_INACTIVE_DEVICES": True/False,
	}

Native Django migrations are in use. ``manage.py migrate`` will install and migrate all models.

Messages
--------

You can read more about different types of messages here_.

.. _here: https://firebase.google.com/docs/cloud-messaging/concept-options

In short, there are two types: notifications and data messages.

Notification:

.. code-block:: json

	{
	    "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
	    "notification" : {
	      "body" : "great match!",
	      "title" : "Portugal vs. Denmark",
	      "icon" : "myicon"
	    }
	}

Data message:

.. code-block:: json

	{
	   "to" : "bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...",
	   "data" : {
	     "Nick" : "Mario",
	     "body" : "great match!",
	     "Room" : "PortugalVSDenmark"
	   },
	}

As in the following example, you can send either a notification, a data message, or both.

Sending messages
----------------

For a list of possible parameters see https://firebase.google.com/docs/cloud-messaging/http-server-ref#notification-payload-support

.. code-block:: python

	from fcm_django.models import FCMDevice

	device = FCMDevice.objects.all().first()

	device.send_message("Title", "Message")
	device.send_message(data={"test": "test"})
	device.send_message(title="Title", body="Message", icon=..., data={"test": "test"})

By default the message will be sent using the FCM server key specified in the settings.py. This default key can be overridden by specifying a key when calling send_message. This can be used to send messages using different firebase projects.

.. code-block:: python

    from fcm_django.models import FCMDevice

    device = FCMDevice.objects.all().first()
    device.send_message(title="Title", body="Message", api_key="[project 1 api key]")
    device.send_message(title="Title", body="Message", api_key="[project 2 api key]")

Sending messages in bulk
------------------------

.. code-block:: python

	from fcm_django.models import FCMDevice

	devices = FCMDevice.objects.all()

	devices.send_message(title="Title", body="Message")
	devices.send_message(title="Title", body="Message", data={"test": "test"})
	devices.send_message(data={"test": "test"})


Django REST Framework (DRF) support
-----------------------------------
Viewsets come in two different varieties:

- ``FCMDeviceViewSet``

	- Permissions as specified in settings (``AllowAny`` by default, which is not recommended)
	- A device may be registered without associating it with a user
	- Will not allow duplicate registration_id's

- ``FCMDeviceAuthorizedViewSet``

	- Permissions are ``IsAuthenticated`` and custom permission ``IsOwner``, which will only allow the ``request.user`` to get and update devices that belong to that user
	- Requires a user to be authenticated, so all devices will be associated with a user
	- Will allow duplicate registration_id's for different users, so you are responsible for cleanup (if that is generally perceived as undesired behaviour or if the package itself should be doing the cleanup, open an issue or email me)

Routes can be added one of two ways:

- Routers_ (include all views)

http://www.django-rest-framework.org/tutorial/6-viewsets-and-routers#using-routers

.. code-block:: python

	from fcm_django.api.rest_framework import FCMDeviceAuthorizedViewSet

	from rest_framework.routers import DefaultRouter

	router = DefaultRouter()

	router.register(r'devices', FCMDeviceAuthorizedViewSet)

	urlpatterns = patterns('',
		# URLs will show up at <api_root>/devices
		# DRF browsable API which lists all available endpoints
		url(r'^', include(router.urls)),
		# ...
	)

- Using as_view_ (specify which views to include)

http://www.django-rest-framework.org/tutorial/6-viewsets-and-routers#binding-viewsets-to-urls-explicitly

.. code-block:: python

	from fcm_django.api.rest_framework import FCMDeviceAuthorizedViewSet

	urlpatterns = patterns('',
		# Only allow creation of devices by authenticated users
		url(r'^devices?$', FCMDeviceAuthorizedViewSet.as_view({'post': 'create'}), name='create_fcm_device'),
		# ...
	)

Demo project for implementation of web push notifications
-------------------
Demonstrates the use of service workers:
https://github.com/xtrinch/fcm-django-web-demo


Python 3 support
----------------
``fcm-django`` is fully compatible with Python 3.4 & 3.5

Acknowledgements
----------------
Library relies on pyFCM for sending notifications, for more info about all the possible fields, see:
https://github.com/olucurious/PyFCM

Need help, have any questions, suggestions?
----------------
Submit an issue/PR or email me at mojca.rojko@gmail.com

            

Raw data

            {
    "maintainer": "", 
    "docs_url": null, 
    "requires_python": "", 
    "maintainer_email": "", 
    "cheesecake_code_kwalitee_id": null, 
    "keywords": "", 
    "upload_time": "2017-06-27 15:35:19", 
    "requirements": [
        {
            "name": "pyfcm", 
            "specs": [
                [
                    "==", 
                    "1.2.3"
                ]
            ]
        }
    ], 
    "author": "xTrinch", 
    "home_page": "https://github.com/xtrinch/fcm-django", 
    "github_user": "xtrinch", 
    "download_url": "https://pypi.python.org/packages/9b/48/006e99b7fc51151c65fedaaa60dc3570448da616d9eaf7812c4db26cd829/fcm-django-0.2.11.tar.gz", 
    "platform": "UNKNOWN", 
    "version": "0.2.11", 
    "cheesecake_documentation_id": null, 
    "description": "fcm-django\n=========================\n\n\n.. image:: https://badge.fury.io/py/fcm-django.svg\n    :target: https://badge.fury.io/py/fcm-django\n\nDjango app for Firebase Cloud Messaging. Used as an unified platform for sending push notifications to mobile devices & browsers (android / ios / chrome / firefox / ...).\n\nFCMDevice model fields\n - *registration_id* (required - is FCM token)\n - *name* (optional)\n - *active* (default: true)\n - *user* (optional)\n - *device_id* (optional - can be used to uniquely identify devices)\n - *type* ('android', 'web', 'ios')\n\nFunctionality:\n - all necessary migrations\n - model admins for django admin\n - admin actions for testing single and bulk notification sending\n - automatic device pruning: devices to which notifications fail to send are marked as inactive\n - devices marked as inactive will not be sent notifications\n - Django rest framework viewsets\n\nSetup\n-----\nYou can install the library directly from pypi using pip:\n\n\t$ pip install fcm-django\n\n\nEdit your settings.py file:\n\n.. code-block:: python\n\n\tINSTALLED_APPS = (\n\t\t...\n\t\t\"fcm_django\"\n\t)\n\n\tFCM_DJANGO_SETTINGS = {\n\t\t\"FCM_SERVER_KEY\": \"[your api key]\",\n\t\t # true if you want to have only one active device per registered user at a time\n\t\t # default: False\n\t\t\"ONE_DEVICE_PER_USER\": True/False,\n\t\t # devices to which notifications cannot be sent,\n\t\t # are deleted upon receiving error response from FCM\n\t\t # default: False\n\t\t\"DELETE_INACTIVE_DEVICES\": True/False,\n\t}\n\nNative Django migrations are in use. ``manage.py migrate`` will install and migrate all models.\n\nMessages\n--------\n\nYou can read more about different types of messages here_.\n\n.. _here: https://firebase.google.com/docs/cloud-messaging/concept-options\n\nIn short, there are two types: notifications and data messages.\n\nNotification:\n\n.. code-block:: json\n\n\t{\n\t    \"to\" : \"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...\",\n\t    \"notification\" : {\n\t      \"body\" : \"great match!\",\n\t      \"title\" : \"Portugal vs. Denmark\",\n\t      \"icon\" : \"myicon\"\n\t    }\n\t}\n\nData message:\n\n.. code-block:: json\n\n\t{\n\t   \"to\" : \"bk3RNwTe3H0:CI2k_HHwgIpoDKCIZvvDMExUdFQ3P1...\",\n\t   \"data\" : {\n\t     \"Nick\" : \"Mario\",\n\t     \"body\" : \"great match!\",\n\t     \"Room\" : \"PortugalVSDenmark\"\n\t   },\n\t}\n\nAs in the following example, you can send either a notification, a data message, or both.\n\nSending messages\n----------------\n\nFor a list of possible parameters see https://firebase.google.com/docs/cloud-messaging/http-server-ref#notification-payload-support\n\n.. code-block:: python\n\n\tfrom fcm_django.models import FCMDevice\n\n\tdevice = FCMDevice.objects.all().first()\n\n\tdevice.send_message(\"Title\", \"Message\")\n\tdevice.send_message(data={\"test\": \"test\"})\n\tdevice.send_message(title=\"Title\", body=\"Message\", icon=..., data={\"test\": \"test\"})\n\nBy default the message will be sent using the FCM server key specified in the settings.py. This default key can be overridden by specifying a key when calling send_message. This can be used to send messages using different firebase projects.\n\n.. code-block:: python\n\n    from fcm_django.models import FCMDevice\n\n    device = FCMDevice.objects.all().first()\n    device.send_message(title=\"Title\", body=\"Message\", api_key=\"[project 1 api key]\")\n    device.send_message(title=\"Title\", body=\"Message\", api_key=\"[project 2 api key]\")\n\nSending messages in bulk\n------------------------\n\n.. code-block:: python\n\n\tfrom fcm_django.models import FCMDevice\n\n\tdevices = FCMDevice.objects.all()\n\n\tdevices.send_message(title=\"Title\", body=\"Message\")\n\tdevices.send_message(title=\"Title\", body=\"Message\", data={\"test\": \"test\"})\n\tdevices.send_message(data={\"test\": \"test\"})\n\n\nDjango REST Framework (DRF) support\n-----------------------------------\nViewsets come in two different varieties:\n\n- ``FCMDeviceViewSet``\n\n\t- Permissions as specified in settings (``AllowAny`` by default, which is not recommended)\n\t- A device may be registered without associating it with a user\n\t- Will not allow duplicate registration_id's\n\n- ``FCMDeviceAuthorizedViewSet``\n\n\t- Permissions are ``IsAuthenticated`` and custom permission ``IsOwner``, which will only allow the ``request.user`` to get and update devices that belong to that user\n\t- Requires a user to be authenticated, so all devices will be associated with a user\n\t- Will allow duplicate registration_id's for different users, so you are responsible for cleanup (if that is generally perceived as undesired behaviour or if the package itself should be doing the cleanup, open an issue or email me)\n\nRoutes can be added one of two ways:\n\n- Routers_ (include all views)\n\nhttp://www.django-rest-framework.org/tutorial/6-viewsets-and-routers#using-routers\n\n.. code-block:: python\n\n\tfrom fcm_django.api.rest_framework import FCMDeviceAuthorizedViewSet\n\n\tfrom rest_framework.routers import DefaultRouter\n\n\trouter = DefaultRouter()\n\n\trouter.register(r'devices', FCMDeviceAuthorizedViewSet)\n\n\turlpatterns = patterns('',\n\t\t# URLs will show up at <api_root>/devices\n\t\t# DRF browsable API which lists all available endpoints\n\t\turl(r'^', include(router.urls)),\n\t\t# ...\n\t)\n\n- Using as_view_ (specify which views to include)\n\nhttp://www.django-rest-framework.org/tutorial/6-viewsets-and-routers#binding-viewsets-to-urls-explicitly\n\n.. code-block:: python\n\n\tfrom fcm_django.api.rest_framework import FCMDeviceAuthorizedViewSet\n\n\turlpatterns = patterns('',\n\t\t# Only allow creation of devices by authenticated users\n\t\turl(r'^devices?$', FCMDeviceAuthorizedViewSet.as_view({'post': 'create'}), name='create_fcm_device'),\n\t\t# ...\n\t)\n\nDemo project for implementation of web push notifications\n-------------------\nDemonstrates the use of service workers:\nhttps://github.com/xtrinch/fcm-django-web-demo\n\n\nPython 3 support\n----------------\n``fcm-django`` is fully compatible with Python 3.4 & 3.5\n\nAcknowledgements\n----------------\nLibrary relies on pyFCM for sending notifications, for more info about all the possible fields, see:\nhttps://github.com/olucurious/PyFCM\n\nNeed help, have any questions, suggestions?\n----------------\nSubmit an issue/PR or email me at mojca.rojko@gmail.com\n", 
    "lcname": "fcm-django", 
    "bugtrack_url": null, 
    "github": true, 
    "coveralls": false, 
    "name": "fcm-django", 
    "license": "", 
    "travis_ci": false, 
    "github_project": "fcm-django", 
    "summary": "Send push notifications to mobile devices & browsers through FCM in Django.", 
    "split_keywords": [], 
    "author_email": "mojca.rojko@gmail.com", 
    "urls": [
        {
            "has_sig": false, 
            "upload_time": "2017-06-27T15:35:19", 
            "comment_text": "", 
            "python_version": "source", 
            "url": "https://pypi.python.org/packages/9b/48/006e99b7fc51151c65fedaaa60dc3570448da616d9eaf7812c4db26cd829/fcm-django-0.2.11.tar.gz", 
            "md5_digest": "aa61d51d51b53aee731ca3fd4824b1ca", 
            "downloads": 0, 
            "filename": "fcm-django-0.2.11.tar.gz", 
            "packagetype": "sdist", 
            "path": "9b/48/006e99b7fc51151c65fedaaa60dc3570448da616d9eaf7812c4db26cd829/fcm-django-0.2.11.tar.gz", 
            "size": 10858
        }, 
        {
            "has_sig": false, 
            "upload_time": "2017-06-27T15:35:17", 
            "comment_text": "", 
            "python_version": "py2.py3", 
            "url": "https://pypi.python.org/packages/5e/94/4c94f7e4e197649f3fa537e1bb2490cf14a4a1a1936ab3662d90af6fb748/fcm_django-0.2.11-py2.py3-none-any.whl", 
            "md5_digest": "ecfa812b13be1cdc0caf25c4f911f219", 
            "downloads": 0, 
            "filename": "fcm_django-0.2.11-py2.py3-none-any.whl", 
            "packagetype": "bdist_wheel", 
            "path": "5e/94/4c94f7e4e197649f3fa537e1bb2490cf14a4a1a1936ab3662d90af6fb748/fcm_django-0.2.11-py2.py3-none-any.whl", 
            "size": 13796
        }
    ], 
    "_id": null, 
    "cheesecake_installability_id": null
}