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@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/...),
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=(a)/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(a)company.com
(mailto:user@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(a)foo.com
(mailto:user@foo.com)", "bar(a)moz.org (mailto:bar@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(a)lists.jboss.org (mailto:aerogear-dev@lists.jboss.org)
https://lists.jboss.org/mailman/listinfo/aerogear-dev