[aerogear-dev] SPEC: AeroGear Unified Push Server

Mon May 6 03:33:15 EDT 2013

Moved the current draft to the homepage, see
https://github.com/aerogear/aerogear.org/pull/57

-M

On Tue, Apr 30, 2013 at 1:57 PM, Bruno Oliveira <bruno at abstractj.org> wrote:

> Really helpful Matthias. Thanks!
>
>
> --
> "The measure of a man is what he does with power" - Plato
> -
> @abstractj
> -
> Volenti Nihil Difficile
>
>
>
> On Tuesday, April 30, 2013 at 8:54 AM, Matthias Wessendorf wrote:
>
> > On IRC, Bruno raised a valid concern: The earlier version had "use cases"
> >
> >
> > I updated the GIST (https://gist.github.com/matzew/b918eb45d3f17de09b8f)
> and added:
> > * more definitions
> > * usage scenarios
> > * use cases
> >
> >
> > -Matthias
> >
> >
> >
> >
> >
> >
> >
> > On Mon, Apr 29, 2013 at 3:27 PM, Matthias Wessendorf <matzew at apache.org(mailto:
> matzew at apache.org)> wrote:
> > > Hi,
> > >
> > > I started a GIST to convert the different gists and readme's into a
> server-side spec
> > > (https://gist.github.com/matzew/b918eb45d3f17de09b8f)
> > >
> > >
> > > * Regarding the "mobile variant instance":
> > > We need to decide, what a SimplePush client may need on-top of the
> data, described below (and in the gist). (since they have clientIDs +
> channels)
> > >
> > > * Similar... we need to reflect the "" on a "selected" (and broadcast)
> send as well.
> > >
> > > * Sec: there is a different meeting, on the sec - content will be
> integrated (or linked from this spec)
> > >
> > >
> > > If this doc, looks good, I will submit it as a PR so that we get it on
> the homepage
> > >
> > >
> > > Next:
> > > CLIENT SPEC is coming later today (or tomorrow)
> > >
> > > Thoughts ?
> > > Matthias
> > >
> > >
> > >
> > >
> > >
> > > AeroGear Unified Push Server (Draft 0.0.3)
> > >
> > > The AeroGear Unified Push Server is a server that allows sending
> native push messages to different mobile operation systems. The initial
> version of the server supports Apple's APNs (
> http://developer.apple.com/library/mac/#documentation/NetworkingInternet/Conceptual/RemoteNotificationsPG/Chapters/ApplePushService.html%23//apple_ref/doc/uid/TP40008194-CH100-SW9),
> Google Cloud Messaging (http://developer.android.com/google/gcm/index.html)
> and Mozilla's Simple Push (https://wiki.mozilla.org/WebAPI/SimplePush).
> > >
> > > Motivation / Purpose
> > >
> > > Goal: Any (JBoss/AeroGear powered) mobile application, that is backed
> by JBoss technology (e.g. admin console, Errai, drools, etc.), is able to
> easily work with mobile push messages. For a JBoss "backend application" it
> should be as simple as possible, to send messages to its different mobile
> clients.
> > >
> > > Definitions
> > >
> > > Before we get into details, it's important that we have a good lexicon.
> > >
> > > Push Application
> > >
> > > A logical construct that represents an overall mobile application
> (e.g. Mobile HR).
> > >
> > > Mobile Variant
> > >
> > > A mobile variant of the Push Application. There can be multiple
> variants for a Push Application (e.g. HR Android,HR iPad, HR iPhone free,
> HR iPhone premium or HR Mobile Web).
> > >
> > > Mobile Variant Instance
> > >
> > > Represents an actual installation on a mobile device (e.g. User1
> connected via MobileWeb or User2 runs HR iPhone premium on his phone)
> > >
> > > Overview
> > >
> > > The AeroGear Unified Push Server contains three different components:
> > >
> > > Registration: Registry for Push Applications, Mobile Variants and
> Mobile Variant Instances
> > > Storage: A database, storing the registered applications and instances
> > > Sender: Receives messages and sends them to different Mobile Variant
> Instances
> > >
> > >
> > > The graphic below gives a little overview:
> > >
> > > Functionality
> > > Registration
> > >
> > > Three different registration types are provided by the AeroGear
> Unified Push Server.
> > >
> > > Push Application Registration
> > >
> > > Adds a logical construct, that represents an overall mobile
> application (e.g. Mobile HR). The Push Application contains the following
> properties:
> > >
> > > Name
> > > Description
> > > A collection of Mobile Variants
> > >
> > >
> > > The server offers an HTTP interfaces to apply a Push Application
> registration:
> > >
> > > curl -v -H "Accept: application/json" -H "Content-type:
> application/json" -X POST -d '{"name" : "MyApp", "description" : "awesome
> app" }' http://SERVER/applications
> > >
> > > The response returns an ID for the Push Application.
> > >
> > > Mobile Variant Registration
> > >
> > > Adds a mobile variant for an existing Push Application. There can be
> multiple variants for a Push Application (e.g. HR Android, HR iPad, HR
> iPhone free, HR iPhone premium or HR Mobile Web).
> > >
> > >
> > > The server supports the following variant types:
> > >
> > > iOS
> > > Android
> > > SimplePush
> > >
> > > iOS Variant
> > >
> > > An iOS variant represents a logical construct for one iOS application
> (e.g. HR for iPhone or HR for iPad ). The iOS variant requires some APNs
> specific values:
> > >
> > > APNs Push Certificate file
> > > Passphrase
> > >
> > >
> > > The server offers an HTTP interfaces to register an iOS varian:
> > >
> > > curl -i -H "Accept: application/json" -H "Content-type:
> multipart/form-data" -F "certificate=@/Users/matzew/Desktop/MyCert.p12" -F
> "passphrase=TopSecret" -X POST http://SERVER/applications/{PUSH_ID}/iOS (
> http://SERVER/applications/%7BPUSH_ID%7D/iOS)
> > >
> > > NOTE: The above is a multipart/form-data, since it is required to
> upload the "Apple Push certificate"!
> > >
> > >
> > > The response returns an ID for the iOS variant.
> > >
> > > Android Variant
> > >
> > > An Android variant represents a logical construct for one Android
> application (e.g. HR for Android). The Android variant requires some Google
> specific values:
> > >
> > > Google API Key
> > >
> > >
> > > The server offers an HTTP interfaces to register an Android variant:
> > >
> > > curl -v -H "Accept: application/json" -H "Content-type:
> application/json" -X POST -d '{"googleKey" : "IDDASDASDSA"}'
> http://SERVER/applications/{PUSH_ID}/android (
> http://SERVER/applications/%7BPUSH_ID%7D/android)
> > >
> > > _The response returns an ID for the Android variant.
> > >
> > > SimplePush Variant
> > >
> > > An SimplePush variant represents a logical construct for one
> SimplePush application (e.g. HR mobile Web). The SimplePush variant
> requires some Simple Push Network specific values:
> > >
> > > URL of the PushNetwork server
> > >
> > >
> > > The server offers an HTTP interfaces to register an SimplePush variant:
> > >
> > > curl -v -H "Accept: application/json" -H "Content-type:
> application/json" -X POST -d '{"pushNetworkURL" : "
> http://localhost:7777/endpoint/"}'
> http://SERVER/applications/{PUSH_ID}/simplePush (
> http://SERVER/applications/%7BPUSH_ID%7D/simplePush)
> > >
> > > The response returns an ID for the SimplePush variant.
> > >
> > > Mobile Variant Instance Registration
> > >
> > > Adds an mobile variant instance to an existing mobile variant (e.g.
> User1 runs HR-iPad on his device). It is possible that one user can have
> multiple devices. A mobile variant instance contains the following
> properties:
> > >
> > > Required Data
> > > deviceToken
> > >
> > >
> > > The platform specific device token, that identifies the device with
> the used push network, in order to deliver messages
> > >
> > > operatingSystem
> > >
> > >
> > > It is required for the device to submit it's exact name of the
> underlying OS.
> > >
> > > osVersion
> > >
> > >
> > > It is required for the device to submit it's exact version of the
> underlying OS.
> > >
> > > Mobile Variation ID
> > >
> > >
> > > ID received when registering a Mobile Variant. This ID needs to be
> submitted as a request header (ag-mobile-variant). NOTE: It is possible
> that this ID goes away, in favor for a digital signature in a future release
> > >
> > > Optional Data
> > > deviceType
> > >
> > >
> > > It is recommended to store the (exact) device type (e.g. phone vs
> tablet).
> > >
> > > alias
> > >
> > >
> > > If the business application requires the conecpt of a user, the
> registration must submit an unique identifier (like a username), to
> identify the user. It is possible that one user has multiple devices.
> > >
> > > Business Data
> > >
> > > The above are technical information bits that are required to get a
> message to the device. This the app wants to send notification based on a
> criteria, the relevant data has to be stored in the business backend. This
> way the backend app is very flexible on the criterias (e.g. max salary,
> geolocation, number of children, etc). All this data is NOT directly
> related to the technical functionality of sending data. The usage of the
> AeroGear Pipe is highly recommended to store business data on the business
> backend.
> > >
> > >
> > > The server offers an HTTP interfaces to register an mobile variant
> instance:
> > >
> > > curl -v -H "Accept: application/json" -H "Content-type:
> application/json" -H "ag-push-app: {id}" -H "ag-mobile-app: {id}" -X POST
> -d '{ "alias" : "user at company.com (mailto:user at company.com)",
> "deviceToken" : "someTokenString", "deviceType" : "ANDROID",
> "mobileOperatingSystem" : "android", "osVersion" : "4.0.1" }'
> http://SERVER/registry/device
> > >
> > > NOTE: Platform specific Client SDKs will be provided to submit the
> require data to the AeroGear Unified Push Server.
> > >
> > > Storage
> > >
> > > A (configurable) database that stores all registered applications and
> instances.
> > >
> > > Sender
> > >
> > > HTTP interface that receives messages for a delivery to different
> Mobile Push Networks. A few different Sender Types are supported by the
> push server.
> > >
> > > Global Broadcast Sender
> > >
> > > Sends a push message to all mobile variants (and all of its mobile
> variant intances), of a given Push Application:
> > >
> > > curl -v -H "Accept: application/json" -H "Content-type:
> application/json" -X POST -d '{"key":"blah", "alert":"HELLO!"}'
> http://SERVER/sender/broadcast/{PushApplicationID} (
> http://SERVER/sender/broadcast/%7BPushApplicationID%7D)
> > >
> > > Sends a JSON map to the server. If platform specific key words (e.g.
> alert for APNs) are used, they are honored for the specific platform. This
> transformation is done by the AeroGear Unified Push Server.
> > >
> > > Variant specific Broadcast
> > >
> > > Sends a push message to only one mobile variants (and all of its
> mobile variant intances).:
> > >
> > > curl -v -H "Accept: application/json" -H "Content-type:
> application/json" -X POST -d '{"key":"blah", "alert":"HELLO!"}'
> http://SERVER/sender/broadcast/variant/{MobileVariantID} (
> http://SERVER/sender/broadcast/variant/%7BMobileVariantID%7D)
> > >
> > > Sends a JSON map to the server. If platform specific key words (e.g.
> alert for APNs) are used, they are honored for the specific platform. This
> transformation is done by the AeroGear Unified Push Server.
> > >
> > > Selected Sender
> > >
> > > Sends a push message to a selected list of identified users
> (regardless of their variant):
> > >
> > > curl -v -H "Accept: application/json" -H "Content-type:
> application/json" -X POST -d '{ alias: ["user at foo.com (mailto:user at foo.com)",
> "bar at moz.org (mailto:bar at moz.org)", ....], message: {"key":"blah",
> "alert":"HELLO!"} }' http://SERVER/sender/selected
> > >
> > > The alias value is used to identied the desired users. The payload
> (messages) is a standard JSON map. If platform specific key words (e.g.
> alert for APNs) are used, they are honored for the specific platform. This
> transformation is done by the AeroGear Unified Push Server.
> >
> >
> >
> >
> >
> > --
> > Matthias Wessendorf
> >
> > blog: http://matthiaswessendorf.wordpress.com/
> > sessions: http://www.slideshare.net/mwessendorf
> > twitter: http://twitter.com/mwessendorf
> > _______________________________________________
> > aerogear-dev mailing list
> > aerogear-dev at lists.jboss.org (mailto:aerogear-dev at lists.jboss.org)
> > https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
>
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>

-- 
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/7e2c358f/attachment-0001.html 