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.
- Introduction
- Required Packages / Dependencies
- Models
- Mongoengine Support
- Creating Device Objects
- Sending Notifications
- 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.
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
- Name (
name): This is optional. Can be used to store a name for a device. - Active (
active): This is a boolean field that tells whether this device is active or not. By default the value is set toTrue. - 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 theDEVICE_OWNER_MODELin the settings and the database tables will be created accordingly. Please check out the settings section to see how to use this settings. - Created (
created): This is a DateTimeField that contains the date and time that represents when this device object was created. - 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.
- Device Id (
device_id): This should contain a unique device id for an android device. - 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.
- Device Id (
device_id): This should contain a unique device id for an iOS device. - 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.
- Name (
name): This is optional. Can be used to store a name for a device. - Active (
active): This is a boolean field that tells whether this device is active or not. By default the value is set toTrue. - 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 theDEVICE_OWNER_MODELin the settings. - 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.
- Device Id (
device_id): This should contain a unique device id for an android device. - 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.
- Device Id (
device_id): This should contain a unique device id for an iOS device. - 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 from instapush.models.mongo# instead of instapush.models.baseapple_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.baseapple_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.baseapple_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 devicegcm_id = '...'gcm.gcm_send_message(gcm_id, {'message': 'my message'})# to multiple devicesgcm_ids = [...]gcm.gcm_send_bulk_message(gcm_ids, {'message': 'my message'})## sending an apns notification directly# to a single devicedevice_token = '...'apns.apns_send_message(device_token, {'message': 'my message'})# to multiple devicesdevice_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.
