[aerogear-dev] SPEC: AeroGear Unified Push Server
Matthias Wessendorf
matzew at apache.org
Tue Apr 30 07:54:38 EDT 2013
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>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>.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#motivation--purpose>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.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#definitions>
> Definitions
>
> Before we get into details, it's important that we have a good lexicon.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#push-application>Push
> Application
>
> A logical construct that represents an overall mobile application (e.g. Mobile
> HR).
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#mobile-variant>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).
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#mobile-variant-instance>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*)
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#overview>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: [image: components]<https://a248.e.akamai.net/camo.github.com/11b903b1eea5c2ba492ee4ec759b205fc363fed6/687474703a2f2f70656f706c652e6170616368652e6f72672f2537456d61747a65772f505553482d5345525645522e706e67>
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#functionality>
> Functionality
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#registration>
> Registration
>
> Three different registration types are provided by the *AeroGear Unified
> Push Server*.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#push-application-registration>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.*
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#mobile-variant-registration>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
>
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#ios-variant>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
>
> *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.*
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#android-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
>
> _The response returns an ID for the Android variant.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#simplepush-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
>
> *The response returns an ID for the SimplePush variant.*
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#mobile-variant-instance-registration>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:
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#required-data>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
> *
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#optional-data>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.*
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#business-data>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",
> "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*.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#storage>Storage
>
> A (configurable) database that stores all registered applications and
> instances.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#sender>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.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#global-broadcast-sender>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}
>
> 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*.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#variant-specific-broadcast>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}
>
> 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*.
> <https://gist.github.com/matzew/b918eb45d3f17de09b8f#selected-sender>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", "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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20130430/672444f1/attachment-0001.html
More information about the aerogear-dev
mailing list