[aerogear-dev] AeroGear UnifiedPush Registration Client Spec (DRAFT 0.0.3)

[Matthias Wessendorf]

See https://github.com/aerogear/aerogear.org/pull/86


On Fri, Jun 7, 2013 at 10:01 PM, Matthias Wessendorf <matzew at apache.org>wrote:

> Hello,
>
> following up on the previous drafts...
>
> This document describes the functionality of a client SDK that works with
> the AeroGear UnifiedPush Server<http://aerogear.org/docs/specs/aerogear-server-push/>
> .
>  <https://gist.github.com/matzew/569190db18694afe22f6#motivation--purpose>Motivation
> / Purpose
>
> The AeroGear UnifiedPush Server<http://aerogear.org/docs/specs/aerogear-server-push/> is
> accessible via HTTP. Instead of having to manually register a device (
> MobileVariantInstance) with the HTTP interface, a client library should
> be offered.
>
> *Goal:* A client library to register a mobile application (
> MobileVariantInstance) with the UnifiedPush Server.
> <https://gist.github.com/matzew/569190db18694afe22f6#background-push-network-token>Background:
> Push Network Token
>
> To receive native push notifications from a Push Network (e.g. APNs, GCM
> or SimplePush), the mobile device is identified with a unique device-token,
> assigned by the actual Push Network. Thisdevice-token is passed, by the
> underlying Operating-System, to the mobile application. Details are
> different on each platform and *not* part of this document.
>
> The device-token needs to be registered with the *AeroGear UnifiedPush
> Server*, to indicate there is a new MobileVariantInstance for a
> MobileVariant. More details about the server-side part of this can be
> found in the *AeroGear Unified Push Server* spec<http://aerogear.org/docs/specs/aerogear-server-push/>
> .
>  <https://gist.github.com/matzew/569190db18694afe22f6#functionality>
> Functionality
>
> *WARNING:* *The focus of this specification is to describe the generic
> minimum and not any platform-specific requirements*
>
> The client SDK offers the following features:
>
>    - Registration and Updating of a MobileVariantInstance
>    - Unregistration of a Mobile Variant Instance (optional, due to
>    platform specific restrictions)
>
>
> <https://gist.github.com/matzew/569190db18694afe22f6#registration-and-updating-of-a-mobile-variant-instance>Registration
> and Updating of a Mobile Variant Instance
>
> Everytime when a mobile application launches it receives the above
> mentioned device-token, via a*platform-specific* method (or callback).
> Since the Push Network (e.g. APNs or GCM) *may* assign a *new*token to a
> device, it is *recommended* to *always* (re)register the device-token with
> the *AeroGear UnifiedPush Server*.
>
> Besides the device-token the *AeroGear UnifiedPush Server* is able to
> store some of the below device- or user-specific metadata:
>
>    - *deviceToken:* *Identifies the device/user-agent within its Push
>    Network.*
>    - *deviceType:* *The device type of the device or the user agent.*
>    - *mobileOperatingSystem:* *The name of the underlying Operating
>    System.*
>    - *osVersion:* *The version of the used Operating System.*
>    - *alias:* _ Application specific alias to identify users with the
>    system. For instance an email addressor a username._
>    - *category:* *Used tp apply a "tag". Mainly usful for the SimplePush
>    channel(s).*
>
> Besides the slight chance that the `device-token may change, some of the
> above metadata is more likely to change. Therefore another reason to always
> send this metadata to the *AeroGear UnifiedPush Server*.
>  <https://gist.github.com/matzew/569190db18694afe22f6#reachability>
> Reachability
>
> The client SDK needs to check if the device can establish a connection to
> the internet (PushNetwork and UnifiedPush Server). It should make use of
> the platform-specific APIs to check the reachablility of the services.
> <https://gist.github.com/matzew/569190db18694afe22f6#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<http://aerogear.org/docs/specs/aerogear-server-push/>
> . *Note:* *The method is optional, since not all supported Push Networks
> recommend having a client application actively 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
>
> <https://gist.github.com/matzew/569190db18694afe22f6#reachability-1>
> Reachability
>
> The client SDK needs to check if the device can establish a connection to
> the internet (PushNetwork and UnifiedPush Server). It should make use of
> the platform-specific APIs to check the reachablility of the services.
>  <https://gist.github.com/matzew/569190db18694afe22f6#authsecurity>
> Auth/Security
>
> To be discussed.....
> <https://gist.github.com/matzew/569190db18694afe22f6#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 process. *For example: In Android a custom Intent is
> required, therefore it would make sense if the "AeroGear Android Push
> Client Library" offers a convenience implementation for this class.*
>
> *
> *
>
> BTW... Current, EARLY, implementations:
>
> * JavaScript (to register SimplePush Variant Instance):
>
> https://github.com/aerogear/aerogear-js/blob/Notifier/src/unified-push/aerogear.unifiedpush.js
>
> * iOS (to register iOS Variant Instance):
> https://github.com/matzew/ag-client-push-sdk
>
>
>
> -Matthias
>
>
>
> --
> 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/20130612/010fa49a/attachment-0001.html