blackberry.com
BlackBerry Dynamics
Runtime library for iOS applications
from the application developer portal
Public Member Functions | Properties

GDPushChannel Class Reference

Manage Push Channel tokens and notifications. More...

#import <GDPush.h>

List of all members.

Public Member Functions

Properties


Detailed 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:

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.

(The above is also shown in the 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:

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 the 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:

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);
     myApp.pushIsOpen = YES;
     myApp.pushToken = token;
     [myApp sendPushToken];
 }

The above snippet shows the following taking place:

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 processPush function, which would be written by the application developer, could initiate any of the following actions:

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 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:

Handle Ping Failure

See under Ping Failure in the GDPushChannel class reference for an explanation of the Ping Failure feature.

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


Member Function Documentation

- (instancetype) initWithIdentifier: (NSString *)  pushChannelIdentifier

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

Parameters:
pushChannelIdentifierNSString containing the identifier for this Push Channel, see under Push Channel Identifiers, above.
- (instancetype) init
Deprecated:
This function is deprecated and will be removed in a future release. Use GDPushChannel::initWithIdentifier: instead.

Call this function to construct a new Push Channel object. This function doesn't initiate data communication. See 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. If the attempt fails, the notification name will be GDPushChannelErrorNotification, and the userInfo will contain a GDPushChannelErrorKey entry holding an NSInteger value.

- (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

- (id<GDPushChannelDelegate>) delegate [read, write, assign]
Deprecated:
This property is deprecated and will be removed in a future release. Use the NSNotification mechanism to receive notifications instead. See under Notifications in the Programming Interface, above.

The Push Channel object works asynchronously. When its state changes, or a Push Channel notification is received, an event is generated by the BlackBerry Dynamics Runtime, and passed to a callback function in the application code.

Set this property to an instance of a class that contains the code for the required callback functions, i.e. a class that implements the GDPushChannelDelegate protocol.

- (GDPushChannelState) state [read, assign]

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: