Class: GDPushChannel

GDPushChannel()

This class encapsulates the GD Push Channel object. The Push Channel framework is a BlackBerry Dynamics (GD) feature used to receive notifications from an application server. Note that the GD Push Channel feature is not part of the native iOS notification feature set.
Push Channels are established from the client end, then used by the server when needed. The sequence of events is as follows:
  1. The client sets an event handler for Push Channel notifications
  2. The client application requests a Push Channel token from the BlackBerry Dynamics proxy infrastructure
  3. The client application sends the token to its server using, for example, a socket or HTTP request
  4. The client can now wait for a Push Channel notification
The BlackBerry Dynamics platform keeps data communications between client and server alive while the client is waiting for a Push Channel notification. This is achieved by sending "heartbeat" messages at an interval that is dynamically optimized for battery and network performance.

Constructor

new GDPushChannel()

Properties:
Name Type Description
onChannelResponse function This function is the callback handler that is called whenever a response is returned from the channel connection. This function should check the value of the responseType returned and determine the required action to take. If the responseType = "open", then the channelID returned in the response should be used to reference this channel in subsequent calls over this connection (see GDPushChannel.open). NOTE: This function is required to be a non-null value.
Source:

Methods

close(channelID)

Call this function to initiate permanent disconnection of the Push Channel. This function creates a request for Push Channel termination to be sent to the BlackBerry Dynamics proxy infrastructure Network Operating Center (NOC). The NOC will delete the channel, and invalidate the Push Channel token that was issued when the channel was initially opened.
Parameters:
Name Type Description
channelID string The unique ID for the push channel to close.
Source:
Example
See the example above (it is added to GDPushChannel.open() method).

isAvailable(responseCallback) → {string}

This function returns the current status of the Push Channel connection.
Parameters:
Name Type Description
responseCallback function Callback function to invoke when the function returns. A single result string will be passed as the input to the callback function: "true" or "false".
Source:
Returns:
"true" or "false".
Type
string
Example
See the example <a href="./GDPushChannel.html">here</a>

open() → {GDPushChannelResponse}

Call this function to open the Push Channel. This function can only be called when the channel is not opened. This function creates a request for a Push Channel to be sent to the Good Dynamics proxy infrastructure Network Operating Center (NOC). The NOC will create the channel, and issue a Push Channel token, which can then be used to identify the channel. The application code that handles the Intent must initiate sending of the Push Channel token to the application server, out of band. The application server will then be able to use the token to address Push Channel messages back to the application, via the BlackBerry Dynamics proxy infrastructure. See the Push Channel Back-End API of Blackberry Dynamics Docs ( Push Channel Open & Push Channel Back-End API of Blackberry Dynamics).
Source:
Returns:
A push channel response object in JSON format. The result should be parsed and saved as a GDPushChannelResponse object in the callback handler. If the channel was opened then the response object will be initialized with a channelID property that can be used to reference this channel connection. Additionally, the response will also contain a token that uniquely identifies the device associated with this push channel. Since this is an asynchronous call, the response will be returned via the onChannelResponse callback. Note that it can take some time for establishing push connection during opening first Push Channel. Please, wait until "onChannelResponse" callback is called with "GDPushChannelResponse" response object.
Type
GDPushChannelResponse
Example
function myPushChannel() {
    var savedChannelID,
        pushChannelToken;
    var channel = new window.plugins.GDPushChannel(pushChannelResponse);
    channel.open();

    channel.isAvailable(function(result) {
        console.log("GDPushChannel status: ", result);
    });

    //-- GDPushChannelResponse
    function pushChannelResponse(response) {
        try {
            var channelResponse = channel.parseChannelResponse(response);

            console.log("Got response channelID: " + channelResponse.channelID);
            console.log("Got response responseType: " + channelResponse.responseType);
            console.log("Got response responseData: " + channelResponse.responseData);
            switch (channelResponse.responseType) {
                case "open":
                    savedChannelID = channelResponse.channelID;
                    pushChannelToken = channelResponse.responseData;
                    console.log("Channel connection opened with ID :" + savedChannelID);
                    break;

                //  Send application server the savedChannelID (token) here at following format:
                //   POST https://gdmdc.good.com//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: pushChannelToken
                //  For more details see Push Channel Back-End API:
                //   https://developer.blackberry.com/devzone/files/blackberry-dynamics/ios/_g_n_p.html

                case "message":
                    // handle pushed message from the server
                    channel.close(channelResponse.channelID);
                    break;
                case "error":
                    console.log("Received an error status from the channel connection.");
                    break;
                case "close":
                    console.log("Channel connection closed successfully.");
                    break;
                case "pingFail":
                    break;
                default:
                    break;
            }
        } catch (e) {
            throw new Error("Invalid response object sent to channel response callback handler.");
        }
    };

};

parseChannelResponse(responseText) → {GDPushChannelResponse}

Call this function to transform the push channel response text into a GDPushChannelResponse object.
Parameters:
Name Type Description
responseText string A string representing the push channel response text.
Source:
Returns:
The push channel response object.
Type
GDPushChannelResponse
Example
See the example <a href="./GDPushChannel.html">here</a>