[aerogear-dev] Client Spec - Unified Push

Mon May 6 06:03:55 EDT 2013

Things like the Android Intent can be mentioned here, IMO, but should not
be spec'd out.  IMO it's up the actual platform, to offer convenience
hooks. On Android I see a value in offing classes and XML snippets. But not
(ATM) for SimplePush, nor for iOS (besides "registration", "update" and
"unregister")

-Matthias

On Mon, May 6, 2013 at 11:44 AM, Matthias Wessendorf <matzew at apache.org>wrote:

> 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>Motivation
> / 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-network-token>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 *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-client-device-information>Registration
> 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-device-information>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.
> <https://gist.github.com/matzew/4fcf677eb217737265a8#unregistration-of-client-device-information>Unregistration
> 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-details>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
>

-- 
Matthias Wessendorf

blog: http://matthiaswessendorf.wordpress.com/
sessions: http://www.slideshare.net/mwessendorf
twitter: http://twitter.com/mwessendorf
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20130506/29f966d5/attachment-0001.html 