[aerogear-dev] AeroGear Push Message Format

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