blackberry/WebWorks-API-Docs — pull request #312 by mdandrea (2012-05-08 18:02:30+00:00)
Title: BlackBerry 10 Push APIs

We tried to simplify the number of APIs but from a business use case perspective. This is what we felt was needed for developers to write push enabled apps.

If it helps the team understand the APIs here are some additional notes:

• createChannel: Developers need to create a push channel before they can receive any pushes. Part of creating a push channel is that the API will return a token that must be communicated back to the content provider’s server-side application; this token allow the content provider to push on the channel to the device. In BIS, this will function will perform the registration with the push server and return the token. In BES, it will just return the token. In theory, this only needs to be called once for the lifetime of the application or whenever the channel has been closed/destroyed and needs to be re-createad. Registering with the push server is a semi-expensive call that we don’t want to have happen on every start of the app or every page transition but we do want developers to have the option of being able to re-subscribe whenever they want so this gives them the flexibility in their to decide when to call this function because there are certain circumstances where the channel can be destroy by the push server and the device won’t know about it.

• destroyChannel: Conversely, when you want to stop receiving push message you would call the destroy channel function.

• launchApplicationOnPush: Apps can choose to toggle if they will be launched to the background when a push comes in and the app isn’t currently running. There is an API for this that can be called to toggle the flag back and forth as many times as they would like. Consider an application that has a settings option to allow users to choose if they want their app to launch or not – the user can theoretically toggle this on/off as many times as they want.

• extractPushPayload: When a push message comes in via an invocation event/callback we exposed a convenience API to take that invocation object and return a PushPayload. The advantage of this is that it allows us to change the format of the message within the invocation payload and it won't break any apps whereas if we let users parse the invocation in the JavaScript layer no changes can be made to that JSon format within the invocation which ties our hands a bit for future development

• acknowledge: Lastly, the content provider server-side application can request the application on the device to acknowledge the receipt of the push message. So we exposed an acknowledge function for this purpose. This communicates with the RIM push server to mark the status of the push appropriately. There is no way to do this through the invocation framework.