Manage Push Channel tokens and notifications. More...

Description

The Push Channel framework is a BlackBerry Dynamics feature used to receive notifications from an application server.

Use of the Push Channel feature in the application is dependent on:

Completion of BlackBerry Dynamics authorization processing.
Connection to the BlackBerry Dynamics infrastructure.

Push Channel data communication doesn't go via the proxy specified in the native settings of the device or computer on which the application is running, if any.

See also: Manuals page for the BlackBerry Dynamics enterprise servers for the Platform Overview.

Push Channel Usage

Push Channels are established by the BlackBerry Dynamics application, then used by the application server when needed. The sequence of events is as follows.

The application sets an event handler for Push Channel notifications.
The application requests a Push Channel token from the BlackBerry Dynamics proxy infrastructure.
The application sends the token to its server using, for example, a socket connection or HTTP request.
The application can now wait for a Push Channel notification.

Later, when the server has data for the user, the following steps take place:
The server sends a Push Channel notification message through the BlackBerry Dynamics proxy infrastructure. The message is addressed using the token.
The message is sent on, and the waiting application's event handler is invoked.

Later, when the server has more data for the user, the following steps take place:
The server sends another Push Channel notification message through the proxy infrastructure. The message is addressed using the same token.
The message is sent on, and the waiting application's event handler is invoked again.

Push Channel sequence diagram

The BlackBerry Dynamics platform keeps data communications between the application and server alive while the application 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.

Ping Failure

Ping Failure is an optional feature of the Push Channel framework. The application server can register a ping address after receiving the Push Channel token from the mobile application.

If the application server registers a ping address, then it will be periodically checked ("pinged") by the BlackBerry Dynamics Network Operation Center (NOC). If the server does not respond to a ping, then the NOC notifies the application that requested the corresponding Push Channel.

The purpose of this feature is to support servers that lose the Push Channel token when they are restarted.

See the Push Channel Back-End API for details of Ping Failure registration.

Programming Interface

The Push Channel programming interface is asynchronous and state-based. The application code creates a Push Channel object for each channel it will use, typically one per application server. When a channel changes state, or a channel event occurs, the BlackBerry Dynamics runtime notifies the application.

Notifications

To notify the application, the runtime sends an Intent, by local broadcast. The attributes of the Intent and its Bundle will specify the channel, and the details of the change or event that is being notified.

For all notifications:

The Intent action will be the GD_PUSH_CHANNEL_EVENT_ACTION value.
The Intent data scheme, data authority, and data path values together specify the particular channel to which the notification relates. There is a helper method, prepareIntentFilter , that creates an Intent Filter that will match notifications for a particular channel.
The Intent Bundle will contain a value that represents the type of the event or change that has occurred. The value can be extracted by passing the Intent to the getEventType class method.
The Intent Bundle may contain other values, depending on the event type. Values can be extracted using the appropriate helper functions:
- getToken .
- getPushChannelHost .
- getMessage .
- getErrorCode .
- getPingFailCode .

The application registers its receivers for Push Channel notifications by calling the GDAndroid.registerReceiver method.

State cycle

The availability of methods in the Push Channel programming interface, and what actions take place, are detailed below, and summarized in the following table. The table also summarizes which notifications are expected in each state.

State	Methods and actions	Expected notifications See Push Channel Constants
Prepared	Application can call `connect`: state becomes Connecting	None
Connecting	BlackBerry Dynamics runtime requests a new channel from the proxy infrastructure	`Error`: new state is Failed `Open`: new state is Open
Open	Application can call `disconnect`: state becomes Disconnecting	`Message`: no state change `PingFail`: no state change `Close`: new state is Disconnected
Disconnecting	BlackBerry Dynamics Runtime requests the proxy infrastructure to close the channel	`Message`: no state change `PingFail`: no state change `Close`: new state is Disconnected
Disconnected	Application can call `connect`: state becomes Connecting	None
Failed	Application can call `connect`: state becomes Connecting	None

The transitions in the above table are also shown in this diagram.

Push Channel state transition diagram

Note that an individual Push Channel might or might not be closed when the overall Push Channel service becomes unavailable.

See also: Push Channel Back-End API

Push Channel Identifiers

Every Push Channel must have an identifier. Identifiers must be unique within an application. A Push Channel identifier is a text string set by the application code. Note that Push Channel identifiers aren't the same as Push Channel tokens. Token values are set by the BlackBerry Dynamics infrastructure and runtime.

The following convention represents best practice for Push Channel identifiers.

A Push Channel identifier should be composed of a domain followed by a module name and an optional purpose. The parts are separated by full stops (periods). The following examples illustrate the convention.

Example: com.example.mobile-life.email

Domain is "com.example"
Name is "mobile-life"
Purpose is "email"

Example: com.example.dashboard

Domain is "com.example"
Name is "dashboard"
Purpose is omitted.

The rules for identifier part values are as follows.

Domain must be the reversal of an Internet domain that is owned by the developer organisation.
Name must be unique within all the organisation's applications, libraries, and other code modules that might create a Push Channel. Ensuring uniqueness of name values is the responsibility of the developer organisation.
Purpose need only be used in the case that a single application, library, or other code module uses more than one Push Channel. Ensuring uniqueness of purpose values is the responsibility of the code module's developer.

Code Snippets

The following code snippets illustrate some common tasks.

Open Push Channel

The following snippet shows a Push Channel being created and opened after checking that the service is available.

if (GDConnectivityManager.getActiveNetworkInfo().isPushChannelAvailable()) {
    System.out.println("Push Channel service available");
    _channel = new PushChannel("com.example.dashboard");
    IntentFilter intentFilter = _channel.prepareIntentFilter();
 
    GDAndroid.getInstance().registerReceiver(new BroadcastReceiver() {
         @Override
         public void onReceive(Context context, Intent intent) {
             switch (PushChannel.getEventType(intent)) {
                   case Open:
                       break;
                   case Close:
                       break;
                   case Error:
                       break;
                   case Message:
                       break;
                   case PingFail:
                       break;
             }
        }
    }, intentFilter);
 
    _channel.connect();
}

The above snippet shows the following taking place:

Availability logged to the system monitor.
Allocation of a Push Channel object.
Creating an Intent Filter that will match only notifications from the new channel.
Instantiation of an anonymous inner class object as the event handler for all notifications from the channel. (The handler is a dummy to keep the snippet clear.)
Attempt to connect the Push Channel.

The attempt is asynchronous. The associated Open notification would be received if and when the attempt is succesful (not shown).

Close Push Channel

_channel.disconnect();

The above snippet shows: Request to disconnect the Push Channel.

The request is asynchronous. The associated Close notification would be received when the closure is finalized (not shown).

Code Snippets

The following code snippets illustrate some common tasks.

Handle Push Channel Opening

The following snippet shows a simple handler for when a Push Channel opens.

@Override
public void onReceive(Context context, Intent intent) {
    switch (PushChannel.getEventType(intent)) {
       case Open:
           String token = PushChannel.getToken(intent);
           System.out.println("Open token: " + token);
           String host = PushChannel.getPushChannelHost(intent);
           if (host != NULL) {
               System.out.println("Open push channel host: " + host);
               myApp.pushChannelHost = host;
           }
           myApp.pushIsOpen = true;
           myApp.pushToken = token;
           myApp.sendPushToken();
       break;
    }
}

The above snippet shows the following taking place:

The Push Channel event type is extracted from the Intent.
The Push Channel token is extracted from the Intent.
The token is logged to the system monitor.
The application flags internally that its channel is open, and stores the token value.
The sendPushToken method in the application is called.

The sendPushToken method, which would be written by the application developer, would send the token to the application server. This could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.

The server will use the token to address Push Channel notification messages back to the application. These would be received by the application's Push Channel event handler code.

Receive Push Channel Message

@Override
public void onReceive(Context context, Intent intent) {
    switch (PushChannel.getEventType(intent)) {
       case Message:
           String data = PushChannel.getMessage(intent);
           System.out.println("Message data: " + data);
           myApp.processPush(data);
       break;
    }
}

The above snippet shows the following taking place when a Push Channel message is received:

The Push Channel event type is extracted from the Intent.
The Push Channel message is extracted from the Intent.
The message is logged to the system monitor.
The processPush method in the application is called and passed the content of the message.

The processPush method, which would be written by the application developer, could initiate any of the following actions:

Alert the user that new data is available.
Connect to the application server to retrieve the data. (Connection could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.)

Handle Channel Closure

@Override
public void onReceive(Context context, Intent intent) {
    switch (PushChannel.getEventType(intent)) {
       case Close:
           String token = PushChannel.getToken(intent);
           System.out.println("Close token: " + token);
           myApp.pushIsOpen = false;
           myApp.discardPushToken(data);
       break;
    }
}

The above snippet shows a simple channel closure handler. The following takes place when the Push Channel is closed:

The Push Channel event type is extracted from the Intent.
The Push Channel token is extracted from the Intent.
The token is logged to the system monitor.
The application flags internally that its channel isn't open.
The application discardPushToken method is called. The token of the closed channel is passed as a parameter.

The discardPushToken method would delete the application's copy of the token, possibly after checking that it matches the previous stored token.

The method could also initiate connection of a new Push Channel, which would have a new token. See connect .

Handle Channel Error

@Override
public void onReceive(Context context, Intent intent) {
    switch (PushChannel.getEventType(intent)) {
       case Error:
           int error = PushChannel.getErrorCode(intent, 0)
           System.out.println("Error error: " + error);
           myApp.pushIsOpen = false;
           myApp.discardPushToken();
       break;
    }
}

The above snippet shows a simple Error handler.

The handler logs the error code to the system monitor, flags the channel's state as not connected, records the error code in the application, then calls the application discardPushToken method.

The discardPushToken method could do any of the following:

Delete the application's copy of the token.
Set the error state in an ongoing status display.
Depending on the error code, initiate connection of a new Push Channel, which would have a new token. See connect .

See under Ping Failure in the Push Channel Back-End API for an explanation of the Ping Failure feature.

Handle Ping Failure

@Override
public void onReceive(Context context, Intent intent) {
    switch (PushChannel.getEventType(intent)) {
       case PingFail:
           int error = PushChannel.getPingFailCode(intent, 0)
           System.out.println("PingFail error: " + error);
           if ( error == 605 ) {
               myApp.resendPushToken();
           }
       break;
    }
}

The above snippet shows a simple Ping Failure handler.

The handler logs the error code to the system monitor, then calls the application resendPushToken method if the token was lost.

The resendPushToken method, which would be written by the application developer, would send the application's stored token to the application server. This could use a socket, an HTTP request, or another means of communication. From the Push Channel point of view, this is an out-of-band communication.

The resendPushToken method should expect that the server is not immediately available, perhaps employing a retry policy.

Public Member Functions
	PushChannel (String pushChannelIdentifier)
	Constructor that prepares a new Push Channel. More...

void	connect ()
	Connect Push Channel. More...

void	disconnect ()
	Disconnect Push Channel. More...

PushChannelState	getState ()
	Push Channel state. More...

String	getDataPath ()
	Intent data path for filtering at the receiver. More...

String	getDataScheme ()
	Intent data scheme for filtering at the receiver. More...

String	getDataAuthority ()
	Intent data authority for filtering at the receiver. More...

IntentFilter	prepareIntentFilter ()
	Intent Filter for receiver registration. More...

Static Public Member Functions
static PushChannelEventType	getEventType (Intent intent)
	Get event type from Push Channel notification. More...

static String	getToken (Intent intent)
	Get Push Channel token from notification. More...

static String	getPushChannelHost (Intent intent)
	Get Push Channel Host Name from notification. More...

static String	getMessage (Intent intent)
	Get message data from Push Channel notification. More...

static int	getErrorCode (Intent intent, int defaultValue)
	Get error code from Push Channel notification. More...

static int	getPingFailCode (Intent intent, int defaultValue)
	Get ping failure reason code from Push Channel notification. More...

Static Public Attributes
static final String	GD_PUSH_CHANNEL_EVENT_ACTION = "com.good.gd.PUSH_CHANNEL_EVENT"
	Intent action for Push Channel notifications. More...

Constructor & Destructor Documentation

◆ PushChannel()

PushChannel ( String pushChannelIdentifier )

Call this method to construct a new Push Channel object. This method does not initiate data communication. See connect .

Parameters

pushChannelIdentifier String containing the identifier for this Push Channel, see under Push Channel Identifiers, above.

Exceptions

com.good.gd.error.GDNotAuthorizedError if BlackBerry Dynamics authorization processing has not yet completed.

Member Function Documentation

◆ connect()

void connect ( )

Call this method to open the Push Channel connection. This method can only be called when the channel isn't open.

This method causes a request for a Push Channel to be sent to the BlackBerry Dynamics Network Operation Center (NOC). The NOC will create the channel, and issue a Push Channel token, which can then be used to identify the channel.

The connection attempt is asynchronous. An Intent with a Bundle will be sent by local broadcast to notify the application of the result. If the attempt succeeds, the Bundle will have an event type of PushChannelEventType.Open, and will contain the token. If the attempt fails, the Bundle will instead have an event type of PushChannelEventType.Error, and will contain an error code. The following class methods can be used to extract the values from the Bundle.

Exceptions

com.good.gd.error.GDNotAuthorizedError if BlackBerry Dynamics authorization processing has not yet completed.

◆ disconnect()

void disconnect ( )

Call this method to initiate permanent disconnection of the Push Channel. This method can only be called when the channel is open.

This method causes a request for Push Channel termination to be sent to the BlackBerry Dynamics Network Operation Center (NOC). The NOC will delete the channel, and invalidate the Push Channel token that was issued when the channel was initially opened, see connect .

Disconnection is asynchronous. When disconnection is complete, an Intent with a Bundle is sent by local broadcast to notify the application. The Bundle will have an event type of PushChannelEventType.Close. The following class method can be used to extract the value from the Bundle.

getEventType .

Note. This method is for permanent closure of the channel. Transient suspension of Push Channel notifications may be more easily accomplished out-of-band, by direct communication with the application server.

If the connection with the NOC is open and operating, and the application server that was sent the token registered for isDisconnected, then a disconnect notification will be sent to the application server, by the NOC. See the Push Channel Back-End API.

Exceptions

com.good.gd.error.GDNotAuthorizedError if BlackBerry Dynamics authorization processing has not yet completed.

◆ getState()

PushChannelState getState ( )

Returns: PushChannelState value for the current state of the channel that corresponds to this instance.

◆ getDataPath()

String getDataPath ( )

This method returns the Intent data path for Push Channel notifications on this channel. The prepareIntentFilter method returns an Intent Filter that uses this value. This separate method is provided for completeness.

Returns: String containing the Intent data path for this channel.

◆ getDataScheme()

String getDataScheme ( )

This method returns the Intent data scheme for Push Channel notifications on this channel. The prepareIntentFilter method returns an Intent Filter that uses this value. This separate method is provided for completeness.

Returns: String containing the Intent data scheme for this channel.

◆ getDataAuthority()

String getDataAuthority ( )

This method returns the Intent data authority for Push Channel notifications on this channel. The prepareIntentFilter method returns an Intent Filter that uses this value. This separate method is provided for completeness.

Returns: String containing the Intent data authority for this channel.

◆ prepareIntentFilter()

IntentFilter prepareIntentFilter ( )

This method returns an Intent Filter that will match Push Channel notifications on the channel that corresponds to the PushChannel instance.

The Intent Filter will be based on the GD_PUSH_CHANNEL_EVENT_ACTION action string, and the values that would be returned by the getDataScheme, getDataAuthority, and getDataPath methods. This method is a shortcut.

Returns: android.content.IntentFilter instance that is suitable to pass to the GDAndroid.registerReceiver method.

◆ getEventType()

static PushChannelEventType getEventType ( Intent intent )

static

Parameters

intent Intent that was sent by local broadcast for a Push Channel notification.

Returns: PushChannelEventType value for the type of event being notified. See Push Channel Constants for documentation.

◆ getToken()

static String getToken ( Intent intent )

static

This method is a helper that returns the Push Channel token from a notification Intent.

Before calling this method, call getEventType to check that the notification is for an event of a type that contains a token:

Parameters

intent Intent that was sent by local broadcast for a Push Channel notification.

Returns: String containing the Push Channel token.

◆ getPushChannelHost()

static String getPushChannelHost ( Intent intent )

static

This method is a helper that returns the Push Channel Host from a notification Intent.

Before calling this method, call getEventType to check that the notification is for an event of a type that contains a token:

PushChannelEventType.Open

Parameters

intent Intent that was sent by local broadcast for a Push Channel notification.

Returns: String containing the Push Channel Host Name or null if the Host Name is not applicable.

◆ getMessage()

static String getMessage ( Intent intent )

static

This method is a helper that returns the Push Channel message data from a notification Intent.

Before calling this method, call getEventType to check that the notification is for a PushChannelEventType.Message event.

Parameters

intent Intent that was sent by local broadcast for a Push Channel notification.

Returns: String containing the message.

◆ getErrorCode()

static int getErrorCode	(	Intent	intent,
		int	defaultValue
	)

static

This method is a helper that returns the error code from a Push Channel notification Intent.

Before calling this method, call getEventType to check that the notification is for a PushChannelEventType.Error event.

Parameters

intent	Intent that was sent by local broadcast for a Push Channel notification.
defaultValue	`int` to return in case there is no error code in the notification.

Returns: int error code, if present in intent, or the defaultValue otherwise.

◆ getPingFailCode()

static int getPingFailCode	(	Intent	intent,
		int	defaultValue
	)

static

This method is a helper that returns the ping failure reason code from a Push Channel notification Intent.

Before calling this method, call getEventType to check that the notification is for a PushChannelEventType.PingFail event.

Parameters

intent	Intent that was sent by local broadcast for a Push Channel notification.
defaultValue	`int` to return in case there is no ping failure code in the notification.

Returns: int ping failure code, if present in intent, or the defaultValue otherwise.

Member Data Documentation

◆ GD_PUSH_CHANNEL_EVENT_ACTION

final String GD_PUSH_CHANNEL_EVENT_ACTION = "com.good.gd.PUSH_CHANNEL_EVENT"

static

Intent action string for Push Channel notifications. The prepareIntentFilter method returns an Intent Filter that uses this value. This separate constant is provided for completeness.

See also: prepareIntentFilter .

Description

Push Channel Usage

Ping Failure

Programming Interface

Notifications

State cycle

Push Channel Identifiers

Code Snippets

Open Push Channel

Close Push Channel

Code Snippets

Handle Push Channel Opening

Receive Push Channel Message

Handle Channel Closure

Handle Channel Error

Handle Ping Failure

Public Member Functions

Static Public Member Functions

Static Public Attributes

Constructor & Destructor Documentation

◆ PushChannel()

Member Function Documentation

◆ connect()

◆ disconnect()

◆ getState()

◆ getDataPath()

◆ getDataScheme()

◆ getDataAuthority()

◆ prepareIntentFilter()

◆ getEventType()

◆ getToken()

◆ getPushChannelHost()

◆ getMessage()

◆ getErrorCode()

◆ getPingFailCode()

Member Data Documentation

◆ GD_PUSH_CHANNEL_EVENT_ACTION