Overview
Push notifications enable server applications (known as providers in push parlance) to send information to mobile apps even when the app isn’t in use. The device displays the information using a "badge," alert, or pop up message. A push notification uses the service provided by the device's operating system:
- iOS - Apple Push Notification service (APNS)
- Android - Google Cloud Messaging (GCM)
The following diagram illustrates how it works.
To send push notifications, you'll need to create a LoopBack server application, then configure your iOS and Android client apps accordingly. You can either use the example LoopBack push application or create your own. Using the example application is a good way to learn about LoopBack push notifications.
For more information on the architecture of the LoopBack Push Notification component, see Architecture below.
Installation
Install the LoopBack push component as usual for a Node package:
$ npm install loopback-component-push
Use the LoopBack push notification sample application
First, download the sample app:
$ git clone https://github.com/strongloop/loopback-component-push.git
Set up messaging credentials for Android apps
First, if you haven't already done so, get your Google Cloud Messaging (GCM) credentials for Android apps. After following the instructions, you will have a GCM API key. Then edit example/server/config.js
and look for the line:
exports.gcmServerApiKey = 'Your-server-api-key';
Replace Your-server-api-key
with your GCM server API key. For example:
exports.gcmServerApiKey = 'AIzaSyDEPWYN9Dxf3xDOqbQluCwuHsGfK4aJehc';
Set up messaging credentials for iOS apps
If you have not already done so, create your APNS certificates for iOS apps. After following the instructions, you will have APNS certificates on your system. Then edit example/server/config.js
and look for these lines:
exports.apnsCertData = readCredentialsFile('apns_cert_dev.pem'); exports.apnsKeyData = readCredentialsFile('apns_key_dev.pem');
Replace the file names with the names of the files containing your APNS certificates. By deafult, readCredentialsFile()
looks in the /credentials
sub-directory for your APNS certificates.
If you don't have a client app yet, leave the default appName in config.js
for now. Once you have created your client app, update the appName.
Now follow the instructions in:
- Push notifications for Android apps to set up Android client apps.
- Push notifications for iOS apps to set up iOS client apps
Run the sample server application
First install all dependencies, then run the Node application as follows:
$ cd example/server $ npm install ... $ node app
You will see the message:
The server is running at http://127.0.0.1:3010
Set up your LoopBack application to send push notifications
Follow the directions in this section to configure your own LoopBack application to send push notifications. It may be helpful to refer to the example LoopBack application.
Install Loopback push notification module
$ npm install loopback-component-push
Create a push model
To send push notifications, you must create a push model. The code below illustrates how to do this with a database as the data source. The database is used to load and store the corresponding application/user/installation models.
var loopback = require('loopback'); var app = loopback(); var Notification = app.models.notification; var Application = app.models.application; var PushModel = app.models.push;
Configure the application with push settings
Register a mobile application
The mobile application needs to register with LoopBack so it can have an identity for the application and corresponding settings for push services. Use the Application model's register()
function for sign-up.
For information on getting API keys, see:
- Get your Google Cloud Messaging credentials for Android.
- Set up iOS clients for iOS.
Application.register('put your developer id here', 'put your unique application name here', { description: 'LoopBack Push Notification Demo Application', pushSettings: { apns: { certData: readCredentialsFile('apns_cert_dev.pem'), keyData: readCredentialsFile('apns_key_dev.pem'), pushOptions: { }, feedbackOptions: { batchFeedback: true, interval: 300 } }, gcm: { serverApiKey: 'your GCM server API Key' } } }, function(err, app) { if (err) return cb(err); return cb(null, app); } ); function readCredentialsFile(name) { return fs.readFileSync( path.resolve(__dirname, 'credentials', name), 'UTF-8' ); }
Register a mobile device
The mobile device also needs to register itself with the backend using the Installation model and APIs. To register a device from the server side, call the Installation.create()
function, as shown in the following example:
Installation.create({ appId: 'MyLoopBackApp', userId: 'raymond', deviceToken: '756244503c9f95b49d7ff82120dc193ca1e3a7cb56f60c2ef2a19241e8f33305', deviceType: 'ios', created: new Date(), modified: new Date(), status: 'Active' }, function (err, result) { console.log('Registration record is created: ', result); });
Most likely, the mobile application registers the device with LoopBack using REST APIs or SDKs from the client side, for example:
POST http://localhost:3010/api/installations { "appId": "MyLoopBackApp", "userId": "raymond", "deviceToken": "756244503c9f95b49d7ff82120dc193ca1e3a7cb56f60c2ef2a19241e8f33305", "deviceType": "ios" }
Send push notifications
Send out the push notification immediately
LoopBack provides two Node.js methods to select devices and send notifications to them:
notifyById()
: Select a device by registration ID and send a notification to it.notifyByQuery()
: Get a list of devices using a query (same as the where property forInstallation.find()
) and send a notification to all of them.
For example, the code below creates a custom endpoint to send out a dummy notification for the selected device:
var badge = 1; app.post('/notify/:id', function (req, res, next) { var note = new Notification({ expirationInterval: 3600, // Expires 1 hour from now. badge: badge++, sound: 'ping.aiff', alert: '\uD83D\uDCE7 \u2709 ' + 'Hello', messageFrom: 'Ray' }); PushModel.notifyById(req.params.id, note, function(err) { if (err) { // let the default error handling middleware // report the error in an appropriate way return next(err); } console.log('pushing notification to %j', req.params.id); res.send(200, 'OK'); }); });
To select a list of devices by query, use the PushModel.notifyByQuery()
, for example:
PushModel.notifyByQuery({userId: {inq: selectedUserIds}}, note, function(err) { console.log('pushing notification to %j', selectedUserIds); });
Schedule the push notification request
Error handling
LoopBack has two mechanisms for reporting push notification errors:
- Most configuration-related errors are reported to the callback argument of notification functions. These errors should be reported back to the caller (HTTP client) as can be seen in the
notifyById()
code example above. - Transport-related errors are reported via "error" events on the push connector. The application should listen for these events and report errors in the same way as other errors are reported (typically via console.error, bunyan, and so forth.).
PushModel.on('error', function(err) { console.error('Push Notification error: ', err.stack); });
Architecture
The following diagram illustrates the LoopBack push notification system architecture. The components are:
- Device model and APIs to manage devices with applications and users.
- Application model to provide push settings for device types such as iOS and Android.
- Notification model to capture notification messages and persist scheduled notifications.
- Optional job to take scheduled notification requests.
- Push connector that interacts with device registration records and push providers APNS for iOS apps and GCM for Android apps.
- Push model to provide high-level APIs for device-independent push notifications.
Attachments:




