<div dir="ltr">based on the "unification issues" (see old thread), Dan, Kris and I met<div><br></div><div><br></div><div>here is what we have come up with:</div><div><br></div><div><br></div><div><br></div><div><br>
</div><div><h2 style="margin-right:0px;margin-bottom:15px;margin-left:0px;padding:0px;font-size:2em;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(238,238,238);color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;margin-top:0px!important">
Draft for the AeroGear Push Message Format</h2><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">The Unified Push Server allows two different ways to send message to the native Push API, of the supported devices:</p>
<ul style="margin:15px 0px;padding:0px 0px 0px 30px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px"><li>broadcast<ul style="margin:0px;padding:0px 0px 0px 30px">
<li>to all <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">MobileVariants</code> and their <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">MobileVariant Instances</code> (devices)</li>
<li>to one specific <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">MobileVariant</code> and its <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">MobileVariant Instances</code> (devices)</li>
</ul></li><li>selective Send</li></ul><h3 style="margin:1em 0px 15px;padding:0px;font-size:1.5em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="broadcast" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#broadcast" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Broadcast</h3>
<pre style="font-size:13px;line-height:19px;font-family:Consolas,'Liberation Mono',Courier,monospace;word-wrap:break-word;margin-top:15px;margin-bottom:15px;background-color:rgb(248,248,248);border:1px solid rgb(221,221,221);overflow:auto;padding:6px 10px;border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;color:rgb(0,0,0)">
<code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px;padding:0px;border:none;background-color:transparent;border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">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"}'
<a href="http://localhost:8080/ag-push/rest/sender/broadcast">http://localhost:8080/ag-push/rest/sender/broadcast</a>
</code></pre><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">If the <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">ag-push-application</code> header is used, a message is send to a <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">PushApplication</code> and <strong>ALL</strong>MobileVariantInstances will receive the message.</p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">If the <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">ag-mobile-variant</code> header is used, a message is send to a particular <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">MobileVariant</code> and <strong>ALL</strong> of its MobileVariantInstances will receive the message.</p>
<h4 style="margin:1em 0px 15px;padding:0px;font-size:1.2em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="message-format" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#message-format" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Message Format</h4>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">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.</p>
<h5 style="margin:1em 0px 15px;padding:0px;font-size:1em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;line-height:22.727272033691406px"><a name="simplepush-special-keys" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#simplepush-special-keys" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>SimplePush special keys</h5>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">Every AeroGear-SimplePush application can subscribe to a <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">broadcast</code> channel. If, on the above<code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">broadcast</code> Endpoint, you are providing the <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">simple-push</code> 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). <strong>NOTE:</strong> On all other platforms, the <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">simple-push</code> key will be simply :-) ignored. Also, for SimplePush, all <strong>OTHER</strong> keys are ignored (since that does not make sense for SP).</p>
<h5 style="margin:1em 0px 15px;padding:0px;font-size:1em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;line-height:22.727272033691406px"><a name="ios-special-keys" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#ios-special-keys" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>iOS special keys</h5>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">If the JSON map contains on of the following reserved keywords, Apple specific hooks will be invoked on the device:</p>
<ul style="margin:15px 0px;padding:0px 0px 0px 30px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px"><li><code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">alert</code> (triggers a dialog, displaying the value - no iOS API needs to be invoked by the app developer)</li>
<li><code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">sound</code> (plays a given sound - no iOS API needs to be invoked by the app developer)</li>
<li><code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">badge</code> (sets the value of the badge icon - no iOS API needs to be invoked by the app developer)</li>
</ul><h5 style="margin:1em 0px 15px;padding:0px;font-size:1em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;line-height:22.727272033691406px"><a name="android-special-keys" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#android-special-keys" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Android special keys</h5>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">None! The JSON map is submitted as it is, directly to the device. There are no Android specific keywords.</p>
<h3 style="margin:1em 0px 15px;padding:0px;font-size:1.5em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="selective-send" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#selective-send" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Selective Send</h3>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">A message is send to a restricted number of <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">MobileVariantInstances</code>, based on a given criteria. The following example shows the correspondent HTTP interface:</p>
<pre style="font-size:13px;line-height:19px;font-family:Consolas,'Liberation Mono',Courier,monospace;word-wrap:break-word;margin-top:15px;margin-bottom:15px;background-color:rgb(248,248,248);border:1px solid rgb(221,221,221);overflow:auto;padding:6px 10px;border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;color:rgb(0,0,0)">
<code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px;padding:0px;border:none;background-color:transparent;border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px">curl -v -H "Accept: application/json" -H "Content-type: application/json"
-X POST
-d '{
"alias" : ["<a href="mailto:user@account.com">user@account.com</a>", "<a href="mailto:jay@redhat.org">jay@redhat.org</a>", ....],
"deviceType" : ["iPad", "AndroidTablet"],
"message": {"key":"value", "key2":"other value", "alert":"HELLO!",
"simple-push": { "SomeCategory":"version=123", "anotherCategory":"version=456"}
}
}'
<a href="http://localhost:8080/ag-push/rest/sender/selected/{PushApplicationID}">http://localhost:8080/ag-push/rest/sender/selected/{PushApplicationID}</a>
</code></pre><h4 style="margin:1em 0px 15px;padding:0px;font-size:1.2em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="message-format-1" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#message-format-1" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Message Format</h4>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">Besides the actual payload the API accepts a few <em>classifiers</em> to select a subset of registered devices.</p>
<h5 style="margin:1em 0px 15px;padding:0px;font-size:1em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;line-height:22.727272033691406px"><a name="query-component" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#query-component" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Query component</h5>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">Currently the Server will support the following query criterias:</p>
<ul style="margin:15px 0px;padding:0px 0px 0px 30px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px"><li><code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">alias</code>: A list of email address (or usernames) to send messages to <em>ALL</em> devices of the users. The<code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">alias</code> needs to be stored, when the device is registering itself with the server. See here for <a href="https://github.com/matzew/ag-client-push-sdk/blob/master/push-sdk/AGClientDeviceInformation.h#L48-L52" style="color:rgb(65,131,196);text-decoration:none">details</a></li>
<li><code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">deviceType</code>: A list of raw devices types that should receive the message (e.g. Coupon only for iPad and AndroidTablets). The <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">deviceType</code> needs to be stored, when the device is registering itself with the server. See here for <a href="https://github.com/matzew/ag-client-push-sdk/blob/master/push-sdk/AGClientDeviceInformation.h#L43-L46" style="color:rgb(65,131,196);text-decoration:none">details</a>. <em><strong>NOTE:</strong></em> For SimplePush, the <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">deviceType</code> is <strong>ONLY</strong> <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">web</code>. No specifics on the actual device are used due to general limitations on "user agent sniffing".</li>
</ul><h5 style="margin:1em 0px 15px;padding:0px;font-size:1em;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;line-height:22.727272033691406px"><a name="message-payload" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#message-payload" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Message Payload</h5>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">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.</p>
<h6 style="margin:1em 0px 15px;padding:0px;color:rgb(119,119,119);font-size:1em;font-family:Helvetica,arial,freesans,clean,sans-serif;line-height:22.727272033691406px"><a name="simplepush" class="" href="https://gist.github.com/matzew/d6f1b88b85e2f6c18031#simplepush" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>SimplePush</h6>
<p style="margin-top:15px;margin-right:0px;margin-left:0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px;margin-bottom:0px!important">
For SimplePush an extra <code style="font-size:12px;line-height:normal;font-family:Consolas,'Liberation Mono',Courier,monospace;margin:0px 2px;padding:0px 5px;border:1px solid rgb(221,221,221);background-color:rgb(248,248,248);border-top-left-radius:3px;border-top-right-radius:3px;border-bottom-right-radius:3px;border-bottom-left-radius:3px;white-space:nowrap">simple-push</code> object is provided. Only for SimplePush Variants this key is used (similar to the broadcast case). However <em>HERE</em> we use an object, to send (selective) different versions to different channels.</p>
</div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div><br></div><div style>'Thoughts ??</div><div><br></div><div><br></div><div>
<br></div><div><br></div><div><br><div class="gmail_extra">-- <br>Matthias Wessendorf <br><br>blog: <a href="http://matthiaswessendorf.wordpress.com/" target="_blank">http://matthiaswessendorf.wordpress.com/</a><br>sessions: <a href="http://www.slideshare.net/mwessendorf" target="_blank">http://www.slideshare.net/mwessendorf</a><br>
twitter: <a href="http://twitter.com/mwessendorf" target="_blank">http://twitter.com/mwessendorf</a>
</div></div></div>