Hello!

I have created an EARLY version of a client spec for push. As discussed earlier focus is offering convenience methods for the registration process. (and unregister on some platforms).

The SEND (from client -->  Unified Push Server --> other clients) is out of scope. The Unified Push is more nofification/signaling, and not chat :) 

URL: https://gist.github.com/matzew/4fcf677eb217737265a8

AeroGear Unified Push Client Spec / SDK (DRAFT 0.0.1)

This document describes the functionality of a client SDK that works with the AeroGear Unified Push Server.

Motivation / Purpose

The AeroGear Unified Push Server offers a rich set of functionality, accessible via HTTP. Instead of having to manually/directly work with the HTTP interface a convenience client library should be offered.

Goal: A client library that is easy to use for device (Mobile Variant Instance) registration and (later) sending Push Notification Messages.

Background: Push Network Token

In order to be able to receive native push messages from a Push Network (e.g. APNs, GCM or SimplePush), the mobile application developer needs to receive a device token (or registration ID), from a device, that is running his application. The way how the different platforms do this is very different and not part of this document.

TL;DR: The token is negotiated between the device and the actual Push Network (GCM/APNs/SimplePush) and afterwards passed to a platform specific callback, where the application of the AeroGear developer has access to it. The developer can now upload it to the AeroGear Unified Push Server, to indicate there is a newMobile Variant Instance for a Push Application Variant.

Basically, the token identifies the device, running our mobile application, with a Push Network. Hence the token is required when the AeroGear Unified Push Server is willing to submit Push Notification Messages against the supportedPush Networks: For sending out Push Notification Messages, the different Push Networks (e.g. GCM, APNs or SimplePush) need to receive a small message payload, combined with a list of tokens, to indicate those devices that should receive the message.

When a server-side application wants to send a Push Notification Message it needs to submit a small message payload, combined with a list of tokens, to indicate those devices that should receive the message.

More details about the server-side part of this can be found in the AeroGear Unified Push Server spec.

Functionality

WARNING: The focus of this specification is to describe the abstract minimum, not any specific requirements for one of the supported client platforms

The client SDK convenience methods to simplify the following tasks

• Initial Registration of a Mobile Variant Instance
• Updating a registered Mobile Variant Instance
  • update the token (could be changed, by the Push Network)
  • store/update other data (e.g. alias, OS version)
• Unregistration of a Mobile Variant Instance

Registration of client device information

Method that helps to initially register the client device information with the AeroGear Unified Push Server. Required Data is defined in the server side spec.

The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.

Update of client device information

Method that helps to update the client device information. One reason could be a changed device token or a newalias of the application user.

Note: It's recommended by most Push Network, to ALWAYs update the information, since a token (that identifies the device with the push network may change). Also, all platforms invoke the hook (see above) where the device tokenfrom the Push Network, is passed to a platform specific callback, always on application launch.

The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.

Unregistration of client device information

Optional method that helps to unregister the client device information with the AeroGear Unified Push Server. Note: The method is optional, since not all supported Push Networks recommend having a client application performing an _unregister. Apple for instance has a Feedback Service, which the AeroGear Unified Push Server needs to freequently query for inactive tokens. Tokens, with Apple, are inactive when the user:

• Disables Push (Settings)
• Deinstalls the app

On platforms a unregistration may be valid, hence this method is option.

The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.

Sending

At some point, a client may trigger a push notification, however not now: Focus is to notify clients. It's not the goal to provide a "chat client".

Auth/Security

To be discussed.....

Platform specific details

Every client platform has it's own base APIs, to receive Push Message from it's Push Network. The AeroGear client SDK may offer utilities to even more simplify this. Example: In Android a custom Intent is required, therefore it may make sense if the AeroGear Android Push Client Library offers a convenience implementation for this class.

--
Matthias Wessendorf

blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf