<div dir="ltr"><br><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Jun 7, 2013 at 10:20 PM, Deepali Khushraj <span dir="ltr"><<a href="mailto:dkhushra@redhat.com" target="_blank">dkhushra@redhat.com</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><br></div>
<br><div><div class="im"><div>On Jun 7, 2013, at 4:01 PM, Matthias Wessendorf <<a href="mailto:matzew@apache.org" target="_blank">matzew@apache.org</a>> wrote:</div><br><blockquote type="cite"><div dir="ltr">Hello,<div>
<br></div><div>following up on the previous drafts...</div><div><br></div><div><p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">
This document describes the functionality of a client SDK that works with the <a href="http://aerogear.org/docs/specs/aerogear-server-push/" style="color:rgb(65,131,196);text-decoration:none" target="_blank">AeroGear UnifiedPush Server</a>.</p>
<h2 style="margin:1em 0px 15px;padding:0px;font-size:2em;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(238,238,238);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="13f204cb6230a1c2_motivation--purpose" href="https://gist.github.com/matzew/569190db18694afe22f6#motivation--purpose" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Motivation / Purpose</h2>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">The <a href="http://aerogear.org/docs/specs/aerogear-server-push/" style="color:rgb(65,131,196);text-decoration:none" target="_blank">AeroGear UnifiedPush Server</a> is accessible via HTTP. Instead of having to manually register a device (<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">MobileVariantInstance</code>) with the HTTP interface, a client library should be offered.</p>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px"><strong>Goal:</strong> A client library to register a mobile application (<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">MobileVariantInstance</code>) with the UnifiedPush Server.</p>
<h4 style="margin:1em 0px 15px;padding:0px;font-size:1.2em;font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="13f204cb6230a1c2_background-push-network-token" href="https://gist.github.com/matzew/569190db18694afe22f6#background-push-network-token" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Background: Push Network Token</h4>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">To receive native push notifications from a Push Network (e.g. APNs, GCM or SimplePush), the mobile device is identified with a unique <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">device-token</code>, assigned by the actual Push Network. This<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">device-token</code> is passed, by the underlying Operating-System, to the mobile application. Details are different on each platform and <strong>not</strong> part of this document.</p>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">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">device-token</code> needs to be registered with the <em>AeroGear UnifiedPush Server</em>, to indicate there is a new <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">MobileVariantInstance</code> for 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">MobileVariant</code>. More details about the server-side part of this can be found in the <em>AeroGear Unified Push Server</em> <a href="http://aerogear.org/docs/specs/aerogear-server-push/" style="color:rgb(65,131,196);text-decoration:none" target="_blank">spec</a>.</p>
<h2 style="margin:1em 0px 15px;padding:0px;font-size:2em;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(238,238,238);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="13f204cb6230a1c2_functionality" href="https://gist.github.com/matzew/569190db18694afe22f6#functionality" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Functionality</h2>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px"><strong>WARNING:</strong> <em>The focus of this specification is to describe the generic minimum and not any platform-specific requirements</em></p>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">The client SDK offers the following features:</p><ul style="margin:15px 0px;padding:0px 0px 0px 30px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">
<li>Registration and Updating of 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">MobileVariantInstance</code></li>
<li>Unregistration of 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">Mobile Variant Instance</code> (optional, due to platform specific restrictions)</li>
</ul><h3 style="margin:1em 0px 15px;padding:0px;font-size:1.5em;font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="13f204cb6230a1c2_registration-and-updating-of-a-mobile-variant-instance" href="https://gist.github.com/matzew/569190db18694afe22f6#registration-and-updating-of-a-mobile-variant-instance" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Registration and Updating of a Mobile Variant Instance</h3>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">Everytime when a mobile application launches it receives the above mentioned <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">device-token</code>, via a<em>platform-specific</em> method (or callback). Since the Push Network (e.g. APNs or GCM) <em>may</em> assign a <strong>new</strong>token to a device, it is <em>recommended</em> to <em>always</em> (re)register 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">device-token</code> with the <em>AeroGear UnifiedPush Server</em>.</p>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">Besides 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">device-token</code> the <em>AeroGear UnifiedPush Server</em> is able to store some of the below device- or user-specific metadata:</p>
<ul style="margin:15px 0px;padding:0px 0px 0px 30px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px"><li><strong>deviceToken:</strong> <em>Identifies the device/user-agent within its Push Network.</em></li>
<li><strong>deviceType:</strong> <em>The device type of the device or the user agent.</em></li><li><strong>mobileOperatingSystem:</strong> <em>The name of the underlying Operating System.</em></li><li><strong>osVersion:</strong> <em>The version of the used Operating System.</em></li>
<li><strong>alias:</strong> _ Application specific alias to identify users with the system. For instance an <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">email address</code>or 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">username</code>._</li>
<li><strong>category:</strong> <em>Used tp apply a "tag". Mainly usful for the SimplePush channel(s).</em></li></ul></div></div></blockquote><div><br></div></div><div><div>Wondering why the "category" feature is only available with SimplePush and not for iOS and Android? It seems like filtering notifications by category could help iOS & Android users too. </div>
</div></div></div></blockquote><div><br></div><div style>It can be used for iOS and Android too. But on SimplePush it may make more sense, since the channels have only IDs, so we have to notion of a tag (e.g. "mail" notifcation, "IM" notification), in one (web) app.</div>
<div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div><div><br></div></div><div>It would be good if user's "<b>timezone"</b> can be an optional field passed at registration (similar to Parse). This can help avoid sending notifications to users at odd hours. </div>
</div></div></blockquote><div><br></div><div style>That is more business logic, like "salary" or "geoloaction". E.g. in a calendar app (business logic), I already store all these infos in the "calendar database" (taking timezone as an example). Not sure why a push server should store all this data as well.</div>
<div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div>Plus, if scheduled notifications is implemented in future, then the actual send could be customized by user's timezone.</div>
</div></div></blockquote><div><br></div><div style>Already today to business app can have (JavaEE) Scheduled Jobs. Based on what every query/filter, you can send a list of "aliases" to the UnifiedPush server. But let's not discuss server features in a "client spec" thread :)</div>
<div style><br></div><div style>-M</div><div><br></div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div><br></div>
<blockquote type="cite"><div class="im"><div dir="ltr"><div><p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">
Besides the slight chance that 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">device-token</code> may change, some of the above metadata is more likely to change. Therefore another reason to always send this metadata to the <em>AeroGear UnifiedPush Server</em>.</p>
<h4 style="margin:1em 0px 15px;padding:0px;font-size:1.2em;font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="13f204cb6230a1c2_reachability" href="https://gist.github.com/matzew/569190db18694afe22f6#reachability" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Reachability</h4>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">The client SDK needs to check if the device can establish a connection to the internet (PushNetwork and UnifiedPush Server). It should make use of the platform-specific APIs to check the reachablility of the services.</p>
<h3 style="margin:1em 0px 15px;padding:0px;font-size:1.5em;font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="13f204cb6230a1c2_unregistration-of-client-device-information" href="https://gist.github.com/matzew/569190db18694afe22f6#unregistration-of-client-device-information" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Unregistration of client device information</h3>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px"><em>Optional</em> method that helps to unregister the client device information with the <a href="http://aerogear.org/docs/specs/aerogear-server-push/" style="color:rgb(65,131,196);text-decoration:none" target="_blank">AeroGear Unified Push Server</a>. <strong>Note:</strong> <em>The method is optional, since not all supported Push Networks recommend having a client application actively performing an _unregister</em>. Apple for instance has 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">Feedback Service</code>, which the<em>AeroGear Unified Push Server</em> needs to freequently query for inactive tokens. Tokens, with Apple, are<em>inactive</em> when the user:</p>
<ul style="margin:15px 0px;padding:0px 0px 0px 30px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px"><li>Disables Push (Settings)</li>
<li>Deinstalls the app</li></ul><h4 style="margin:1em 0px 15px;padding:0px;font-size:1.2em;font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="13f204cb6230a1c2_reachability-1" href="https://gist.github.com/matzew/569190db18694afe22f6#reachability-1" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Reachability</h4>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">The client SDK needs to check if the device can establish a connection to the internet (PushNetwork and UnifiedPush Server). It should make use of the platform-specific APIs to check the reachablility of the services.</p>
<h2 style="margin:1em 0px 15px;padding:0px;font-size:2em;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(238,238,238);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="13f204cb6230a1c2_authsecurity" href="https://gist.github.com/matzew/569190db18694afe22f6#authsecurity" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Auth/Security</h2>
<p style="margin:15px 0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px">To be discussed.....</p><h2 style="margin:1em 0px 15px;padding:0px;font-size:2em;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(238,238,238);font-family:Helvetica,arial,freesans,clean,sans-serif">
<a name="13f204cb6230a1c2_platform-specific-details" href="https://gist.github.com/matzew/569190db18694afe22f6#platform-specific-details" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px" target="_blank"><span></span></a>Platform specific details</h2>
<p style="margin-top:15px;margin-right:0px;margin-left:0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px;margin-bottom:0px!important">
Every client platform has it's own base APIs, to receive Push Message from it's Push Network. The AeroGear client SDK <em>may</em> offer utilities to even more simplify this process. <em>For example: In Android a custom <code style="font-style:normal;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">Intent</code> is required, therefore it would make sense if the "AeroGear Android Push Client Library" offers a convenience implementation for this class.</em></p>
<p style="margin-top:15px;margin-right:0px;margin-left:0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px;margin-bottom:0px!important">
<em><br></em></p><p style="margin-top:15px;margin-right:0px;margin-left:0px;font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:15.454545021057129px;line-height:22.727272033691406px;margin-bottom:0px!important">
BTW... Current, EARLY, implementations:</p><p style="margin-top:15px;margin-right:0px;margin-left:0px;margin-bottom:0px!important">* JavaScript (to register SimplePush Variant Instance):<br><a href="https://github.com/aerogear/aerogear-js/blob/Notifier/src/unified-push/aerogear.unifiedpush.js" target="_blank">https://github.com/aerogear/aerogear-js/blob/Notifier/src/unified-push/aerogear.unifiedpush.js</a><br>
</p></div><div><br></div><div>* iOS (to register iOS Variant Instance):</div><div><a href="https://github.com/matzew/ag-client-push-sdk" target="_blank">https://github.com/matzew/ag-client-push-sdk</a><br></div><div><br>
</div><div><br></div><div><br></div><div>-Matthias</div><div><br></div><div><br clear="all"><div><br></div>-- <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>
_______________________________________________<br>aerogear-dev mailing list<br><a href="mailto:aerogear-dev@lists.jboss.org" target="_blank">aerogear-dev@lists.jboss.org</a><br><a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a></blockquote>
</div><br></div><br>_______________________________________________<br>
aerogear-dev mailing list<br>
<a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>
<a href="https://lists.jboss.org/mailman/listinfo/aerogear-dev" target="_blank">https://lists.jboss.org/mailman/listinfo/aerogear-dev</a><br></blockquote></div><br><br clear="all"><div><br></div>-- <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>