<div dir="ltr">See <a href="https://github.com/aerogear/aerogear.org/pull/86">https://github.com/aerogear/aerogear.org/pull/86</a><br></div><div class="gmail_extra"><br><br><div class="gmail_quote">On Fri, Jun 7, 2013 at 10:01 PM, Matthias Wessendorf <span dir="ltr"><<a href="mailto:matzew@apache.org" target="_blank">matzew@apache.org</a>></span> wrote:<br>
<blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div dir="ltr">Hello,<div><br></div><div>following up on the previous drafts...</div><div><br></div><div><p style="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">
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="border-bottom-style:solid;border-bottom-width:1px;font-size:2em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px;border-bottom-color:rgb(238,238,238)"><a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px"><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="font-size:1.2em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px"><a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">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="border-bottom-style:solid;border-bottom-width:1px;font-size:2em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px;border-bottom-color:rgb(238,238,238)"><a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px"><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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">The client SDK offers the following features:</p><ul style="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px;padding:0px 0px 0px 30px">
<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="font-size:1.5em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px"><a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px;padding:0px 0px 0px 30px"><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><p style="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">
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="font-size:1.2em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px"><a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">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="font-size:1.5em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px"><a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px"><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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px;padding:0px 0px 0px 30px"><li>Disables Push (Settings)</li>
<li>Deinstalls the app</li></ul><h4 style="font-size:1.2em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px"><a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">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="border-bottom-style:solid;border-bottom-width:1px;font-size:2em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px;border-bottom-color:rgb(238,238,238)"><a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;font-size:15.454545021057129px;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:15px 0px">To be discussed.....</p><h2 style="border-bottom-style:solid;border-bottom-width:1px;font-size:2em;font-family:Helvetica,arial,freesans,clean,sans-serif;margin:1em 0px 15px;padding:0px;border-bottom-color:rgb(238,238,238)">
<a name="13f203a6b9f039b5_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="line-height:22.727272033691406px;margin-right:0px;font-size:15.454545021057129px;margin-left:0px;margin-bottom:0px!important;font-family:Helvetica,arial,freesans,clean,sans-serif;margin-top:15px">
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="line-height:22.727272033691406px;margin-right:0px;font-size:15.454545021057129px;margin-left:0px;margin-bottom:0px!important;font-family:Helvetica,arial,freesans,clean,sans-serif;margin-top:15px">
<em><br></em></p><p style="line-height:22.727272033691406px;margin-right:0px;font-size:15.454545021057129px;margin-left:0px;margin-bottom:0px!important;font-family:Helvetica,arial,freesans,clean,sans-serif;margin-top:15px">
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><span class="HOEnZb"><font color="#888888"><br>
</font></span></div><span class="HOEnZb"><font color="#888888"><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></font></span></div>
</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>