Re: [aerogear-dev] AeroGear Push Message Format

Look good ! +1 to discuss later how to "unify" the message API Regarding the message formats, don't we want to also define what the format of the message responses are ? On Mon, May 27, 2013 at 1:51 PM, Matthias Wessendorf <matzew(a)apache.org&gt;wrote: > This document is devided in two sections: > > - Native Push (Android and iOS) > - SimplePush (web-based Push) > > <https://gist.github.com/matzew/98762c8d3f516e1abd38#native-push>Native > Push > > 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) > - seletive Send > > <https://gist.github.com/matzew/98762c8d3f516e1abd38#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", "key2":"other value", "alert":"HELLO!", "sound":"default", "badge":7}' > 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*MobileVariantIncances will receive the message. > > If the ag-mobile-variant header is used, a message is send to a > particular MobileVariant and *ALL* of its MobileVariantIncances will > receive the message. > <https://gist.github.com/matzew/98762c8d3f516e1abd38#message-format>Mes... > 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/98762c8d3f516e1abd38#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/98762c8d3f516e1abd38#android-special-keys&... > 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/98762c8d3f516e1abd38#selective-send>Sel... > Send > > A message is send to a restricted number of MobileVariantIncances, 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" : [&quot;user(a)account.com&quot;, &quot;jay(a)redhat.org&quot;, ....], > > "deviceType" : ["iPad", "AndroidTablet"], > > "message": {"key":"value", "key2":"other value", "alert":"HELLO!"} > }' > http://localhost:8080/ag-push/rest/sender/selected/{PushApplicationID} > > <https://gist.github.com/matzew/98762c8d3f516e1abd38#message-format-1>M... > Format > > Besides the actual payload the the API accepts a few *classifiers* to > select a subset of registered devices. > <https://gist.github.com/matzew/98762c8d3f516e1abd38#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-... > - 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-... > > <https://gist.github.com/matzew/98762c8d3f516e1abd38#message-payload>Me... > 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/98762c8d3f516e1abd38#simplepush> > SimplePush > > The Unified Push Server allows two different ways to send message to > SimplePush-enabled devices: > > - broadcast > - seletive Send > > <https://gist.github.com/matzew/98762c8d3f516e1abd38#broadcast-1> > Broadcast > > Sends a message to all connected devices of a SimplePush variant. The > message (aka version) will be received on the *broadcast* channel > (AeroGear specific broadcast channel, not part of the official spec). > > curl -v -H "Accept: application/json" -H "Content-type: application/json" > > -X POST > -d '{"version":1234}' > http://localhost:8080/ag-push/rest/sender/simplePush/broadcast/{SimplePus... > > <https://gist.github.com/matzew/98762c8d3f516e1abd38#message-format-2>M... > Format > > The message format is very simple: The version number is send to the > server, as a JSON object. > <https://gist.github.com/matzew/98762c8d3f516e1abd38#selective-send-1>S... > Send > > A message is send to a selected number of channels, connected against a > specific SimplePush variant > > curl -v -H "Accept: application/json" -H "Content-type: application/json" > -X POST > -d '{ > "channelIDs":["someID", "moreID...."], > "version":1909 > }'http://localhost:8080/ag-push/rest/sender/simplePush/selected/{SimplePushVariantID} > > <https://gist.github.com/matzew/98762c8d3f516e1abd38#message-format-3>M... > Format > > The message format is very simple: A JSON object, containing the actual > payload (version) and an array, containing all the different channels. > <https://gist.github.com/matzew/98762c8d3f516e1abd38#discussion> > Discussion > > SimplePush and NativePush do have different APIs / endpoints. However, > that's mainly because the SimplePush is really.... simple.... and not 100% > compliant with the richer APIs for Android/iOS. > > We *could* (later?) try to unify the API and simply *IGNORE* everything > besides the version, when talking toSimplePush Variant. > > -- > 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 > https://lists.jboss.org/mailman/listinfo/aerogear-dev > _______________________________________________ aerogear-dev mailing list aerogear-dev(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/aerogear-dev