Django push notifications mongoengine

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
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.

We will be happy to hear your thoughts

      Leave a reply

      Techs Tricks
      Logo
      Reset Password
      Shopping cart