SALES: 1-800-867-1380
1 out of 1 rated this helpful - Rate this topic

gcm object

Updated: June 22, 2013

Exposes the functionality of Google Cloud Messaging (GCM) in Windows Azure Mobile Services server scripts.

The gcm object has the following methods:

send

Sends a notification to a specific device.

Syntax

gcm.send(registrationId, payload, options)

Parameters

 

Parameter Description

registrationId

Specifies the registration ID of a device or an array of registration IDs for devices that receive the message.

payload

Required object that contains the notification payload. This can contain a simple text string or an object containing key-value pairs such as


{
    symbol: 'msft',
    price: '26.78',
    lastClose: '26.20'  
}

The values must be strings. There are some restrictions on the property names outlined here. The total size of the payload serialized to JSON cannot be larger than 4 KB.

options

Optional object that specifies the success handler and error handler functions, in the following format:


{
    success: function(response) {
        // handle success here.
    },
    error : function(err) {
        // handle the error here.
    }
}

The success callback will fire if GCM was able to successfully accept the request. It does not mean all notifications were delivered. Your application must process the response callback parameter to fully understand the state of processing. The response parameter contains the following two properties to help in processing the result:

  • response.invalidIds - this is an array of registration IDs that are no longer valid. The application should not send future notifications to these IDs, otherwise it may be blocked by GCM.

  • response.updatedIds - a map of registration IDs provided in the request to updated registration IDs. The application should use the updated IDs instead of the original IDs when sending future notifications. GCM may occasionally update the registration ID associated with a device, and this is the mechanism used to notify the sender about such update.

Returns

Undefined.

sendAdvanced

Used to request information from GCM using features beyond what is available in the simple send method , such as:

  • automatically retry sending the notications if GCM servers are too busy

  • collapse multiple notifications into one if the notification cannot be delievered at once,

  • only send a notification if the device is active,

  • specify the TTL for storing notifications at GCM servers while the device is offline,

  • restrict delivery to applications with specific package name,

  • issue the request against GCM sandbox without actual delivery to the device.

Syntax

gcm.sendAdvanced(content, retryCount, options)

Parameters

 

Parameter Description

content

Required object that contains the request object to send to GCM. Here is an example object:


{
   registration_ids : ['one or more IDs'],
   data : {
      message:  'hello GCM'
  },
  // Other properties such as 'collapse_key', 'delay_while_idle', 'time_to_live', 'restricted_package_name', and 'dry_run'
}

The format for the properties of this object is specified here.

retryCount

A non-negative integer indicating how many times the request should be re-tried if the GCM servers respond with a 5xx status code. The module implements the required back-off policy based on the Retry-After HTTP response header sent from GCM. The default value is 0.

options

Optional object that specifies the success handler and error handler functions, please see the detailed description provided for the send method above.

Returns

Undefined.

The gcm object is obtained from the push object in a server script. For a complete example, see Get started with push notifications.

The following example calls the send method to send a text notification to a specific device when a new item is inserted into a table.

function insert(item, user, request) {
    request.execute({
        success: function() {
            // Write to the response and then send the push notification.
            request.respond();
            push.gcm.send(item.channel, item.text, {
                   success: function(response) {
                       console.log('Push notification sent: ', response);
                }, error: function(error) {
                       console.log('Error sending push notification: ', error);
                }
            });
        }
    });
}

The following example calls the sendAdvanced method to send a text notification to a specific device when a new item is inserted into a table and to retry the send 3 times if needed.

function insert(item, user, request) {
    request.execute({
        success: function() {
            // Write to the response and then send the push notification.
            request.respond();
            push.gcm.sendAdvanced({
                registration_ids: ['27'],
                data: {
                    message: 'hello GCM'
                },
            }, 3, {
                success: function(response) {
                    console.log('Push notification sent: ', response);
                },
                error: function(error) {
                    console.log('Error sending push notification: ', error);
                }
            });
        }
    });
}

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft. All rights reserved.