This document describes the functionality of a client SDK that works with the AeroGear Unified Push Server.
The AeroGear Unified Push Server 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.
Goal: A client library that is easy to use for device (Mobile Variant Instance
) registration and (later) sending Push Notification Messages.
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 his application. The way how the different platforms do this is very different and not part of this document.
TL;DR: The token
is negotiated between the device and the actual Push Network (GCM/APNs/SimplePush) and afterwards passed to a platform specific callback, where the application of the AeroGear developer has access to it. The developer can now upload it to the AeroGear Unified Push Server, to indicate there is a newMobile Variant Instance
for a Push Application Variant
.
Basically, the token
identifies the device, running our mobile application, with a Push Network. Hence the token
is required when the AeroGear Unified Push Server is willing to submit Push Notification Messages against the supportedPush Networks: For sending out Push Notification Messages, 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.
When a server-side application wants to send a Push Notification Message it needs to submit a small message payload, combined with a list of tokens, to indicate those devices that should receive the message.
More details about the server-side part of this can be found in the AeroGear Unified Push Server spec.
WARNING: The focus of this specification is to describe the abstract minimum, not any specific requirements for one of the supported client platforms
The client SDK convenience methods to simplify the following tasks
Mobile Variant Instance
Mobile Variant Instance
Mobile Variant Instance
Method that helps to initially register the client device information with the AeroGear Unified Push Server. Required Data is defined in the server side spec.
The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.
Method that helps to update the client device information. One reason could be a changed device token
or a newalias
of the application user.
Note: 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 device token
from the Push Network, is passed to a platform specific callback, always on application launch.
The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.
Optional method that helps to unregister the client device information with the AeroGear Unified Push Server. Note: The method is optional, since not all supported Push Networks recommend having a client application performing an _unregister. Apple for instance has a Feedback Service
, which the AeroGear Unified Push Server needs to freequently query for inactive tokens. Tokens, with Apple, are inactive when the user:
On platforms a unregistration may be valid, hence this method is option.
The method should check if a network connection is available, if not an 'error callback' should be invoked, to immediately contact the calling code.
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".
To be discussed.....
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 Intent
is required, therefore it may make sense if the AeroGear Android Push Client Library offers a convenience implementation for this class.