[aerogear-dev] AeroGear Push Message Format
Matthias Wessendorf
matzew at apache.org
Mon May 27 08:26:04 EDT 2013
This is all fire and forget, there is no guarantee that the messages are
delivered.
Response would be: 200 "Job submitted"
On Mon, May 27, 2013 at 2:22 PM, Sebastien Blanc <scm.blanc at gmail.com>wrote:
> 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
>>
>
>
> _______________________________________________
> aerogear-dev mailing list
> aerogear-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/aerogear-dev
>
--
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/20130527/e15a07b5/attachment-0001.html
More information about the aerogear-dev
mailing list