<div dir="ltr"><h1 style="font-size:28px;margin:0px 0px 10px;padding:0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><span style="font-size:14px;font-weight:normal;line-height:20px">Hello!</span><br>
</h1><div style><span style="font-size:14px;line-height:20px">I have created an EARLY version of a client spec for push. As discussed earlier focus is offering convenience methods for the registration process. (and unregister on some platforms).</span></div>
<div style><span style="font-size:14px;line-height:20px"><br></span></div><div style><span style="font-size:14px;line-height:20px">The SEND (from client --> Unified Push Server --> other clients) is out of scope. The Unified Push is more nofification/signaling, and not chat :) </span></div>
<div style><span style="font-size:14px;line-height:20px"><br></span></div><div style><span style="font-size:14px;line-height:20px">URL: <a href="https://gist.github.com/matzew/4fcf677eb217737265a8">https://gist.github.com/matzew/4fcf677eb217737265a8</a></span></div>
<div style><span style="font-size:14px;line-height:20px"><br></span></div><div><span style="font-size:14px;font-weight:normal;line-height:20px"><br></span></div><h1 style="font-size:28px;margin:0px 0px 10px;padding:0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif">
AeroGear Unified Push Client Spec / SDK (DRAFT 0.0.1)</h1><p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">This document describes the functionality of a client SDK that works with the <a href="https://gist.github.com/matzew/b918eb45d3f17de09b8f" style="color:rgb(65,131,196);text-decoration:none">AeroGear Unified Push Server</a>.</p>
<h2 style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="motivation--purpose" class="" href="https://gist.github.com/matzew/4fcf677eb217737265a8#motivation--purpose" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Motivation / Purpose</h2>
<p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">The <a href="https://gist.github.com/matzew/b918eb45d3f17de09b8f" style="color:rgb(65,131,196);text-decoration:none">AeroGear Unified Push Server</a> offers a rich set of functionality, accessible via HTTP. Instead of having to manually/directly work with the HTTP interface a convenience 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:13.63636302947998px;line-height:20px"><strong>Goal:</strong> A client library that is easy to use for 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(234,234,234);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>) registration and (later) sending <em>Push Notification Messages</em>.</p>
<h2 style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);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/4fcf677eb217737265a8#background-push-network-token" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Background: Push Network Token</h2>
<p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">In order to be able to receive native push messages from a Push Network (e.g. APNs, GCM or SimplePush), the mobile application developer needs to receive a device token (or registration ID), from a device, that is running <em>his</em> application. The way how the different platforms do this is <em>very</em> different 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:13.63636302947998px;line-height:20px"><strong>TL;DR:</strong> 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(234,234,234);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">token</code> is negotiated between the device and the actual Push Network (GCM/APNs/SimplePush) and afterwards passed to a <em>platform specific callback</em>, where the application of the AeroGear developer has access to it. The developer can now upload it to the <em>AeroGear Unified Push 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(234,234,234);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> 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(234,234,234);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">Push Application Variant</code>.</p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">Basically, 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(234,234,234);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">token</code> identifies the device, running our mobile application, with a Push Network. Hence 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(234,234,234);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">token</code> is required when the <em>AeroGear Unified Push Server</em> is willing to submit <em>Push Notification Messages</em> against the <em>supported</em>Push Networks: For sending out <em>Push Notification Messages</em>, the different Push Networks (e.g. GCM, APNs or SimplePush) need to receive a small message payload, combined with a list of tokens, to indicate those devices that should receive the message.</p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">When a server-side application wants to send a <em>Push Notification Message</em> it needs to submit a small message payload, combined with a list of tokens, to indicate those devices that should receive the message.</p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">More details about the server-side part of this can be found in the <em>AeroGear Unified Push Server</em> <a href="https://gist.github.com/matzew/b918eb45d3f17de09b8f" style="color:rgb(65,131,196);text-decoration:none">spec</a>.</p>
<h2 style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="functionality" class="" href="https://gist.github.com/matzew/4fcf677eb217737265a8#functionality" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Functionality</h2>
<p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px"><strong>WARNING:</strong> <em>The focus of this specification is to describe the abstract minimum, not any specific requirements for one of the supported client platforms</em></p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">The client SDK convenience methods to simplify the following tasks</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:13.63636302947998px;line-height:20px">
<li>Initial Registration 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(234,234,234);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></li>
<li>Updating a registered <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(234,234,234);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><ul style="margin:0px;padding:0px 0px 0px 30px">
<li>update the token (could be changed, by the <em style="margin-top:0px">Push Network</em>)</li><li>store/update other data (e.g. alias, OS version)</li></ul></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(234,234,234);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></li>
</ul><h3 style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="registration-of-client-device-information" class="" href="https://gist.github.com/matzew/4fcf677eb217737265a8#registration-of-client-device-information" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Registration of client device information</h3>
<p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">Method that helps to initially register the client device information with the <a href="https://gist.github.com/matzew/b918eb45d3f17de09b8f" style="color:rgb(65,131,196);text-decoration:none">AeroGear Unified Push Server</a>. Required Data is defined in the server side spec.</p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.</p>
<h3 style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="update-of-client-device-information" class="" href="https://gist.github.com/matzew/4fcf677eb217737265a8#update-of-client-device-information" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Update of client device information</h3>
<p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">Method that helps to update the client device information. One reason could be a changed <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(234,234,234);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> or 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(234,234,234);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">alias</code> of the application user.</p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px"><strong>Note</strong>: It's recommended by most Push Network, to ALWAYs update the information, since a token (that identifies the device with the push network may change). Also, all platforms invoke the hook (see above) where 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(234,234,234);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>from the Push Network, is passed to a <em>platform specific callback</em>, <em>always</em> on application launch.</p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.</p>
<h3 style="margin:20px 0px 10px;padding:0px;font-size:18px;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/4fcf677eb217737265a8#unregistration-of-client-device-information" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Unregistration of client device information</h3>
<p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">Optional method that helps to unregister the client device information with the <a href="https://gist.github.com/matzew/b918eb45d3f17de09b8f" 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 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(234,234,234);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:13.63636302947998px;line-height:20px"><li>Disables Push (Settings)</li><li>Deinstalls the app</li>
</ul><p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">On platforms a <em>unregistration</em> may be valid, hence this method is option.</p>
<p style="margin:15px 0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.</p>
<h3 style="margin:20px 0px 10px;padding:0px;font-size:18px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="sending" class="" href="https://gist.github.com/matzew/4fcf677eb217737265a8#sending" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Sending</h3>
<p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">At some point, a client may trigger a push notification, however not now: Focus is to notify clients. It's not the goal to provide a "chat client".</p>
<h2 style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif"><a name="authsecurity" class="" href="https://gist.github.com/matzew/4fcf677eb217737265a8#authsecurity" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Auth/Security</h2>
<p style="margin:0px 0px 15px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px">To be discussed.....</p><h2 style="margin:20px 0px 10px;padding:0px;font-size:24px;border-bottom-width:1px;border-bottom-style:solid;border-bottom-color:rgb(204,204,204);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/4fcf677eb217737265a8#platform-specific-details" style="color:rgb(65,131,196);text-decoration:none;display:block;padding-left:30px"></a>Platform specific details</h2>
<p style="margin-top:0px;margin-right:0px;margin-left:0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px;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 may offer utilities to even more simplify this. Example: In Android a custom <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(234,234,234);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 may make sense if the AeroGear Android Push Client Library offers a convenience implementation for this class.</p>
<p style="margin-top:0px;margin-right:0px;margin-left:0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px;margin-bottom:0px!important"><br></p><p style="margin-top:0px;margin-right:0px;margin-left:0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px;margin-bottom:0px!important">
<br></p><p style="margin-top:0px;margin-right:0px;margin-left:0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px;margin-bottom:0px!important"><br></p>
<p style="margin-top:0px;margin-right:0px;margin-left:0px;color:rgb(0,0,0);font-family:Helvetica,arial,freesans,clean,sans-serif;font-size:13.63636302947998px;line-height:20px;margin-bottom:0px!important"><br></p><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>