App & Software, Dev & Design, Development, Django, Mobile, Python, Tech, Tutorials, Tutorials, Web

Django Push Notifications Mongoengine

Django Push Notifications Image Courtsey: Jaysin Trevino (Flickr)

I recently had to implement push notifications (both GCM and APNS) on a project that I was working on. As we were using django/python for this project, our research led us to django-push-notifications, a django app to send GCM and APNS notifications to android and ios devices respectively. But we found out that the above mentioned app implemented models using the django models which did not support mongoengine. We had implemented our django project using mongoengine instead of other sql databases as it was our project requirement. The resolution to this problem gave birth to django-instapush which makes django push notifications work with mongoengine Document or Models. As we had resolved this and now have it working on production servers of our application, we have decided to provide it to other fellow developers, who may want to send push notifications from their django projects and use sql or mongoengine under MIT License.

Following is the required documentation that you may need to look at while working with django-instapush. Until we get enough time to host proper documentation at readthedocs, You may go through the following brief documentation. Also if you would have any questions, queries, feature requests etc. Please let us know in the comments section below this article.

Django Instapush Documentation

This documentation is divided into the following parts. If you’d like a general idea about how to use django-instapush or make push notifications work with your django and mongoengine based application. Just read through each of the sections below. If you are looking for anything specific, Just click on topic you are looking to explore.

  1. Introduction
  2. Required Packages / Dependencies
  3. Models
    1. BaseDevice
    2. GCMDevice
    3. APNSDevice
  4. Mongoengine Support
    1. BaseDevice
    2. GCMDevice
    3. APNSDevice
  5. Creating Device Objects
  6. Sending Notifications
  7. Settings & Configuration

 

Introduction

Django-instapush is a reusable and a generic app that helps send GCM and APNS push notifications to android and ios devices respectively. It implements django models that stores the device information. If you are using mongoengine instead of django supported databases, you need not worry as django-instapush fully supports mongoengine and implements mongoengine documents as well that you can use instead of using the base models to store the device information.

No matter what models you use to store the device information, In each case a send_message method is available on both the model (Document in case of mongoengine) and the manager (queryset in case of mongoengine). So to send a single notification message to a specific device, you can use Model.send_message() or Document.send_message() method. To send a message to multiple devices you can use Model.objects.filter(**filters).send_message() method. To know more about how to send push notifications or see examples, Please go through the Sending Notifications section below.

Required/Packages / Dependencies

This package depends on the following packages. All the following packages can be installed using pypi.

  1. django
  2. mongoengine
  3. pymongo

Models

There are three models implemented by django-instapush to store your users’ device information. (If you are using mongoengine, Please follow the Mongoengine Support section below). The models are defined under models/base.py and can be imported as from instapush.models.base import .... Following are the 3 models:

BaseDevice

This model contains the generic and the basic device information. The other two models defined below, extend from this model and are platform specific. There are 5 fields defined for this model

  1. Name (name): This is optional. Can be used to store a name for a device.
  2. Active (active): This is a boolean field that tells whether this device is active or not. By default the value is set to True.
  3. Owner (owner): This is a ForeignKey to another model. This can be a user model or any other model if required. You’d need to set the DEVICE_OWNER_MODEL in the settings and the database tables will be created accordingly. Please check out the settings section to see how to use this settings.
  4. Created (created): This is a DateTimeField that contains the date and time that represents when this device object was created.
  5. Updated (updated): This is a DateTimeField that contains the date and time that represents when this device object was last updated.

GCMDevice

This model extends from the above mentioned BaseDevice model and implements 2 extra fields and a custom GCMDeviceManager. This model should be used to store device information for android based devices. This model and it’s manager (GCMDeviceManager) both implement a send_message method that can be used to send messages to a single and multiple devices respectively. Following are the two fields available with this model.

  1. Device Id (device_id): This should contain a unique device id for an android device.
  2. Registration Id (registration_id): This should contain the gcm id for the android device.

APNSDevice

This model also extends from the BaseDevice model and similar to GCMDevice implements 2 extra fields and a manager with the send_message method. This model should be used to store device information for iOS devices.

  1. Device Id (device_id): This should contain a unique device id for an iOS device.
  2. Registration Id (registration_id): This should contain the device token for the apple (iOS) device.

Mongoengine Support

For projects or apps that use mongoengine documents to define their models, django instapush implements similar three documents (models) to work with. If you do not use mongoengine and use django supported databases, please refer to the models section above instead. These documents are defined under models/mongo.py and can be imported as from instapush.models.mongo import ....

BaseDevice

This mongoengine document model contains the generic and the basic device information. The other two documents / models defined below, extend from this and are platform specific. There are 4 fields defined for this document.

  1. Name (name): This is optional. Can be used to store a name for a device.
  2. Active (active): This is a boolean field that tells whether this device is active or not. By default the value is set to True.
  3. Owner (owner): This is a mongoengine ReferenceField and can be used to refer to another mongoengine Document. This can be a user model document or any other if required. You’d need to set the DEVICE_OWNER_MODEL in the settings.
  4. Created (created): This is a DateTimeField that contains the date and time that represents when this device object was created.

GCMDevice

This document extends from the above mentioned BaseDevice model document and implements 2 extra fields and a custom GCMDeviceManager. This model should be used to store device information for android based devices. This model and it’s manager (GCMMongoQueryset). Both the model document and the manager implement a send_message method that can be used to send messages to a single and multiple devices respectively. Following are the two fields defined in this document.

  1. Device Id (device_id): This should contain a unique device id for an android device.
  2. Registration Id (registration_id): This should contain the gcm id for the android device.

APNSDevice

This model document also extends from the BaseDevice class and similar to GCMDevice implements 2 extra fields and a queryset with the send_message method. This document should be used to store device information for iOS devices.

  1. Device Id (device_id): This should contain a unique device id for an iOS device.
  2. Registration Id (registration_id): This should contain the device token for the apple (iOS) device.

Creating Device Objects

Creating a device object with django instapush is as easy as creating any other django model object.

from instapush.models.base import APNSDevice, GCMDevice
# if you are using mongoengine then import from instapush.models.mongo
# instead of instapush.models.base

apple_device = APNSDevice.objects.create(device_id=<your_unique_device_id>, registration_id=<your_apple_device_token>)
android_device = GCMDevice.objects.create(device_id=<your_unique_device_id>, registration_id=<your_devices_gcm_id>)

Sending Notifications

You would either want to send a single push notification to a device or bulk push notification to multiple devices. Both of these scenarios are possible with django-instapush models.

To send a single push notification to a particular device:

from instapush.models.base import APNSDevice, GCMDevice
# if you are using mongoengine then import from instapush.models.mongo
# instead of instapush.models.base

apple_device = APNSDevice.objects.create(device_id=<your_unique_device_id>, registration_id=<your_apple_device_token>)
android_device = GCMDevice.objects.create(device_id=<your_unique_device_id>, registration_id=<your_devices_gcm_id>)

apple_device.send_message({'message': 'You have a new notification', 'custom_parameter': 'custom_parameter_value'})
android_device.send_message({'message': 'You have a new notification', 'custom_parameter': 'custom_parameter_value'})

To send bulk push notifications to multiple devices:

from instapush.models.base import APNSDevice, GCMDevice
# if you are using mongoengine then import from instapush.models.mongo
# instead of instapush.models.base

apple_device_tokens = [...]
android_gcm_ids = [...]

apple_devices = APNSDevice.objects.filter(registration_id__in=apple_device_tokens)
android_devices = GCMDevice.objects.create(registration_id__in=android_gcm_ids)

apple_devices.send_message({'message': 'You have a new notification', 'custom_parameter': 'custom_parameter_value'})
android_devices.send_message({'message': 'You have a new notification', 'custom_parameter': 'custom_parameter_value'})

Sending a push notification directly using the gcm_id (android devices) or deviceToken (iOS Devices):

from instapush.models.libs import gcm, apns


## sending a gcm notification directly

# to a single device
gcm_id = '...'
gcm.gcm_send_message(gcm_id, {'message': 'my message'})

# to multiple devices
gcm_ids = [...]
gcm.gcm_send_bulk_message(gcm_ids, {'message': 'my message'})


## sending an apns notification directly

# to a single device
device_token = '...'
apns.apns_send_message(device_token, {'message': 'my message'})

# to multiple devices

device_tokens = [...]
apns.apns_send_bulk_message(device_tokens, {'message': 'my message'})

Settings & Configuration

Generic Settings

DEVICE_OWNER_MODEL : This represents the owner model that device models will connect to using a ForeignKey or a ReferenceField (in case of mongoengine).

GCM Specific Settings

API_KEY : This is a required setting. The value should be the API key for your GCM api service

API_URL: This is the GCM api’s url. Default is set to https://android.googleapis.com/gcm/send

MAX_RECIPIENTS: Number of maximum recipients. defaults to 1000.

APNS Specific Settings

APNS_CERTIFICATE: This is a required setting. The value should be the path to your APNS certificate pem file.

HOST: This is the apns host url. defaults to gateway.sandbox.push.apple.com if settings.DEBUG is set to True otherwise defaults to gateway.push.apple.com

PORT: defaults to 2195

MAX_SIZE: defaults to 2048

FEEDBACK_HOST: defaults to feedback.sandbox.push.apple.com’

FEEDBACK_PORT: uses the default 2196

ERROR_TIMEOUT: This is an optional setting. defaults to 0.

 

 

You Might Also Like