blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal

Push Channel Back-End API

The BlackBerry Dynamics Push Channel feature has both front-end and back-end parts. This page covers the back-end part, which is used by the application server.

See also:
GDPushChannel for the front-end part, which is used by the application on the mobile device or computer, and for an overall description of the feature.

Services and Callbacks

The application programming interface (API) for the back-end application server (App Server) consists of the following services and callbacks.

Services that are offered to the App Server:

checkToken Check Push Channel token and register App Server callbacks.
notify Send Push Channel notification message.

Callbacks that may be registered by the App Server.

isDisconnected Receive notification of front-end application disconnection.
AppServer Ping Periodically called when Ping Failure detection is enabled.

Addressing Service Requests

BlackBerry Dynamics Push Channel services are hosted on the Network Operation Center (NOC). The NOC is a central mediation point for the BlackBerry Dynamics platform and its proxy infrastructure. From an architectural point-of-view, there is a single NOC for all BlackBerry Dynamics enterprises, users and services. For practical reasons, however, there may actually be a number of NOC deployments. For example, there may be separate production and development deployments.

Requests can be addressed directly to the NOC by specifying its server address. Each NOC deployment has a single address for all Push Channel services. NOC server addresses and port numbers are published on the application developer portal, on the Network Operation Center server addresses page.

Requests can also be addressed through an enterprise BlackBerry Proxy or legacy Good Proxy server that is behind the enterprise firewall, as an access point. This is the recommended addressing method when the App Server is itself located behind the enterprise firewall. Notification content will be encrypted in transit from behind the enterprise firewall all the way to the destination device or computer when this method is used. This method is also compatible with the receipt by App Servers of callbacks from the BlackBerry Dynamics infrastructure, as discussed below.

Requests can be addressed to an access point by specifying its server address and port number directly. Requests could also be addressed indirectly, through a load balancer, virtual IP address, or other component of the enterprise network. The server address would be provided by the enterprise's IT or network administration. By default, a BlackBerry Dynamics enterprise access point will accept:

  • Plain HTTP connections on port 17080.
  • Secure HTTP connections on port 17433.

It is recommended that production App Servers connect over a secure connection, and that plain HTTP is only used during the development phase. See under Certificates for Service Requests, below, for details of the electronic certificates that could be required when addressing service requests on a secure connection. Any certificates that are required should be obtained from the enterprise IT or network administration.

BlackBerry Dynamics supports clustering of access point servers. If clustering is in use, then there will be a number of servers that can used as the access point for this API. A list of these servers' addresses can be obtained by utilizing the getGPSservers service, which is documented on the enterprise access point servers list API page. Note that this API is itself hosted on an enterprise access point, so at least one server address must still be provided by the enterprise's IT or network administration, at some point. That page also describes how the App Server should select a single server from the returned list.

For the purpose of this API, then, there will be a single server address or IP address to which service requests are sent. This will either be the address of the NOC server, or of a BlackBerry Dynamics access point server or network component at the enterprise.

Certificates for Service Requests

Service requests in this API can be sent over a secure HTTP connection, the establishment of which requires the usual presentation and trusting of electronic certificates.

When service requests are addressed to an enterprise access point over a secure connection, its certificate must be trusted by the App Server. The certificate presented will be one of the following:

  • Certificate signed by the Certificate Authority (CA) generated for the management console during installation.
  • Certificate signed by an Enterprise CA.
  • Certificate signed by a trusted third party CA.

The first of these is the default, applying unless action has been taken to install a different root CA on the management console.

If the certificate is signed by a management console or Enterprise CA, then a corresponding CA certificate must also be installed on the App Server as a trusted CA. If no such certificate is installed, the App Server will not be able to establish a secure HTTP connection to the access point, and hence won't be able to send service requests.

Service requests in this API can instead be sent to the NOC.

When service requests are addressed to the NOC, the NOC's certificate must be trusted by the App Server. The NOC accepts HTTP over TLS and always presents a certificate signed by a generally trusted authority that is valid for this purpose.

Certificates for Callbacks

Some features of the Push Channel Service API involve the use of callbacks. To utilize these features, the App Server provides a URL to which an HTTP request will be sent in order to invoke the callback. The URL can refer to a server that is only accessible from within the enterprise firewall, an enterprise App Server, or to a server that is accessible to the Internet, an Internet App Server. The scheme part of the URL can be either https or plain http. The accessibility of the host and the scheme of the callback URL determine the requirements for certificates.

Note that callbacks hosted on enterprise App Servers will only be invoked if the original service call was addressed to an access point at the enterprise. Callbacks on enterprise App Servers won't be invoked if the original service call was addressed directly to the NOC.

Callbacks that are hosted on enterprise App Servers and invoked through plain HTTP do not require any certificates to be in place. The hosting server must, however, be configured to accept plain http connections.

Callbacks that are hosted on enterprise App Servers and invoked through secure HTTP require a certificate to be in place at the hosting server. The certificate must be trusted by the enterprise access point, which will invoke the callback. For example, if the App Server certificate is signed by an Enterprise CA, then a corresponding certificate must also be installed as a trusted CA on the enterprise access point server.

Callbacks that are hosted on Internet App Servers and invoked through secure HTTP also require a certificate to be in place at the App Server. The certificate must be signed by a generally trusted authority. A self-signed certificate won't be accepted here.

It isn't recommended to host plain HTTP callbacks on Internet App Servers.

checkToken Service

Call this service when the App Server is sent a Push Channel token by a front-end application. The service will validate the token, and respond accordingly. The App Server should then store the token for later use, if the token was valid.

Push Channel tokens are used to address Push Channel notifications, see notify, below.

This service can also be used to register callbacks, see the disconnectURL and pingURL parameters in the following. Note that callbacks are registered against a particular token, not against the App Server as such.

Method
GET
Path
/GNP1.0
Protocol
HTTP/1.1
Host
NOC or enterprise access point address and port number

See under Addressing Service Requests, above, for details. This is a standard HTTP field.

Parameters
method=checkToken
Mandatory parameter specifying the checkToken method.
disconnectURL= disconnectCallbackURL
Register a Disconnect Callback for the token. Passing this parameter causes the application server to be notified of disconnection by the front-end application that was issued the token. The notification takes the form of an isDisconnected message, see below. If this parameter is omitted, or blank, then no message will be sent when the front-end application disconnects.
See also:
disconnect
pingURL= pingCallbackURL
Enable Ping Failure Detection for the token. Passing this parameter causes the application server to be periodically checked by the NOC. The check takes the form of an AppServer Ping message, see below. If this parameter is omitted, or blank, Ping Failure Detection is disabled for the token.
See also:
onChannelPingFail
minPingInterval= minutes
Specify the minimum time that the NOC must wait after sending an AppServer Ping message for the token, before sending another. The time is expressed as a number of minutes. This is only relevant if a pingURL was also specified, see above.
Headers
X-Good-GNP-Token: received_token

Mandatory header containing a Push Channel token. This will have been sent to the application server by the front-end application.

Each request to this service may contain only a single instance of this header. However, multiple service invocations may be sent over a single TCP connection using the standard keep-alive mechanism of the HTTP1.1 protocol.

See also:
GDPushChannel
Response
The service returns a standard HTTP/1.1 response. The status will be 200, if the NOC checkToken service received the request. The Content-Length will be zero. A response header will be included, as follows.
X-Good-GNP-Code: code description
This header will contain a numeric status code, possibly followed by a status text. The codes used are as follows.
CodeTextDescription
100OKSuccess.
200UnsupportedThe specified protocol version is unsupported.
401Token format errorThe format of the supplied token is not recognized.
402Invalid tokenThe token is not valid for this application.
403Terminal is disconnectedThe token was valid, but the Terminal that owns it is not currently connected.
404URL format not supportedA supplied URL has an invalid or unsupported format.
Examples

Verify token

 GET /GNP1.0?method=checkToken
     &pingURL=https%3A%2F%2Fmyappserver.com%2Fping%3Fabc%3D1234
     &disconnectURL=https%3A%2F%2Fmyappserver.com%2Fdisconnect%3Fabc%3D1234
     &minPingInterval=5 HTTP/1.1
 Host: gdmdc.good.com:443
 X-Good-GNP-Token: ABCD1234 9B2 010.010.010.010 5678901234 1234567890
     5618A9CBA76F93C54ABC739AF36BDF30

(Long lines have been wrapped for ease of reading, and indented.)

Token verification response

 HTTP/1.1 200 OK
 Content-Length: 0
 Date: Fri, 17 Jul 2009 19:55:08 GMT
 X-Good-GNP-Code: 100 OK

notify Service

Call this service to send a Push Channel notification to a front-end application. This generates a Channel Message event in the application that was issued the token.

If the App Server is located behind the enterprise firewall, the service call should be addressed to an enterprise access point. The notification will then be encrypted between the access point and the BlackBerry Dynamics runtime embedded in the front-end application.

See also:
onChannelMessage
Note:
This service represents the principal capability of the Push Channel feature. Because this service is provided by the Blackberry Dynamics platform, it is unnecessary for the application code to maintain a constant connection to the App Server.
Method
POST
Path
/GNP1.0
Protocol
HTTP/1.1
Host
NOC or enterprise access point address and port number

See under Addressing Service Requests, above, for details. This is a standard HTTP field.

Parameters
method=notify
Mandatory parameter specifying the notify method.
Headers
X-Good-GNP-Token: address_token

Mandatory header containing a Push Channel token. This will have been sent to the server by the front-end application, and subsequently verified by calling checkToken, see above.

Each request to this service may contain only a single instance of this header. However, multiple service invocations may be sent over a single TCP connection using the standard keep-alive mechanism of the HTTP1.1 protocol.

Content-Type: text/plain; charset=utf-8
Mandatory header, with standard meaning. Only the above encoding is supported.
Content-length: body_length
Mandatory header, with standard meaning. See Body, below.
Body
Set the body of the POST request to the required content of the Push Channel notification message. The NOC will deliver the content to the front-end application as part of the push channel notification. The body can be empty, in which case the front-end application will receive a push channel notification with no "payload". The maximum supported size of body is 1 megabyte.
See also:
onChannelMessage
Response
The service returns a standard HTTP/1.1 response. The status will be 200, if the NOC notify server received the request. The Content-Length will be zero. A response header will be included, as follows.
X-Good-GNP-Code: code description
This header will contain a numeric status code, possibly followed by a status text. The codes used are as follows:
CodeTextDescription
100OKSuccess.
200UnsupportedThe specified protocol version is unsupported.
401Token format errorThe format of the supplied token is not recognized.
402Invalid tokenThe token is not valid for this application.
403Terminal is disconnectedThe token was valid, but the Terminal that owns it is not currently connected.
407Unsupported encodingThe specified encoding is not supported.
Examples

Send push channel notification

 POST /GNP1.0?method=notify HTTP/1.1
 Host: gdmdc.good.com:443
 Content-Type: text/plain; charset=utf-8
 Content-length: 30
 X-Good-GNP-Token: ABCD1234 9B2 010.010.010.010 5678901234 1234567890
  5618A9CBA76F93C54ABC739AF36BDF30

 This is a notification payload

(Long lines have been wrapped for ease of reading, and indented.)

Push channel notification response

 HTTP/1.1 200 OK
 Content-Length: 0
 Date: Fri, 17 Jul 2009 19:55:08 GMT
 X-Good-GNP-Code: 100 OK

isDisconnected Callback

This callback is invoked when a terminal has disconnected. Invocation notifies the App Server that the front-end application that was issued a particular Push Channel token has disconnected.

Method
GET
Path
As specified in the disconnectURL parameter of the checkToken request. A path and query string may be included. See above.
Protocol
HTTP/1.1
Parameters
See under Path, above. No further parameters will be added.
Headers
X-Good-GNP-Token: disconnected_token
This header will contain the Push Channel token for the front-end application that has disconnected.
Example

Disconnection message

 GET /disconnect?abc=1234 HTTP/1.1
 Host: myappserver.com
 X-Good-GNP-Token: ABCD1234 9B2 010.010.010.010 5678901234 1234567890
     5618A9CBA76F93C54ABC739AF36BDF30

(Long lines have been wrapped for ease of reading, and indented.)

In the above, the original disconnectURL would have been one of the following:

  • https://myappserver.com/disconnect?abc=1234
  • http://myappserver.com/disconnect?abc=1234

Which, in the checkToken service request, would have appeared as one of the following, respectively:

  • disconnectURL=https%3A%2F%2Fmyappserver.com%2Fdisconnect%3Fabc%3D1234
  • disconnectURL=http%3A%2F%2Fmyappserver.com%2Fdisconnect%3Fabc%3D1234 .

AppServer Ping Callback

This callback is invoked periodically, to check that the App Server still recognizes tokens that were previously checked.

The NOC will send a list of tokens to the App Server. The server must then respond with the list of those tokens that are recognized. Any tokens that were sent by the NOC, but aren't in the server's response, generate a Ping Fail event.

See also:
onChannelPingFail
Method
POST
Path
As specified in the pingURL parameter of the checkToken request. A path and query string may be included. See above.
Protocol
HTTP/1.1
Parameters
See under Path, above. No further parameters will be added.
Headers
Content-Type: text/plain; charset=utf-8
Standard header. Only the above encoding is supported.
Content-length: body_length
Standard header. See Body, below.
Body
The body of the POST request will contain a list of token prefixes, separated by commas. A token prefix is the leading portion of a token, including only the first three space-separated components.
Response
Send a standard HTTP/1.1 response to this message. The HTTP status should be 200. In the body of the response, put the list of token prefixes that were recognized. Only tokens prefixes that were in the request should be in the response. The required format is as follows.
Response headers
X-Good-GNP-Code: result_code
Send a numeric status code in this header, possibly followed by a status text. Use the following codes:
CodeTextDescription
100OKSuccess.
201Parse error.Invalid request. An error occurred on the server while parsing the request.
202Method not found.The requested remote-procedure does not exist or is not available.
203Invalid params.Invalid method parameters.
500-599Server error.Reserved for internal server errors.
Content-Type: text/plain; charset=utf-8
Mandatory header, with standard meaning. Only the above encoding is supported.
Content-length: body_length
Mandatory header, with standard meaning. See Response body, below.
Response body
Put the token prefixes that were recognized in the body of the response, separated by commas.
Examples

AppServer Ping message

 POST /ping?abc=1234 HTTP/1.1
 Host: myappserver.com
 Content-Type: text/plain; charset=utf-8
 Content-length: 87

 ABCD1234 9B2 010.010.010.010,ABCD1234 5DB9 010.010.010.010,ABCD1234 A67
 010.010.010.010

In the above, the original pingURL would have been one of the following, for all the tokens in the request body:

  • https://myappserver.com/ping?abc=1234
  • http://myappserver.com/ping?abc=1234

AppServer Ping response

This is an example response to the above request.

 HTTP/1.1 200 OK
 Content-Length: 58
 Content-Type: text/plain; charset=utf-8
 Date: Fri, 17 Jul 2009 19:55:08 GMT
 X-Good-GNP-Code: 100 OK

 ABCD1234 9B2 010.010.010.010,ABCD1234 5DB9 010.010.010.010

In the above response, the App Server notifies the NOC that it has not recognized one of the three token prefixes that were in the request. The front-end application that was issued the unrecognized token will receive a Ping Fail event.