Re: [aerogear-dev] SPEC: AeroGear Unified Push Server

Matthias, A couple of comments: * You mention disable notifications feature for "mobile variant instances". I was wondering if you considered the same for "mobile variants" and "push applications"? Could help admins disable misbehaving apps, and developers manage older app versions.

* API access: during "app registration", developer login seems like a good idea.

I am not so sure about "sending" messages though, as this will likely be initiated by a server-side component with no developer in the loop.

Thanks for the spec! The clear definitions made it very easy to read.

D. On May 6, 2013, at 3:33 AM, Matthias Wessendorf <matzew(a)apache.org&gt; wrote: 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(a)abstractj.org&gt;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(a)apache.org(mailto: > matzew(a)apache.org)&gt; 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/...), > 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 <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 &quot;certificate=(a)/Users/matzew/Desktop/MyCert.p12&quot; -F > "passphrase=TopSecret" -X POST http://SERVER/applications/{PUSH_ID}/iOS<http://server/applications/%7... > http://SERVER/applications/%7BPUSH_ID%7D/iOS<http://server/application... > ) > > > > > > 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/application... > http://SERVER/applications/%7BPUSH_ID%7D/android<http://server/applica... > ) > > > > > > _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/applicat... > http://SERVER/applications/%7BPUSH_ID%7D/simplePush<http://server/appl... > ) > > > > > > 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" : &quot;user(a)company.com (mailto:user@company.com)", > "deviceToken" : "someTokenString", "deviceType" : "ANDROID", > "mobileOperatingSystem" : "android", "osVersion" : "4.0.1" }' > http://SERVER/registry/device <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/sende... > http://SERVER/sender/broadcast/%7BPushApplicationID%7D<http://server/s... > ) > > > > > > 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... > http://SERVER/sender/broadcast/variant/%7BMobileVariantID%7D<http://se... > ) > > > > > > 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: [&quot;user(a)foo.com (mailto: > user(a)foo.com)&quot;, &quot;bar(a)moz.org (mailto:bar@moz.org)", ....], message: > {"key":"blah", "alert":"HELLO!"} }' http://SERVER/sender/selected<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(a)lists.jboss.org (mailto:aerogear-dev@lists.jboss.org) > > https://lists.jboss.org/mailman/listinfo/aerogear-dev > > > > _______________________________________________ > aerogear-dev mailing list > aerogear-dev(a)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 _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev