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

[Matthias Wessendorf]

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