[aerogear-dev] SPEC: AeroGear Unified Push Server

Wed May 8 00:54:02 EDT 2013

On Wed, May 8, 2013 at 5:24 AM, Deepali Khushraj <dkhushra at redhat.com>wrote:

> 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.
>

yeah, removing(or perhaps disabling) mobile variants, or even the lager
"push application" concept would be possible.
I think I mentioned the "instances" to make clear I can easily remove a
guy, which has been fired (but he didn't return the company phone).

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

Otherwise everyone could register new apps :)

> 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.
>

I feel that we should protect our "sending http endpoint". That does
not necessarily mean a user:password combination.

The "Send" is triggered by a server-side component (e.g. some backend app,
written in some language/framework).
We should make sure that only "valid" server-side components can send
messages to a PushApplication/MobileVariant(s).

Not covered in the spec (but the UI Mockups indicate it already)
When these PushApplication/MobileVariant(s) are registered we will have a
button to generate "access keys".

curl -v -H "Accept: application/json" -H "Content-type: application/json"
-H "ag-pa-access-key:
329804327981237984317927098247980432179843217813267834687213842"
-X POST
   -d '{message: {"key":"blah",
"alert":"HELLO!"}}'http://SERVER/sender/broadcast/PushApplicationID

Not sure if that is really enough, but here the "server side comp." needs
to know the ID of the logical "Push Application" constract, plus it
"push-app-access-key";

So... if someone knows these two, he could start spamming the users, hence
I feel that on-top of these keys we may want to have the
server-side-component somehow perform some sort of auth against our
HTTP-SEND endpoint

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

Thanks!

>
> D.
>
>
> On May 6, 2013, at 3:33 AM, Matthias Wessendorf <matzew at apache.org> 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 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 <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>(
>> http://SERVER/applications/%7BPUSH_ID%7D/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>(
>> http://SERVER/applications/%7BPUSH_ID%7D/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>(
>> http://SERVER/applications/%7BPUSH_ID%7D/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 <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>(
>> http://SERVER/sender/broadcast/%7BPushApplicationID%7D<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>(
>> http://SERVER/sender/broadcast/variant/%7BMobileVariantID%7D<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<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
> _______________________________________________
> aerogear-dev mailing list
> 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/20130508/4ed03a5f/attachment-0001.html 