<div dir="ltr">Hello,<div><br></div><div>following up on the previous drafts...</div><div><br></div><div><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">
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">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);color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="motivation--purpose" class="" href="https://gist.github.com/matzew/569190db18694afe22f6#motivation--purpose" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Motivation / Purpose</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 <a href="http://aerogear.org/docs/specs/aerogear-server-push/" style="color:rgb(65,131,196);text-decoration:none">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;color:rgb(0,0,0);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;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="background-push-network-token" class="" 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"><span class=""></span></a>Background: Push Network Token</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">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;color:rgb(0,0,0);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">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);color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="functionality" class="" href="https://gist.github.com/matzew/569190db18694afe22f6#functionality" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Functionality</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"><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;color:rgb(0,0,0);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;color:rgb(0,0,0);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;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="registration-and-updating-of-a-mobile-variant-instance" class="" 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"><span class=""></span></a>Registration and Updating of a Mobile Variant Instance</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">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;color:rgb(0,0,0);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;color:rgb(0,0,0);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><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 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;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="reachability" class="" href="https://gist.github.com/matzew/569190db18694afe22f6#reachability" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Reachability</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 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;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="unregistration-of-client-device-information" class="" 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"><span class=""></span></a>Unregistration of client device information</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"><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">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;color:rgb(0,0,0);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;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="reachability-1" class="" href="https://gist.github.com/matzew/569190db18694afe22f6#reachability-1" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Reachability</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 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);color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="authsecurity" class="" href="https://gist.github.com/matzew/569190db18694afe22f6#authsecurity" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Auth/Security</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">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);color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif">
<a name="platform-specific-details" class="" href="https://gist.github.com/matzew/569190db18694afe22f6#platform-specific-details" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"><span class=""></span></a>Platform specific details</h2>
<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">
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;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">
<em><br></em></p><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">
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">https://github.com/aerogear/aerogear-js/blob/Notifier/src/unified-push/aerogear.unifiedpush.js</a><br>
</p></div><div style><br></div><div style>* iOS (to register iOS Variant Instance):</div><div style><a href="https://github.com/matzew/ag-client-push-sdk">https://github.com/matzew/ag-client-push-sdk</a><br></div><div><br>
</div><div><br></div><div><br></div><div style>-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>