[aerogear-dev] Unified Message format (was: Re: AeroGear Push Message Format)

[Matthias Wessendorf]

based on the "unification issues" (see old thread), Dan, Kris and I met


here is what we have come up with:




Draft for the AeroGear Push Message Format

The Unified Push Server allows two different ways to send message to the
native Push API, of the supported devices:

   - broadcast
      - to all MobileVariants and their MobileVariant Instances (devices)
      - to one specific MobileVariant and its MobileVariant Instances
       (devices)
   - selective Send

<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#broadcast>Broadcast

curl -v -H "Accept: application/json" -H "Content-type: application/json"
   -H "ag-push-application: {PushApplicationID}
   -H "ag-mobile-variant: {MobileVariantID}
   -X POST
   -d '{"key":"value", "alert":"HELLO!", "sound":"default", "badge":7,
       "simple-push":"version=123"}'
http://localhost:8080/ag-push/rest/sender/broadcast

If the ag-push-application header is used, a message is send to a
PushApplication and *ALL*MobileVariantInstances will receive the message.

If the ag-mobile-variant header is used, a message is send to a particular
MobileVariant and *ALL* of its MobileVariantInstances will receive the
message.
<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#message-format>Message
Format

The message format is very simple: A generic JSON map is used to send
messages to Android and iOS devices. The applications on the devices will
receive the JSON map and are responsible for performing a lookup to read
values of the given keys.
<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#simplepush-special-keys>SimplePush
special keys

Every AeroGear-SimplePush application can subscribe to a broadcast channel.
If, on the abovebroadcast Endpoint, you are providing the simple-push key,
the version (that's what SimplePush is really about), is extracted and send
to ALL "connected" broadcast channels, of the given SimplePush variant(s). *
NOTE:* On all other platforms, the simple-push key will be simply :-)
ignored. Also, for SimplePush, all *OTHER* keys are ignored (since that
does not make sense for SP).
<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#ios-special-keys>iOS
special keys

If the JSON map contains on of the following reserved keywords, Apple
specific hooks will be invoked on the device:

   - alert (triggers a dialog, displaying the value - no iOS API needs to
   be invoked by the app developer)
   - sound (plays a given sound - no iOS API needs to be invoked by the app
   developer)
   - badge (sets the value of the badge icon - no iOS API needs to be
   invoked by the app developer)

<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#android-special-keys>Android
special keys

None! The JSON map is submitted as it is, directly to the device. There are
no Android specific keywords.
<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#selective-send>Selective
Send

A message is send to a restricted number of MobileVariantInstances, based
on a given criteria. The following example shows the correspondent HTTP
interface:

curl -v -H "Accept: application/json" -H "Content-type: application/json"
   -X POST

   -d '{
      "alias" : ["user at account.com", "jay at redhat.org", ....],

      "deviceType" : ["iPad", "AndroidTablet"],

      "message": {"key":"value", "key2":"other value", "alert":"HELLO!",
        "simple-push": { "SomeCategory":"version=123",
"anotherCategory":"version=456"}
      }
   }'
http://localhost:8080/ag-push/rest/sender/selected/{PushApplicationID}

<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#message-format-1>Message
Format

Besides the actual payload the API accepts a few *classifiers* to select a
subset of registered devices.
<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#query-component>Query
component

Currently the Server will support the following query criterias:

   - alias: A list of email address (or usernames) to send messages to
*ALL* devices
   of the users. Thealias needs to be stored, when the device is
   registering itself with the server. See here for
details<https://github.com/matzew/ag-client-push-sdk/blob/master/push-sdk/AGClientDeviceInformation.h#L48-L52>
   - deviceType: A list of raw devices types that should receive the
   message (e.g. Coupon only for iPad and AndroidTablets). The deviceType needs
   to be stored, when the device is registering itself with the server. See
   here for details<https://github.com/matzew/ag-client-push-sdk/blob/master/push-sdk/AGClientDeviceInformation.h#L43-L46>
   . *NOTE:* For SimplePush, the deviceType is *ONLY* web. No specifics on
   the actual device are used due to general limitations on "user agent
   sniffing".

<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#message-payload>Message
Payload

The message format is very simple: A generic JSON map is used to send
messages to Android and iOS devices. The applications on the devices will
receive the JSON map and are responsible for performing a lookup to read
values of the given keys. Like above, iOS specific keywords are honored.
<https://gist.github.com/matzew/d6f1b88b85e2f6c18031#simplepush>SimplePush

For SimplePush an extra simple-push object is provided. Only for SimplePush
Variants this key is used (similar to the broadcast case). However *HERE* we
use an object, to send (selective) different versions to different channels.










'Thoughts ??





-- 
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/20130604/724d446a/attachment-0001.html