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

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