Manage Push Channel tokens and notifications. More...
#import <GDPush.h>
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:
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.
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 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 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.
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.
To notify the application, the runtime posts an NSNotification.
For all NSNotification instances that are Push Channel notifications:
userInfo, depends on the event type. The following values are used as keys.
Push Channel state changes can also be detected by key-value observing (KVO) of the state property.
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 |
|---|---|---|
| Prepared | Application can call connect: state becomes Connecting | None |
| Connecting | BlackBerry Dynamics runtime requests a new channel from the proxy infrastructure |
|
| Open | Application can call disconnect: state becomes Disconnecting |
|
| Disconnecting | BlackBerry Dynamics Runtime requests the proxy infrastructure to close the channel |
|
| 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.
The following code snippets illustrate some common tasks.
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] init]; 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).
[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).
The following code snippets illustrate some common tasks.
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:
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.
- (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:
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:
-(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:
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.
- (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:
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.
| - (instancetype) init |
Call this function to construct a new Push Channel object. This function does not 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.
- (id<GDPushChannelDelegate>) delegate [read, write, assign] |
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 GDPushChannelState values depends on state of push channel
This property is compatible with key-value observing (KVO).