Creating a Push Service object

The sample app calls the static PushService.create() function to create a PushService object to perform push-related operations. After the Push Service object is instantiated, the sample app can make calls to the object to receive and process push messages.

Your app needs to call PushService.create() with one appID parameter and one invokeTargetID parameter. If you try to create another PushService object with a different appID or invokeTargetID parameter, the create operation fails with an exception.

The appID parameter corresponds to the application ID that you specified when you configured the sample app. For details about configuring the sample app, see the documentation included with the Push Capture sample app.

The invokeTargetID is a value that you generate. The value identifies the client-side app that's the target of a push message, and that's invoked when a push message arrives. The value must be the same in the config.xml file for your app and in the PushService.create() function. For more information about updating your config.xml file, see Update your config.xml file.

Call PushService.create()

The static PushService.create() function instantiates a PushService object. If the object is created successfully, the create function calls the successCreatePushService() callback function with the PushService object that the app can use. If the object isn't created, the create function calls the failCreatePushService() callback function with a result number value. The result corresponds to one of the error constants provided in the PushService class. For more information about the error constants, see the PushService class in the API Reference.

The call to PushService.create() is different depending on whether or not the Push Service is used with BES10 or BES12. If the Push Service is used without BES10 or BES12, the create function call looks like this:

var ops;
if (sample.pushcapture.usingpublicppg) {
    // Consumer app using public push
    ops = { invokeTargetId : sample.pushcapture.invokeTargetIdPush, 
            appId : sample.pushcapture.appid,
            ppgUrl : sample.pushcapture.ppgurl
    };
} else {
    // Enterprise app using enterprise push
}
    
blackberry.push.PushService.create(ops, 
           sample.pushcapture.successCreatePushService,
           sample.pushcapture.failCreatePushService,
           sample.pushcapture.onSimChange,
           sample.pushcapture.onPushTransportReady);

If the Push Service is used with BES10 or BES12, the create function call looks like this:

var ops;
if (sample.pushcapture.usingpublicppg) {
    // Consumer app using public push
} else {
    // Enterprise app using enterprise push
    if (sample.pushcapture.usesdkaspi) {
        // If you used the Push Service SDK for your Push  
        // Initiator implementation, use the application ID
        // that you specified when you configured that app.
        ops = { invokeTargetId : sample.pushcapture.invokeTargetIdPush, 
                appId : sample.pushcapture.appid
        };
    } else {
        ops = { invokeTargetId : 
            sample.pushcapture.invokeTargetIdPush };
    }
}
       
blackberry.push.PushService.create(ops, 
           sample.pushcapture.successCreatePushService, 
           sample.pushcapture.failCreatePushService, 
           sample.pushcapture.onSimChange,
           sample.pushcapture.onPushTransportReady);

Call successCreatePushService()

The successCreatePushService() callback function stores the PushService object in a global variable. The app can use the global variable to make calls to the other functions of the PushService class without having to call PushService.create() again.

PushCapture.prototype.successCreatePushService = function(service) {          
   // Save the service into a global variable so that it can be  
   // used later for operations such as create channel or destroy 
   // channel.
   sample.pushcapture.pushService = service;
   // ...
};

Call failCreatePushService()

If the PushService object isn't created, the failCreatePushService() callback function shows the error handling and the error messages that you can use for debugging. In your app, you might want to handle the errors differently. For example, you might want to retry an operation first before displaying an error message. The API Reference lists the possible actions that you can take for each error constant. The API Reference also tells you which error codes apply to which function calls.

PushCapture.prototype.failCreatePushService = function(result) { 
   // ...
   if (result == blackberry.push.PushService.INTERNAL_ERROR) {
       alert("Error: An internal error occurred while calling " +
           "blackberry.push.PushService.create. Try restarting the 
           app.");
   } else if (result == blackberry.push.PushService.
                        INVALID_PROVIDER_APPLICATION_ID) {
       // This error applies only to consumer apps that use 
       // a public/BIS PPG
       alert("Error: Called blackberry.push.PushService.create with 
           a missing " + "or invalid appId value. It usually means 
           a programming error.");
   } else if (result == blackberry.push.PushService.
                        MISSING_INVOKE_TARGET_ID) {
       alert("Error: Called blackberry.push.PushService.create with 
           a missing " + "invokeTargetId value. It usually means a 
           programming error.");
   } else if (result ==
       blackberry.push.PushService.SESSION_ALREADY_EXISTS) {      
           alert("Error: Called blackberry.push.PushService.create 
           with an appId or " + "invokeTargetId value that matches 
           another app. It usually means a " + "programming error.");      
   } else {
       alert("Error: Received error code (" + result + ") after " +
           "calling blackberry.push.PushService.create.");
   }
};

Last modified: 2015-06-11



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus