Push

Push helps you reach out to your users in a timely fashion with important messages. You can use it to inform users about updates to some piece of data, about new services available nearby or that they are winners in a game. Using Custom server code you can set up triggers which send push notifications to a targeted set of people based on changes in the data you specify.

Kinvey brings Android Push Notifications to you through an integration with Google Cloud Messaging (GCM), and iOS Push Notifications through an integration with AWS SNS. While push notifications can only be configured to be used by either iOS or Android devices, our APIs provide support for registering/unregistering devices and associating them with Kinvey users.

Preparation

Before using the endpoints to register and unregister devices, you must configure your app for push notifications through the Kinvey Console. For more information, please refer to the iOS or Android push notification guides.

Note that the iOS and Android libraries already use these endpoints "behind the scenes". If you are using one of these libraries, you need not register or unregister devices explicitly through the REST API.

Registering a device

In order to register a device, send a POST request to /push/:appKey/register-device. The request must be authenticated with either user or master credentials. The body of the request must contain the following information:

  • platform: a string. Either "ios" or "android".
  • deviceId: a string containing the ID of the device you wish to register.
  • userId: required only if your request is authenticated using the master credentials. If your request is authenticated with user credentials, the userId will be the ID of the authenticated user, and it needs not be specified in the request body.

Example with master credentials:

POST /push/:appKey/register-device HTTP/1.1
Host: baas.kinvey.com
Authorization: [master credentials]
Content-Type: application/json

{
  "platform": "ios",
  "deviceId": "device ID goes here",
  "framework": "optional: put 'titanium' if using the titanium library, omit  otherwise",
  "userId": "5058c666474f050906000001"
}
HTTP/1.1 204 OK

Example with user credentials:

POST /push/:appKey/register-device HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
Content-Type: application/json

{
  "platform": "ios",
  "deviceId": "device ID goes here"
}
HTTP/1.1 204 OK

Required headers

  • Authorization
  • Content-Type: application/json

Unregistering a device

In order to unregister a device, send a POST request to /push/:appKey/unregister-device. The request must be authenticated with either user or master credentials. The body of the request must contain the following information:

  • platform: a string. Either "ios" or "android".
  • deviceId: a string containing the ID of the device you wish to unregister.
  • userId: required only if your request is authenticated using the master credentials. If your request is authenticated with user credentials, the userId will be the ID of the authenticated user, and it needs not be specified in the request body.

Example with master credentials:

POST /push/:appKey/unregister-device HTTP/1.1
Host: baas.kinvey.com
Authorization: [master credentials]
Content-Type: application/json

{
  "platform": "ios",
  "deviceId": "device ID goes here",
  "userId": "5058c666474f050906000001"
}
HTTP/1.1 204 OK

Example with user credentials:

POST /push/:appKey/unregister-device HTTP/1.1
Host: baas.kinvey.com
Authorization: [user credentials]
Content-Type: application/json

{
  "platform": "ios",
  "deviceId": "device ID goes here"
}
HTTP/1.1 204 OK

Required headers

  • Authorization
  • Content-Type: application/json

Triggering push notifications

function onPreSave(request,response,modules){
    var collectionAccess = modules.collectionAccess
   , userCollection = collectionAccess.collection('user')
   , utils = modules.utils
   , push = modules.push
   , template = '{{name}}, the {{team}} just won!'
   , pushedMessageCount = 0
   , userCount;


   // Find all users who's favoriteTeam matches the incomming request's winning team
   userCollection.find({"favoriteTeam": request.body.winningTeam}, function(err, userDocs){
     // Total number of messages to send
     userCount = userDocs.length;

     // Each message is customized
     userDocs.forEach(function(doc){
       var values = {
          name: doc.givenName,
          team: doc.favoriteTeam
       };

       // Render the message to send
       var message = utils.renderTemplate(template, values);

       // Send the push
       push.send(doc, message);

       // Keep track of how many pushes we've sent
       pushedMessageCount++;

       // reduce the number of users left to push to
       userCount--;
       if (userCount <= 0){
         // We've pushed to all users, complete the request
         response.body = {"message": "Attempted to push " + pushedMessageCount + " messages."};
         response.complete(200);
        }
     });
  });
}

This sends a push notification to all users who match the winning team provided by a POST or PUT (also known as save in Kinvey client libraries) to a collection. Instead of saving any data to the data store, this request just causes the push notification to be sent.

The body of the request must have a winningTeam property, like

 {
   "winningTeam": "Boston Red Sox"
 }

Users are expected to have a givenName property and a favoriteTeam property.

The Push notification will be similar to:

Joe, the Kansas City Royals just won!

Code is a Custom Endpoint Business Logic.

Push methods

See our reference documentation for push.

Got a question?