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

[Deepali Khushraj]

Comments inline.


On Jun 4, 2013, at 11:55 AM, Matthias Wessendorf <matzew at apache.org> wrote:

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

Newsstand push notification maybe worth considering since it's quite similar. 

Here's an excerpt on how it compares to other special keys:

"The notification that initiates the Newsstand background download is the same as any other push notification, with two exceptions. The first difference is the payload — your Newsstand notification should include thecontent-available property (with a value of 1) in the JSON payload. Second, your app may only initiate a background download once every 24 hours. iOS will ignore notifications that try to initiate a background download more than once in a 24 hour period."

http://developer.apple.com/library/ios/#technotes/tn2280/_index.html

D.

> Android special keys
> 
> None! The JSON map is submitted as it is, directly to the device. There are no Android specific keywords.
> 
> 

> 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} 
> Message Format
> 
> Besides the actual payload the API accepts a few classifiers to select a subset of registered devices.
> 
> 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
> 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. NOTE: For SimplePush, the deviceType is ONLY web. No specifics on the actual device are used due to general limitations on "user agent sniffing".
> 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.
> 
> 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
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.jboss.org/pipermail/aerogear-dev/attachments/20130607/c55c88ca/attachment-0001.html