[aerogear-dev] AeroGear Push Message Format
Sebastien Blanc
scm.blanc at gmail.com
Mon May 27 08:22:47 EDT 2013
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 at apache.org>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>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/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>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/98762c8d3f516e1abd38#selective-send>Selective
> 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" : ["user at account.com", "jay at redhat.org", ....],
>
> "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>Message
> 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-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>
>
> <https://gist.github.com/matzew/98762c8d3f516e1abd38#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/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/{SimplePushVariantID}
>
> <https://gist.github.com/matzew/98762c8d3f516e1abd38#message-format-2>Message
> 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>Selective
> 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>Message
> 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 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/20130527/00067bfe/attachment-0001.html
More information about the aerogear-dev
mailing list