[aerogear-dev] Client Spec - Unified Push

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<https://gist.github.com/matzew/b918eb45d3f17de09b8f> . <https://gist.github.com/matzew/4fcf677eb217737265a8#motivation--purpose&g... / Purpose The AeroGear Unified Push Server<https://gist.github.com/matzew/b918eb45d3f17de09b8f> 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*. <https://gist.github.com/matzew/4fcf677eb217737265a8#background-push-netwo...: 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 * supported*Push 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<https://gist.github.com/matzew/b918eb45d3f17de09b8f> . <https://gist.github.com/matzew/4fcf677eb217737265a8#functionality> 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 <https://gist.github.com/matzew/4fcf677eb217737265a8#registration-of-clien... of client device information Method that helps to initially register the client device information with the AeroGear Unified Push Server<https://gist.github.com/matzew/b918eb45d3f17de09b8f>;. 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. <https://gist.github.com/matzew/4fcf677eb217737265a8#update-of-client-devi... 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. <https://gist.github.com/matzew/4fcf677eb217737265a8#unregistration-of-cli... of client device information Optional method that helps to unregister the client device information with the AeroGear Unified Push Server<https://gist.github.com/matzew/b918eb45d3f17de09b8f> . *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. <https://gist.github.com/matzew/4fcf677eb217737265a8#sending>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". <https://gist.github.com/matzew/4fcf677eb217737265a8#authsecurity> Auth/Security To be discussed..... <https://gist.github.com/matzew/4fcf677eb217737265a8#platform-specific-det... 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