[aerogear-dev] SPEC: AeroGear Unified Push Server

Mon Apr 29 09:27:05 EDT 2013

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#//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*.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20130429/149bc528/attachment-0001.html 