<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 &lt;<a href="mailto:matzew@apache.org">matzew@apache.org</a>&gt; 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&nbsp;<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&nbsp;<a href="http://aerogear.org/docs/specs/aerogear-server-push/" style="color:rgb(65,131,196);text-decoration:none">AeroGear UnifiedPush Server</a>&nbsp;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>&nbsp;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&nbsp;<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>&nbsp;is passed, by the underlying Operating-System, to the mobile application. Details are different on each platform and&nbsp;<strong>not</strong>&nbsp;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&nbsp;<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>&nbsp;needs to be registered with the&nbsp;<em>AeroGear UnifiedPush Server</em>, to indicate there is a new&nbsp;<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>&nbsp;for a&nbsp;<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&nbsp;<em>AeroGear Unified Push Server</em>&nbsp;<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>&nbsp;<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&nbsp;<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&nbsp;<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>&nbsp;(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&nbsp;<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>&nbsp;method (or callback). Since the Push Network (e.g. APNs or GCM)&nbsp;<em>may</em>&nbsp;assign a&nbsp;<strong>new</strong>token to a device, it is&nbsp;<em>recommended</em>&nbsp;to&nbsp;<em>always</em>&nbsp;(re)register the&nbsp;<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>&nbsp;with the&nbsp;<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&nbsp;<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>&nbsp;the&nbsp;<em>AeroGear UnifiedPush Server</em>&nbsp;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>&nbsp;<em>Identifies the device/user-agent within its Push Network.</em></li>
<li><strong>deviceType:</strong>&nbsp;<em>The device type of the device or the user agent.</em></li><li><strong>mobileOperatingSystem:</strong>&nbsp;<em>The name of the underlying Operating System.</em></li><li><strong>osVersion:</strong>&nbsp;<em>The version of the used Operating System.</em></li>
<li><strong>alias:</strong>&nbsp;_ Application specific alias to identify users with the system. For instance an&nbsp;<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&nbsp;<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>&nbsp;<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 &amp; Android users too.&nbsp;</div><div><br></div></div><div apple-content-edited="true">It would be good if user's "<b>timezone"</b>&nbsp;can be an optional field passed at registration (similar to Parse). This can help&nbsp;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>&nbsp;may change, some of the above metadata is more likely to change. Therefore another reason to always send this metadata to the&nbsp;<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>&nbsp;method that helps to unregister the client device information with the&nbsp;<a href="http://aerogear.org/docs/specs/aerogear-server-push/" style="color:rgb(65,131,196);text-decoration:none">AeroGear Unified Push Server</a>.&nbsp;<strong>Note:</strong>&nbsp;<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&nbsp;<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>&nbsp;needs to freequently query for inactive tokens. Tokens, with Apple, are<em>inactive</em>&nbsp;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&nbsp;<em>may</em>&nbsp;offer utilities to even more simplify this process.&nbsp;<em>For example: In Android a custom&nbsp;<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>&nbsp;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&nbsp;(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>