#Cloudpokes

Overview

Cloudpokes is a simple, lightweight push notification library for Java backends of iOS and Android apps. A single SSL connection to APNS is kept alive, making Cloudpokes suitable for apps with medium load. Cloudpokes provides a platform-abstracted push API that makes serving iOS and Android clients from the same backend simple and easy.

Payloads are constructed and notifications routed transparently depending on client type, which is encoded inside a DeviceToken class. This allows a factory to instantiate the correct platform-specific implementation of a Notification. Therefore, the following example will send a greeting to the device identified by token, no matter whether it is an iOS or an Android device:

void sayHello(String name, DeviceToken token) {
    Notification notification = Notification.withToken(token);
    notification.setMessage("Hello " + name + '!')
            .setDefaultSound().send();
}

Configuration

To configure the APNS gateway, you must implement the ApnsGateway.ApnsConfig abstract class with methods getCertFile() and getCertPhrase(). These methods must return an InputStream of your app's PKCS #12 push certificate and its passphrase, respectively, for example:

ApnsConfig apns_config = new ApnsConfig(Env.SANDBOX) {
    @Override
    public InputStream getCertFile() throws IOException {
        return getResourceStream("META-INF/apns-dev.p12");
    }
    @Override
    public String getCertPhrase() {
        return "changeme";
    }
};
ApnsPushSender.configure(apns_config);

The constructor of ApnsConfig takes an environment specifier which can be Env.PRODUCTION or Env.SANDBOX. The same configuration object can be used for setting up the FeedbackClient, which queries the APNS feedback service.

To configure the GCM gateway, implement the getApiKey() method of the GcmPushSender.Delegate interface and return your API key. A good place to configure both gateways is the init method of your HttpServlet.

Custom JSON payloads

Cloudpokes internally uses Ralf Sternberg's highly efficient minimal-json to build platform-conforming JSON payloads. Notification also exposes functionality to extend payload objects with custom members. Use the method setCustom(String key, JsonValue value) to insert such members, which can be atomic, array, or object values. key can be any JSON-key except "aps", which is reserved by iOS. For iOS, custom values are stored as members of the main JSON payload, whereas for Android, those values become members of the "data" object.

Error handling

Currently, only rudimentary support exists in Cloudpokes for detecting whether a specific Notification was rejected by the APNS endpoint. However, a full client for the APNS feedback service is implemented as FeedbackClient, which takes an ApnsConfig object for construction. To receive inactive tokens from APNS, you must implement the FeedbackClient.Listener interface, for example:

FeedbackClient.Listener listener = new FeedbackClient.Listener() {
    @Override
    public void receiveInactiveToken(byte[] token) {
        removeTokenFromUserDB(token);
    }
};
FeedbackClient feedback_client = new FeedbackClient(apns_config);
try {
    feedback_client.fetchInactiveTokens(listener);
}
catch (IOException e) { ... }

In contrast, transmission errors at the GCM endpoint are directly reported to the GcmPushSender.Delegate interface that you must implement. The corresponding methods are didSend and didFail, for example:

@Override
public void didSend(Notification notification, String reg_id) {
    if (reg_id != null) {
        updateToken(notification.getToken().getGcmToken(), reg_id);
    }
}

In the above, reg_id is the canonical registration ID from the GCM endpoint if one was returned or null otherwise. The failure handler could look like this:

@Override
public void didFail(Notification notification, String error) {
    if ("NotRegistered".equals(error)) {
        removeTokenFromUserDB(notification.getToken().getGcmToken());
    }
}

See the Android Developers reference for a list of possible error strings. error is null for failed connections to the GCM endpoint.

How to contribute

• Better support for detecting errors at the APNS endpoint and automatic resending of those notifications that were streamed after the offending one and before APNS hung up.
• This would also allow efficient support for broadcasts.
• Support for Windows Phone via MPNS.
• This library is not yet documented with Javadoc annotations. Javadocs for at least all public would be very useful.