-
- BlackBerry Dynamics
- Runtime library for Android applications
- 12.1.1.43
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.
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:
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.
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.
Latest Blackberry Dynamics SDK has the feature that supports talking to the regionalized push channel service. Regionalized push channel service host name would be communicated via push channel open notification. SeePushChannelEventType.Open for more details.
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:
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.
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:
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.
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.
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.
GET/GNP1.0HTTP/1.1NOC or enterprise access point address and port number
See under Addressing Service Requests, above, for details. This is a standard HTTP field.
method=checkTokendisconnectURL= disconnectCallbackURLpingURL= pingCallbackURLminPingInterval= minutespingURL was also specified, see above.X-Good-GNP-Token: received_tokenMandatory 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.
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| Code | Text | Description |
|---|---|---|
| 100 | OK | Success. |
| 200 | Unsupported | The specified protocol version is unsupported. |
| 401 | Token format error | The format of the supplied token is not recognized. |
| 402 | Invalid token | The token is not valid for this application. |
| 403 | Terminal is disconnected | The token was valid, but the Terminal that owns it is not currently connected. |
| 404 | URL format not supported | A supplied URL has an invalid or unsupported format. |
(Long lines have been wrapped for ease of reading, and indented.)
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.
POST/GNP1.0HTTP/1.1NOC or enterprise access point address and port number
See under Addressing Service Requests, above, for details. This is a standard HTTP field.
method=notifyX-Good-GNP-Token: address_tokenMandatory 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-8Content-length: body_lengthnotify server received the request. The Content-Length will be zero. A response header will be included, as follows.X-Good-GNP-Code: code description| Code | Text | Description |
|---|---|---|
| 100 | OK | Success. |
| 200 | Unsupported | The specified protocol version is unsupported. |
| 401 | Token format error | The format of the supplied token is not recognized. |
| 402 | Invalid token | The token is not valid for this application. |
| 403 | Terminal is disconnected | The token was valid, but the Terminal that owns it is not currently connected. |
| 407 | Unsupported encoding | The specified encoding is not supported. |
(Long lines have been wrapped for ease of reading, and indented.)
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.
GETdisconnectURL parameter of the checkToken request. A path and query string may be included. See above.HTTP/1.1X-Good-GNP-Token: disconnected_token(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=1234http://myappserver.com/disconnect?abc=1234Which, in the checkToken service request, would have appeared as one of the following, respectively:
disconnectURL=https%3A%2F%2Fmyappserver.com%2Fdisconnect%3Fabc%3D1234disconnectURL=http%3A%2F%2Fmyappserver.com%2Fdisconnect%3Fabc%3D1234 .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.
POSTpingURL parameter of the checkToken request. A path and query string may be included. See above.HTTP/1.1Content-Type: text/plain; charset=utf-8Content-length: body_lengthX-Good-GNP-Code: result_code| Code | Text | Description |
|---|---|---|
| 100 | OK | Success. |
| 201 | Parse error. | Invalid request. An error occurred on the server while parsing the request. |
| 202 | Method not found. | The requested remote-procedure does not exist or is not available. |
| 203 | Invalid params. | Invalid method parameters. |
| 500-599 | Server error. | Reserved for internal server errors. |
Content-Type: text/plain; charset=utf-8Content-length: body_length 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=1234http://myappserver.com/ping?abc=1234This is an example response to the above request.
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.