3:01 p.m.
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&g...
/ 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-netwo...:
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-upda...
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-cli...
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-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 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/ae...
* 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