BlackBerry Spark Communications Services Guide

Push Notifications

The BlackBerry Infrastructure supports push notifications to mobile clients. When new chat messages and incoming calls are pending delivery to the clients, the BlackBerry Infrastructure can send a push notification with one of the following mechanisms.

Direct Push

The BlackBerry Infrastructure initiates a push request directly to Apple's Push or Google's GCM/FCM servers.

Direct Push

Android

On Android, you must configure your application to receive direct pushes as described in Google's documentation on how to set up a Firebase Cloud Messaging client application on Android.

You must provide BlackBerry with your application's FCM (or GCM) server keys to allow the BlackBerry Infrastructure to initiate push requests for your application. You obtain this key when you set up your application for FCM. You provide these keys to BlackBerry using the BlackBerry Online Account page for your application, under the Communications Services tab's Push Notifications section.

Configure Direct Push for Android

Your application must request a push "token" from FCM at runtime and provide it to the SDK with the BBMEnterprise.setPushToken() method. This token is what uniquely identifies your endpoint to the push infrastructure. For example:

FirebaseInstanceId.getInstance().getInstanceId()
    .addOnCompleteListener(new OnCompleteListener() {
        @Override
        public void onComplete(@NonNull Task task) {
            if (!task.isSuccessful()) {
                Log.w(TAG, "getInstanceId failed", task.getException());
                return;
            }

            // Get new Instance ID token
            String token = task.getResult().getToken();
            BBMEnterprise.getInstance().setPushToken(token);
        }
      });

There are no special application signing requirements for Android direct push.

iOS

For iOS, you must provide BlackBerry with your Production APNS and VoIP Services certificates from Apple to allow the BlackBerry Infrastructure to initiate Apple APNS and VOIP push requests for your application. You provide these keys to BlackBerry using the BlackBerry Online Account page for your application, under the Communications Services tab's Push Notifications section.

For iOS 13, it is strongly recommended that you provide an Apple APNS certificate and you register for an Apple APNS token.

If APNS is enabled, it will be used to push all message-related content and VoIP push will be used only to notify the device of incoming VoIP calls. The RichChat for iOS example application shows how this is achieved.

Configure Direct Push on iOS

When you are testing your iOS application in the sandbox, you can test direct Apple push notifications if your application is signed with a development certificate.

When you release your iOS application for production or you distribute the application with TestFlight, you must configure the SDK to use a production domain and sign your application with a distribution certificate from Apple to enable direct push notifications.

Examples

The SDK RichChat example application supports direct push on Android and iOS.

Proxied Push

Your infrastructure can initiate push requests to Apple or Google servers.

If your infrastructure will be initiating the push requests to Apple's Push or Google's GCM/FCM servers, then you will have to implement a simple REST API for the BlackBerry Infrastructure to invoke when push delivery to one of your users is required, using the user identity token supplied by your Userinfo Endpoint. In this mechanism, you do not need to share your push credentials with BlackBerry.

Proxied Push

Configuring Push Proxy

In order for the BlackBerry Infrastructure to use your push proxy there are a few configuration items that need to be set. Using the BlackBerry Online Account page for your application, under the Communications Services tab's Push Notifications section, for either Apple or Google you will want the Connection Method to be set to PROXY which will add a new PROXY tab.

Proxy Push Tab

Field Description
Endpoint URL The URL of your Push Proxy.
Domain Reserved for future use and should be left empty.
Certificate (PEM) The client certificate that the BlackBerry Infrastructure must use when establishing a mutually authenticated TLS connection. This must be PEM-encoded as per RFC 7468 Section 5.
Private Key (PEM) The private key for the client certificate. This must be a PEM-encoded PKCS #8 private key.
Private Key Password The password for the private key, if any. If the private key does not require a password, leave this empty.
CA Certificate (PEM)

A list of certificates that the BlackBerry Infrastructure will trust when verifying the Push Proxy's TLS certificate. You can specify multiple certificates by providing more than one PEM-encoded object in this field.

A trusted certificate can be self-signed.

Push Request

The BlackBerry Infrastructure will issue an HTTP POST request to the Endpoint URL. This request will include the following HTTP headers.

Request Entity

Each push request will carry a JSON object that conforms to the following specification. Notifications do not carry any information about the content or sender of messages or calls destined for your application. The JSON object provides your Push Proxy with enough information to deliver the notification to your client application. When your application receives the notification, it must then give the opaque body value to the SDK. The SDK processes that value and then informs your application of any new content or events.

Name Type Required Description
version string Yes Version of number of this API. Currently 0.2.
expiry number Yes The notification's time-to-live value, in seconds. Your Push Proxy should not attempt to deliver the notification if more than this many seconds have passed since the notification was received from BlackBerry Infrastructure.
userId string Yes

The user ID of the identity that should receive the notification. This is your application's user ID for the identity, not an SDK regId.

An identity can have multiple endpoints, and your Push Proxy should delivery the notification to each of endpoint that is indicated in the endpointData array.

isStatus boolean No Specify if the push is for a status message. Default is false.
body string Yes The body field value in each notification should be forwarded to your client application and then given to the SDK as is, without modification.
endpointData array Yes

Array of endpoint objects that describe all endpoints for the userId that the push notification is to be sent to.

The endpoint JSON object is defined in table below.

The endpoint JSON object conforms to the following specification.

Name Type Required Description
endpointId string Yes The ID of a single endpoint associated with the user.
platform string No

The platform of this endpoint. Usually, your Push Proxy uses different mechanisms to deliver push notifications to each platform. For example, FCM for android or APNS for ios.

Possible values are: android, ios, web or node.

tokenType string No

When present, this push notification carries a token or push cookie. For example, fcm for Android and apns or apnsVoip for iOS. If your Web SDK application provided the SDK with a pushCookie value, the tokenType will be cookie.

If this is present, then the token field is also present.

Possible values are: fcm, apns, apnsVoip, or cookie.

token string No

If your application provided the SDK with the endpoint's push token that was obtained from the push service provider, this is a copy of that token. The maximum length of the token is 4096 bytes.

If your application provided the SDK with a pushCookie value, this is a copy of that value base64 encoded as per RFC 4648 Section 4.

pushType string No

Some push service providers have different types of notifications. For such providers, such as Apple, this field will always be present. For other providers, this field can be ignored.

The value im indicates that a normal push notification is required. This does not imply that the tokenType is apns and it does not imply that a token is provided.

The value voip indicates that a VoIP type of push notification is required.

Possible values are: im or voip.

Request Response

When your Push Proxy receives a push request, it must respond with one of the following HTTP status codes. Other responses will be treated as temporary failures.

HTTP Response Code HTTP Response Name Description
200 OK The request was accepted by your Push Proxy. Your Push Proxy has token responsibility for delivering it to the specified endpoints.
400 OK Your Push Proxy couldn't understand the request. The BlackBerry Infrastructure should not resend it.
403 OK The user ID does not correspond to a known user in your application. The BlackBerry Infrastructure should stop sending push requests for this user ID until a new endpoint for that identity is registered.
404 OK

The Push Proxy is not operational at this URL. The BlackBerry Infrastructure should not resend the request.

This will not stop the BlackBerry Infrastructure from sending future pushes to the same or a different identity.

500 OK Your Push Proxy encountered an error while processing the request. The BlackBerry Infrastructure can retry the request.
503 OK Your Push Proxy is currently unable or unwilling to process the request. The BlackBerry Infrastructure can retry the request. TheRetry-After header indicates when a retry might work.