This is an early version of a 'spec' for the AeroGear Native Push Server.
The AeroGear Native Push Server is an abstraction layer for "push enabled" mobile apps. The initial version of the server supports Apple's iOS and Google's Android Operating System.
Goal: We want that any (JBoss/AeroGear powered) mobile application, that is backed by JBoss technology (e.g. admin console, Errai, drools, etc.), is able to easily work with push messages. For a JBoss "backend application" it should be as simple as possible, to send messages to its different mobile clients
###Some Usage Scenarios
- MyWarehouseInc-backend can send messages to different "customer" groups (e.g. discounts for only iOS (or only Android) users).
- MyInsuranceCorp-backend can send important "info messages" to diffenrent variants of its mobile Applications (e.g. to its customer APP (regardless of the OS) AND to the app for their own agents)
- MyPublishing-Company-backend sends updates to all of its apps (free and premium - regardless of the mobile OS). Advanced content is only push to the paying customers...
- A company has different backends (small apps for different tasks) - and these different backends could be able to reach all (or some) of the company's mobile apps
The Native Push Server contains three different components:
- Registration: registry for "push enabled" apps
- Storage: stores the registered applications
- Sender: sends messages to different application
The graphic below gives a little overview:
We have a PushApplicationRegistry defined, which is basically a registry for "push enabled" mobile apps (PushApplication). Such a PushApplication is a logical construct on the backend which is allowed/enabled to send notifications to mobile clients. One example could be the "Twitter Backend" (e.g. for push notification on direct messages).
Now each of the PushApplication can have a few mobile applications, that receive those native push messages (e.g. the offical Twitter iOS client and the offical Twitter Android client).
These "mobile apps" are represented - on the server - with the MobileApplication class. Usually there is only one iOS app and one Android... BUT imagine the case of a "paid/premium app" versus a free app (e.g. something like TwitterPro-iOS and Twitter-free-iOS... NOTE: there is NOTHING like that, I just made these two apps up, to explain the concept).
Of course there are several installations of the iOS(and Android...) app. Each installation is represented with the MobileApplicationInstance class. Each installation is registered by a "device registration service": The actual app on the device submits its token/registrationID (and some other infos) to a HTTP endpoint....
Now the PushApplicationRegistry is the central API to register PushApps and their mobile views, including (device)registration of installations (-> MobileApplication and MobileApplicationInstance).
Java Flow:
PushApplication pa = new PushApplicationImpl();
pa.setName("All The Thingz - backend");
pa.setDescription("Logical rep. of a application
that needs to push notifications to different mobile apps");
// one iOS app:
iOSApp iOSapplication = new iOSApp();
iOSapplication.setAppleAppId("net.wessendorf.Pusher");
iOSapplication.setCertificate("/Users/matzew/Desktop/PUSHER.p12");
iOSapplication.setPassphrase("foo");
// DEVICE REG (an installed app)
MobileApplicationInstance installedApp = new MobileApplicationInstanceImpl();
installedApp.setDeviceToken("adsadsasdadsdas");
iOSapplication.addInstance(installedApp);
// add the iOS app, to the PushApplication:
pa.addMobileApplication(iOSapplication);
// the Android view/app:
AndroidApp droidApp = new AndroidApp();
droidApp.setGoogleAPIKey("dsdsaadsadsdasadsdsa");
// DEVICE REG (an installed app)
MobileApplicationInstance installedAndroidApp = new MobileApplicationInstanceImpl();
installedAndroidApp.setDeviceToken("sdadadssdaasddsaasd");
droidApp.addInstance(installedAndroidApp);
// add the Android app, to the PushApplication:
pa.addMobileApplication(droidApp);
// register it with server:
AeroGearRegistry.registerPushApplication(pa);A configurable database that stores all the information about the registered Push Applications, their mobile views and the installed tokens
The Sender API sends the native push message to a filtered list of applications or users/devices. The Sender will enqueue the message for the different platforms, it is basically an aggregate of the different mobile Application's "send function"
Java Flow:
Sender sender = ...
sender.sendMessageToApplications("Yo, dude!",
listOfApplicationsThatWillReceiveTheMessage);Right now there are the following roles:
- Developer / Admin: Some one that setup up the backend for different mobile applications, to enable push (e.g. iOS certs or Google API keys(more later)
- User: Install an AG-App on his phone
Below are the BASIC use-cases, that the AG Unified/Native Push needs to initially support.
- Enroll AeroGear-Push-User (based on identified roles)
- Remove AeroGear-Push-User
- Developer can register a "push App" (a logical abstraction for all push enabled views(mobile apps))
- Developer can add a mobile view (application) for different operation systems (and their different Push Networks)
- Developer can remove a mobile view (application)
- Developer can unregister "push App"
- User registers his phone with the backend (Device Token + APP-ID are send to the backend)
- User unregisters his phone with the backend (e.g. app got deinstalled, user deleted etc)
- User receives Push Messages (handled by the native OS, once accepted to receive messages)
- Send push messages, done by a user or a developer
- Admin can disable push notifications to devices
Register different user types (based on desired role) with the AG-Native-Push server. The Developer role always requires a username/password. The User is not always required on the server. Some mobile apps don't know the concept of a logged in user (e.g. Sport Broadcast apps), but others do require a User before using the mobile app (e.g. Twitter)
It should be possible to remove Users (app users). That can mean their account is erased, or their device tokes are removed....
A registered Developer can register multiple Push-Apps (e.g. HR mobile, CNN mobile news etc) with the AeroGear Push Server. Each app has a (generated) AeroGear-Application-Key to identify the "server side" representation of the Push-App. Each Push-App can have several mobile views (e.g. one iOS app, one Android app) that receives messages from the server.
The same registered Developer can now add a specific mobile variant/view/representation (e.g. HR-Android) of the server side Push-app. The (abstract) mobile app requires access to the Push Networks (Google or Apple). Therefore such a registered APP needs a certificate and passphrase (iOS) or a Google API key (Android).
A registered Developer should be able to remove the push apps and/or some of their mobile-views (mobile apps) from the server.
Once a User installs and launches the mobile app, the embedding OS generates a Device-Token (or Registration ID on Android). The mobile Application needs to send this Token/ID and the AeroGear-Application-Key to the AeroGear Server, so that the server can register this phone/app with the particular app, to be able to receive push messages.
Note: On iOS the user as to agree to receive push messages
If an app gets uninstalled, the phone is no longer able to receive push messages. Therefore inactive Device-Tokens/Registration-IDs should be removed, on the server. However... there is no harm if invalid keys are used, on the server, when trying to send push messages...
Admin can disable push notifications to devices
Every installed app, is able to receive Push Messages through the APIs, offered by the platforms (iOS, Android). Initially there will be NO client SDK.
Note: On iOS the user as to agree to receive push messages
The Unified Push server acts as a broker to deliver messages (via Native Push) to several devices. Authorized Users (based on their roles) can send push messages to a specific application. For instance a Developer that ONLY owns "AeroGear-App1" is only able to broadcast messages to that particular app. He is NOT able to send a message to "AeroGear-App2"...
Sending message to a specific user.... We need a DSL to filter users etc.... This will be done later...
Later, there will be an option to have the app also submit push messages, to broadcast to other users of the app (or to a specific user). This will be done later...
Initial focus is that the above functionality is ONLY accessable via RESTful/HTTP APIs!
For interaction with the API endpoints (for app registration and sending) we need a proper sec/auth model/workflow. Perhaps something like OAuth...:
NOTE: The User in the image is a DEV/ADMIN in our wordings...
The registration of a device token (from the installed app) is different to APP REGISTRATION or SENDING messages to devices/mobile apps:
Since a mobile app, on a phone, does not always require a registered USER-ACCOUNT on the server (think about something ESPN sports news app), there is/should no "OAuth" be required for registration of a device token...
Later we will have a few more SDKs:
- Client APIs (for Android, iOS)
- Server APIs (send a push message out of your JavaEE app, without submitting (manually) the HTTP calls)
Does admin access removal mean removing the device or device/application pair? If a device has multiple apps installed that use the same notification server do we allow the per app or per device management of the access?