AppWorks Notifications

JohnWilkinson

🕐️ 6 min read

What are AppWorks Notifications

The AppWorks Gateway provides a backchannel, which allows trusted servers to send messages to clients. Trusted servers call the notifications API with a secret key, a JSON message, and a list of users. Client containers receive these messages and pass them on to registered handler apps when a user clicks them. Schematically:

trusted server ? Gateway ? client runtimes ? notification handlers

Below, we will discuss three things:

1. How to send a custom notification from a trusted server.
2. How to register a custom notification handler for mobile clients.
3. How to register a custom notification handler for web clients.

Sending Notifications

A trusted server relationship is created by a Gateway administrator by generating a key on the Trusted Servers tab.

Your server can then send a notification to clients using this key:

POST /gateway/v2/notifications
Content-Type: application/x-www-form-urlencoded

key=<trusted server key>
message=<json string>
users=<comma-separated list of usernames>

The JSON object sent as the message can contain any custom fields you find useful, but should have the following standard fields:

{
    "type":<a string identifying notifications from your server>,
    "displayType":"show",
    "body":<the body of the message to the user>,
    "header":<the message header line>
}

Creating a Notification Handler (Mobile)

A notification handler is an HTML5 page which has, in app.properties, either

type=app

or

type=component

In either case, the handler must, like any AppWorks mobile app, contain a mobile.zip with an index.html in it (see here for an overview of creating an app). If type is 'component', the app icon will not appear on the launch screen.

To make your app or component handle notifications, include a file called component.properties in your mobile.zip. The file just needs a single line which lists the notification types to handle. For example, if your server will send notifications with "type"="mytype", then your component.properties should look like this:

notification=mytype

When your app or component is installed, and a user clicks on one of your notifications, your index.html will be loaded with two parameters in the URL query string. One will be action and have the value notification. The other will be data and its value will be the JSON string representing the notification. For example:

.../index.html?action=notification&data=<urlencoded json>

Creating a Notification Handler (Web)

When you create a tab in the Gateway common header (see here for an introduction and sample configuration file), you can specify a list of notification handlers in webaccess.json, in the “handlers” field. These are specified as urls. You may use any url here, but it is often useful to specify an url relative to your tab app, e.g.:

...
"handlers":[
    {"type":"mytype","url":"#/"}
]
...

When a user clicks on a notification of the registered type, the url will be loaded with an additional parameter called notificationJson, which will have the urlencoded json message as its value. For example, if your tab app is called myapp, the above configuration would result in a url like this:

/myapp#/?action=notification¬ificationJson=<urlencoded message>