GDPushChannel Class Reference

Manage Push Channel tokens and notifications. More...

#import <BlackBerryDynamics/GD/GDPush.h>

Description

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

Note that the BlackBerry Dynamics Push Channel feature is not part of the native iOS notification feature set.

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.

Thread support statement

Background Execution

Local and Remote Notification Programming Guide on the apple.com developer website.

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.

1. The application sets an event handler for Push Channel notifications.
2. The application requests a Push Channel token from the BlackBerry Dynamics proxy infrastructure.
3. The application sends the token to its server using, for example, a socket connection or HTTP request.
4. The application can now wait for a Push Channel notification.
   
   Later, when the server has data for the user, the following steps take place:
   
   
5. The server sends a Push Channel notification message through the BlackBerry Dynamics proxy infrastructure. The message is addressed using the token.
6. 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:
   
   
7. The server sends another Push Channel notification message through the proxy infrastructure. The message is addressed using the same token.
8. 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 posts an NSNotification.

For all NSNotification instances that are Push Channel notifications:

• The object will be the Push Channel object for the channel to which the notification relates.
• The name depends on the type of event or change that has occurred. It will be one of the following values.
  • GDPushChannelOpenedNotification .
  • GDPushChannelMessageNotification .
  • GDPushChannelClosedNotification .
  • GDPushChannelErrorNotification .
  • GDPushChannelPingFailedNotification .
• The contents of the user information dictionary, userInfo, depends on the event type. The following values are used as keys.
  • GDPushChannelTokenKey .
  • GDPushChannelHostKey .
  • GDPushChannelMessageKey .
  • GDPushChannelErrorKey .

Push Channel state changes can also be detected by key-value observing (KVO) of the state property.

See also

Key-Value Observing Programming Guide on the apple.com developer website.

NSNotificationCenter class reference on the apple.com developer website.

State cycle

The availability of functions 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	Functions 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	GDPushChannelErrorNotification: new state is Failed GDPushChannelOpenedNotification: new state is Open
Open	Application can call disconnect: state becomes Disconnecting	GDPushChannelMessageNotification: no state change GDPushChannelPingFailedNotification: no state change GDPushChannelClosedNotification: new state is Disconnected
Disconnecting	BlackBerry Dynamics Runtime requests the proxy infrastructure to close the channel	GDPushChannelMessageNotification: no state change GDPushChannelPingFailedNotification: no state change GDPushChannelClosedNotification: 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

Notification feature differences

The capabilities of the BlackBerry Dynamics Push Channel are different to the capabilities of the native Apple Push Notification Service (APNS) in the following ways.

Only native notifications can be received when the application is in background. This might change in a future release of iOS.

In principle, native notifications alert the user, not the application. Having been alerted, the user may choose to open the application. BlackBerry Dynamics Push Channel messages alert the application, which in turn may alert the user.

BlackBerry Dynamics Push Channel messages can include a "payload" of application data from the server. The application data is conveyed by the proxy infrastructure from the server to the application.

Native notifications may be received whenever the device has a connection to APNS. BlackBerry Dynamics Push Channel messages may be received whenever the application has a connection to the BlackBerry Dynamics infrastructure.

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 ([GDReachability sharedInstance].isPushChannelAvailable) {
    NSLog( @"Push Channel service available");
    myChannel = [[GDPushChannel alloc] initWithIdentifier:@"com.example.dashboard"];
    myHandler = [[AppChannelHandler alloc] init]
    NSNotificationCenter *notificationCenter = [NSNotificationCenter defaultCenter];
    [notificationCenter addObserver:myHandler
                           selector:@selector(channelOpenedNotification:)
                               name:GDPushChannelOpenedNotification
                             object:myChannel];
 
    [notificationCenter addObserver:myHandler
                           selector:@selector(channelClosedNotification:)
                               name:GDPushChannelClosedNotification
                             object:myChannel];
 
    [notificationCenter addObserver:myHandler
                           selector:@selector(channelErrorNotification:)
                               name:GDPushChannelErrorNotification
                             object:myChannel];
 
    [notificationCenter addObserver:myHandler
                           selector:@selector(channelPingFailedNotification:)
                               name:GDPushChannelPingFailedNotification
                             object:myChannel];
 
    [notificationCenter addObserver:myHandler
                           selector:@selector(channelMessageReceivedNotification:)
                               name:GDPushChannelMessageNotification
                             object:myChannel];
    [myChannel connect];
}

The above snippet shows the following taking place:

• Availability logged to the system monitor.
• Allocation of a Push Channel object.
• Allocation of an application Push Channel event handler.
• Registration of the new handler for all notifications from the channel. All notifications are sent to the same handler instance, but to different functions, specified as selectors.
• Attempt to connect the Push Channel.

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

Close Push Channel

[myChannel disconnect];

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

The request is asynchronous. The associated GDPushChannelClosedNotification 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.

-(void)channelOpenedNotification:(NSNotification *)notification
{
    NSString *token = notification.userInfo[GDPushChannelTokenKey];
    NSLog(@"GDPushChannelOpenedNotification token: %@", token);
    NSString *host = notification.userInfo[GDPushChannelHostKey];
    if (host != nil) {
        NSLog(@"GDPushChannelOpenedNotification push channel host: %@", host);
        myApp.pushChannelHost = host;
    }
    myApp.pushIsOpen = YES;
    myApp.pushToken = token;
    [myApp sendPushToken];
}

The above snippet shows the following taking place:

• The Push Channel token is extracted from the user information dictionary in the notification.
• The token is logged to the system monitor.
• The application flags internally that its channel is open, and stores the token value.
• The sendPushToken function in the application is called.

The sendPushToken function, 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

- (void)channelMessageReceivedNotification:(NSNotification *)notification
{
    NSString *data = notification.userInfo[GDPushChannelMessageKey];
    NSLog(@"channelMessageReceivedNotification message: %@", data);
    [myApp processPush:data];
}

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

• The Push Channel message is extracted from the user information dictionary in the notification.
• The message is logged to the system monitor.
• The processPush function in the application is called and passed the content of the message.

The processPush function, 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

-(void)channelClosedNotification:(NSNotification *)notification
{
    NSString *data = notification.userInfo[GDPushChannelTokenKey];
    NSLog(@"GDPushChannelClosedNotification: %@", data);
    myApp.pushIsOpen = NO;
    [myApp discardPushToken:data];
}

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

• The token is logged to the system monitor.
• The application flags internally that its channel isn't open.
• The application discardPushToken function is called. The token of the closed channel is passed as a parameter.

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

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

Handle Channel Error

- (void)channelErrorNotification:(NSNotification *)notification
{
    NSInteger errorCode = [notification[GDPushChannelErrorKey] integerValue];
    NSLog(@"GDPushChannelErrorNotification: %zd", error);
    myApp.pushIsOpen = NO;
    myApp.pushErr = error;
    [myApp discardPushToken];
}

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 function.

The discardPushToken function 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

- (void)channelErrorNotification:(NSNotification *)notification
{
    NSInteger errorCode = [notification[GDPushChannelErrorKey] integerValue];
    NSLog(@"GDPushChannelPingFailedNotification %zd", error);
    if ( error == 605 ) {
        [myApp resendPushToken];
    }
}

The above snippet shows a simple Ping Failure handler.

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

The resendPushToken function, 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 function should expect that the server is not immediately available, perhaps employing a retry policy.

Instance Methods
(instancetype)	- initWithIdentifier:
	Constructor that prepares a new Push Channel. More...
(void)	- connect
	Connect Push Channel. More...
(void)	- disconnect
	Disconnect Push Channel. More...

Properties
GDPushChannelState	state
	Push Channel state. More...

Method Documentation

initWithIdentifier:

- (instancetype) initWithIdentifier:

(NSString *)

pushChannelIdentifier

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

Parameters

pushChannelIdentifier

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

connect

- (void) connect

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

This function 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 NSNotification with a user information dictionary, userInfo, will be posted to notify the application of the result. If the attempt succeeds, the notification name will be GDPushChannelOpenedNotification, and the userInfo will contain a GDPushChannelTokenKey entry of NSString type with the token as its value and if applicable a GDPushChannelHostKey entry of NSString type with push service host name. If the attempt fails, the notification name will be GDPushChannelErrorNotification, and the userInfo will contain a GDPushChannelErrorKey entry holding an NSInteger value.

disconnect

- (void) disconnect

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

This function 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 NSNotification is posted to notify the application. The notification name will be GDPushChannelClosedNotification.

Note. This function 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.

Property Documentation

state

- (GDPushChannelState) state

readnonatomicassign

The BlackBerry Dynamics runtime sets this property to one of the GDPushChannelState values to represent the state of the channel.

This property is compatible with key-value observing (KVO).

---

The documentation for this class was generated from the following file:

• GDPush.h