SALES: 1-800-867-1380

apns object

Updated: February 21, 2013

Exposes the functionality of the Apple Push Notification Service (APNS) in Windows Azure Mobile Services server scripts.

The apns object has the following methods:

send

Sends a notification to a specific device.

Syntax

apns.send(deviceToken, payload, options)

Parameters

 

Parameter Description

deviceToken

Required token value that indicates which device receives the notification.

payload

Required object that contains the notification information, in the following format:

{
     badge: badge_number,
     alert: 'alert_text',
     sound: 'sound_file',
     payload: payload_object,
     expiry: expire_date
}

Where badge_number is the number to display over the app icon, alert_text is the toast alert message, sound_file is the sound to play when the notification is received, payload_object is a JSON object that contains the notification text, and expire_date is the date after which the notification is no longer delivered.

options

Optional object that specifies the error handler function, in the following format:

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

The error output supplied to the callback has the following format:

{
    statusCode : error_status,
    deviceToken : 'device_token',
    statusDescription : 'error_description' 
}

Where error_status is the status code for the error, device_token indicates which device produced the error, and error_description is a text description of the error.

Returns

Undefined.

getFeedback

Used to request information from the APNS about device-specific push notification failures.

Syntax

apns.getFeedback(completion)

Parameters

 

Parameter Description

completion

A completion object that has success and error handers, as follows:

{
    success: function(devices) {
        // Code that executes when the method succeeds.
    },
    error: function(err) {
        // Code that executes when the method fails.
    }
}

When an error handler is not provided, errors are written to the log.

The devices output object is in the following format:

[ 
    { 
        deviceToken : 'device_token1', 
        timeStamp : 'time_stamp_datetime1'
    },
{ 
        deviceToken : 'device_token2', 
        timeStamp : 'time_stamp_datetime2'
    },
    { n }
]

Returns

Undefined.

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

When the alert field of the payload object is specified, the assigned text value is displayed as a toast notification. This notification is displayed even when the app is not running. The data in the payload field of the payload object is only displayed when the app is running.

APNS tracks notifications that fail because the app is no longer installed on the device. Mobile Services enables you access this information from the APNS feedback service and remove device tokens so that you can avoid the extra cost of sending notifications to uninstalled apps. To do this, Mobile Services periodically calls the processFeedback function. In this function, you can call the getFeedback method on the apns object. This method returns array of objects that represent failures, where each object has a deviceToken and timeStamp field. The devices array is returned in the success: handler. When an error handler is not provided, errors are written to your mobile service’s log.

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.apns.send(item.deviceToken, {
                payload: { itemText: item.text, userId: user.userId } 
            });
        }
    });
}

The following processFeedback script is called by Mobile Services and is used to execute the getFeedback method.

function processFeedback() {

    push.apns.getFeedback({
        success: function(results) {
            // results will be an array of objects, each with 'deviceToken' and 'time' properties
            if (results.length > 0) {
                  // TODO - update your storage to mark or delete devices appropriately
                  console.warn("APNS feedback received for the following device tokens.",  results);
            }
        }
    });
}

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft