AeroGear UnifiedPush Server

The AeroGear UnifiedPush Server is a server that allows sending native push messages to different mobile operation systems. The initial version of the server supports Apple’s APNs, Google Cloud Messaging and Mozilla’s Simple Push.

Motivation / Purpose

The AeroGear UnifiedPush Server offers a Notification Service API to different backend applications. This gives a server the ability to send Push Notifications to mobile applications. The Notification Service API is a signalling mechanism, like Apple APNs, Google Cloud Messaging or Mozilla SimplePush for sending messages. It’s not suitable to be used as a data carrying system (e.g. use in a chat application).

Some Usage Scenarios

  • MyWarehouseInc-backend can send “notification messages” to different “customer” groups (e.g. discounts for only iOS (or only Android) users).
  • MyInsuranceCorp-backend can send “notification messages” to different variants of its mobile Applications:
    • App for the Customers
    • App for the employed Sales Agents
  • Publishing Company:
    • MyPublishing-Company-backend sends update “notification messages” to all of its apps (free and premium - regardless of the mobile OS).
    • The arrival of “advanced content” is only notified to the paying customers (e.g. those that run the premium app).
  • A company has different backends (small/simple apps for different tasks) - and these different backends could be able to reach all (or some) of the company’s mobile apps.

Goal: To make any (JBoss/AeroGear powered) mobile application, that is backed by JBoss technology (e.g. admin console, Errai, drools, etc.), work easily with mobile push messages. For a JBoss “backend application” it should be as simple as possible to send messages to its different mobile clients.

Definitions

Before we get into details, it’s important that we have a good lexicon.

Push Application

A logical construct that represents an overall mobile application (e.g. Mobile HR).

Variant

A variant of the Push Application. There can be multiple variants for a Push Application (e.g. HR Android, HR iPad, HR iPhone free, HR iPhone premium or HR Mobile Web). A Variant contains platform specific properties, such as a Google API key (Android) or a PushNetwork URL (SimplePush).

Installation

Represents an actual installation on a mobile device / client (e.g. User1 connected via MobileWeb or User2 runs HR iPhone premium on his phone)

(Push) Notification Message

A simple message to be send to a mobile application, to notify it of a data change.

Sender API

Is a component that sends Push Notification Messages to a Push Application or some of its different Variants.

Developer

A Developer is in charge of enabling Push Notifications for his different backend systems. For that he has to create a Push Application and one or more Variants on the AeroGear UnifiedPush Server.

A Developer will use the Sender API to send “notification messages” to different Installations.

User

A user of an AeroGear Installation, which may consume notification messages.

Overview

The AeroGear UnifiedPush Server contains three different components:

  • Registration: Registry for Push Applications, Variants and Installations
  • Storage: A database, storing the registered applications and installations
  • Sender: Receives messages and sends them to different Installations

The graphic below gives a little overview:

components

Functionality

Registration

Three different registration types are provided by the AeroGear UnifiedPush Server.

Push Application Registration

Adds a logical construct, that represents an overall mobile application (e.g. Mobile HR). The Push Application contains the following properties:

  • Name
  • Description
  • A collection of Variants

The server offers an HTTP interfaces to apply a Push Application registration:

curl -3 -v -b cookies.txt -c cookies.txt
     -v -H "Accept: application/json" -H "Content-type: application/json"
     -X POST
     -d '{"name" : "MyApp", "description" :  "awesome app" }'

https://SERVER:PORT/context/rest/applications

The response returns a JSON map, representing the Push Application.

Variant Registration

Adds a variant for an existing Push Application. There can be multiple variants for a Push Application (e.g. HR Android, HR iPad, HR iPhone free, HR iPhone premium or HR Mobile Web).

The server supports the following variant types:

  • iOS
  • Android
  • SimplePush
iOS Variant

An iOS variant represents a logical construct for one iOS application (e.g. HR for iPhone or HR for iPad ). The iOS variant requires some APNs specific values:

  • APNs Push Certificate file
  • Passphrase

The server offers an HTTP interfaces to register an iOS variant:

curl -3 -v -b cookies.txt -c cookies.txt 
     -i -H "Accept: application/json" -H "Content-type: multipart/form-data" 
     -F "certificate=@/path/to/the/cert.p12"
     -F "passphrase=TopSecret"
     -F "description=An iPhone variant"
     -F "name=HR for iPhone"
     -X POST

https://SERVER:PORT/context/rest/applications/{pushApplicationID}/iOS

NOTE: The above is a multipart/form-data, since it is required to upload the “Apple Push certificate”!

The response returns a JSON map, representing the iOS variant.

Android Variant

An Android variant represents a logical construct for one Android application (e.g. HR for Android). The Android variant requires some Google specific values:

  • Google API Key
  • Google Project Number / Sender ID (optional)

The server offers an HTTP interfaces to register an Android variant:

curl -3 -v -H "Accept: application/json" -H "Content-type: application/json"
 -X POST
 -d '{"googleKey" : "My Google API Key","projectNumber":"My Project Number / Sender ID", "name" : "HR for Android", "description" :  "Android variant" }'
  
 https://SERVER:PORT/context/rest/applications/{pushApplicationID}/android

The response returns a JSON map, representing the Android variant.

SimplePush Variant

An SimplePush variant represents a logical construct for one SimplePush application (e.g. HR mobile Web). The SimplePush variant requires some Simple Push Network specific values:

  • URL of the PushNetwork server

The server offers an HTTP interfaces to register an SimplePush variant:

curl -3 -v -H "Accept: application/json" -H "Content-type: application/json"
  -X POST
  -d '{"name" : "HR mobile Web", "description" :  "SimplePush variant" }'

  https://SERVER:PORT/context/rest/applications/{pushApplicationID}/simplePush 

The response returns a JSON map, representing the SimplePush variant.

Installation Registration

Supported by Client SDKs: Adds an installation to an existing variant (e.g. User1 runs HR-iPad on his device). It is possible that one user can have multiple devices. An installation contains the following properties:

Required Data
  • deviceToken

Identifies the device/user-agent within its Push Network.

  • variantID

The ID of the variant, where the client belongs to.

  • variantSecret

Password of the actual variant.

Optional Data
  • deviceType:

The device type of the device or the user agent.

  • operatingSystem:

The name of the underlying Operating System.

  • osVersion:

The version of the used Operating System.

  • alias:

Application specific alias to identify users with the system. For instance an email address or a username.

  • categories:

Used to apply one or more “tags” for the registered Installation.

  • simplePushEndpoint:

SimplePush server endpoint which receives update requests for one SimplePush client/channel.

REST APIs

The server offers an HTTP interfaces to register an installation:

curl -3 -u "{MobileVariantID}:{secret}"
    -v -H "Accept: application/json" -H "Content-type: application/json" 
    -X POST
    -d '{
      "deviceToken" : "someTokenString",
      "deviceType" : "iPad",
      "operatingSystem" : "iOS",
      "osVersion" : "6.1.2",
      "alias" : "someUsername or email adress...",
      "categories" : ["football", "sport"],
      "simplePushEndpoint" : "http://server.com/someEndpoint"
     }'

https://SERVER:PORT/context/rest/registry/device

NOTE: Platform specific Client SDKs are provided to submit the require data to the AeroGear UnifiedPush Server.

Sender

The RESTful APIs for sending Push Notifications to different Mobile Push Networks:

RESTful Sender

Sends a push message to a selected list of devices/clients, or all, based on different query criterias:

curl -3 -u "{PushApplicationID}:{MasterSecret}"
     -v -H "Accept: application/json" -H "Content-type: application/json" 
     -X POST
   -d '{
       "variants" : ["c3f0a94f-48de-4b77-a08e-68114460857e", "444939cd-ae63-4ce1-96a4-de74b77e3737" ....],
       "alias" : ["user@account.com", "someone@aerogear.org", ....],
       "categories" : ["someCategory", "otherCategory"],
       "deviceType" : ["iPad", "AndroidTablet"],
       "ttl" : 3600,
       "message": {
           "alert":"HELLO!",
           "sound":"default",
           "badge":7,
           "content-available" : true,
           "someKey":"some value",
           "anotherCustomKey":"some other value"
       },
       "simple-push": "version=123"
    }'

https://SERVER:PORT/context/rest/sender

The variants is a filter for notifying certain variants (e.g. HR Android, HR iPad etc.) of the PushApplication with the respective IDs. The alias value is used to identify the desired users, while the categories is more a semantical tag, of a registered Installation. The deviceType is a filter for notifying only users, running a certain device. The ttl is supported on GCM/APNs to specify how long the supported networks should try to deliver the notification. The payload (message and simple-push) are standard JSON objects. If platform specific key words (e.g. alert for APNs) are used, they are honored for the specific platform. This transformation is done by the AeroGear UnifiedPush Server.

Use Cases

Below are the BASIC use-cases, that the AeroGear UnifiedPush Server needs to initially support.

  • Enroll Developer
  • Remove Developer
  • Developer can register a Push Application
    • Developer can add a Variant for different operation systems
    • Developer can remove a Variant
  • Developer can remove Push Application
  • User registers his Installation
  • User unregisters his Installation (e.g. app got deinstalled, user deleted etc)
  • User receives Push Notification Messages (handled by the native OS, once accepted to receive messages)
  • Developer send Push Notification Messages
  • Developer can disable Push Notifications to selected Installations.

Enroll

Developer

The Developer role is always registered with the AeroGear UnifiedPush Server and a username/password combination is required.

User

Not all mobile applications define the concept of a registered user (e.g. Sport Broadcast apps), but others do (e.g. Twitter). The User is never registered with the AeroGear UnifiedPush Server. The User lives in the Business Database. In cases where the mobile app requires a User, it is highly recommend to register an alias with the Installation.

Remove

Developer

It should be possible to remove Developers from the Server.

User

It should be possible to remove a Installation, so that it can no longer receive Push Notification Messages.

Register Push Applications

A Developer can register multiple Push Applications. Each Push Application can have several Variants.

Add Variant

A Developer can add a Variant to an existing Push Application.

Remove Push Application

A Developer should be able to remove a Push Application (including its Variant).

Remove Variant

A Developer should be able to remove a Variant, of an existing Push Application.

Installation Registration

The mobile application needs to send his device-token (and some more metadata) to the AeroGear UnifiedPush Server, in order to be able to receive Push Notification Messages.

Remove Installation

uninstall

If an app gets uninstalled, the phone is no longer able to receive push messages. Therefore inactive Installation 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. They are ignored by the actual Push Networks.

access removed

Admin can disable push notifications for a specific Installation.

Receives Push Notification Messages

Every installed app, is able to receive Push Notification Messages through the APIs, offered by the platforms (iOS, Android, SimplePush).

Note: On iOS the user as to agree to receive push messages

Sending Push Notification Messages

Sender

The AeroGear UnifiedPush Server acts as a broker to deliver Push Notification Messages to several Installations. A developer can send Push Notification Messages to a specific Installations, using query criterias, such as alias or deviceType, or all (aka broadcast) when no criteria is provided.

API access

PushApplications and Variants

The AeroGear Security Module is used to secure the endpoints for:

  • Working with PushApplications
  • Working with Variants

Installation Registration API

HTTP Basic is used to secure the endpoint. Credentials: variantID:variantSecret

Sender API

HTTP Basic is used to secure the endpoint. Credentials: pushApplicationID:masterSecret

Client SDK / API

The Client SDKs for Installation Registration are tracked here