<html><head><meta http-equiv="Content-Type" content="text/html charset=iso-8859-1"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space; "><div apple-content-edited="true"><br></div>
<br><div><div>On Jun 7, 2013, at 4:01 PM, Matthias Wessendorf <<a href="mailto:matzew@apache.org">matzew@apache.org</a>> wrote:</div><br class="Apple-interchange-newline"><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">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="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; 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; 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="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; 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">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="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; 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="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; 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>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><br></div></div><div apple-content-edited="true">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. Plus, if scheduled notifications is implemented in future, then the actual send could be customized by user's timezone.</div><div><br></div><blockquote type="cite"><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="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; 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="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; 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; 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="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; 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="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; 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="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; 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">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>
_______________________________________________<br>aerogear-dev mailing list<br><a href="mailto:aerogear-dev@lists.jboss.org">aerogear-dev@lists.jboss.org</a><br>https://lists.jboss.org/mailman/listinfo/aerogear-dev</blockquote></div><br></body></html>