[aerogear-dev] Client Spec - Unified Push

[Matthias Wessendorf]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20130506/9e749d78/attachment.html