netbulls/notification-server repository overview

⁠Notification-Server

Notification-server is a server which enables sending push notifications in a unified and safe way to client applications and internet browsers. The server uses communication channels native to all supported platforms, such as GCM, APNS, MPNS, etc. Because every channel has a different API and different capabilities our server translates notifications into a format supported by the target communication channel. Thanks to the use of native communication channels our server is completely free. The only thing that must be done is: complete a proper registration with the provider, gain access data of an external push notification service, then configure the notification-server with that data and start sending notifications.

Notification-server is persistent so every notification sent is saved in the database and can be downloaded/read/deleted at any moment.

⁠Version

2.1.0

⁠Supported platforms:

• GCM
• APNS
• MPNS
• socket.io

⁠Features

• unified API
• secure
• persistent
• history of notifications with the option to read and delete
• support for old browsers which do not support WebSockets
• REST JSON API
• Well documented REST API with Swagger

⁠Installation

⁠MongoDB

The server uses Mongodb for storing notification server details. Mongo installation is described here link⁠. You can also use docker (recommended) to install MongoDB

docker run ­d ­p 27017:27017 \
­­  name mongodb3 \
  ­­hostname=mongodb \
  -­v /opt/mongodb3/data/db:/data/db \
  mongo:3

⁠Logs

Logs from the application are stored in the /var/log/notification-server directory. You should create the directory and give the deamon user permissions to access it. Default login level for application logs is INFO.

⁠notification-socket.io (optional)

If you wish to have support for push notification via socket.io you have to install our other product, notification-socket.io, which provides secure socket.io server wrapping.

Installation is described here https://github.com/netbulls/notification-socket.io⁠

⁠Configuration

Configuration of the Notification server is stored in the production.conf file which is in the HOCON format.

⁠Global settings

# Public (external) url to application without "/" at the end, 
# e.g. http://notificotion-server-example.io
application.publicUrl = "http://notification-server.netbulls.io"

# Database url, in format mongodb://user:passoword@host:port/database
mongodb.uri = "mongodb://mongodb3:27017/notification-server"

# Key required by swagger to display information about API. 
# Swagger is disabled if the key has less than 5 characters.
swagger.accessKey = ""

# Authentication token to API must have at least 8 chars
security.authToken = ""

⁠APN settings (optional – only if you want to use APNS)

# Path to keystore with certificate - if empty then APN will be disabled.
apn.keystore.path = ""

# Password to keystore with certificate - if empty then APN will be disabled.
apn.keystore.password = ""

# If use PRODUCTION or SANDBOX account
apn.production = false

# Size of THREAD POOL to communication
apn.threadPool.size = 100

⁠GCM settings (optional – only if you want to use GCM)

# API key to GCM - if empty then GCM will be disabled.
gcm.apiKey = ""

# Name of icon using in push notification.
gcm.icon = ""

⁠notification-socket.io (optional – only if you want to use socket.io)

# Url to socker.io server, without "/" at the end
# if empty then socket.io will be disabled.
socketio.url = ""

# Authentication token to socket.io server.
socketio.authToken = ""

⁠MPNS settings (optional – only if you want to use MPNS)

# Should the MPNS be enabled or disabled
mpns.enabled = false

⁠Running the notification server

⁠Docker

We prefer the docker solution so the following command must be run:

docker run -d -p 80:9000 \
  --name notification-server \
  --hostname=`hostname` \
  --link mongodb3:mongodb3 \
  -v `pwd`/production.conf:/opt/docker/conf/production.conf \
  -v /var/log/notification-server/:/var/log/notification-server/ \
  netbulls/notification-server:1.1.0

⁠Docker with APNS support

A catalog must be created into which the APNS certificate file is placed (only certificates from the keystore in the PKCS12 format and protected by a password are supported). Next run docker mounted with the catalog with the certificate.

docker run -d -p 80:9000 \
  --name notification-server \
  --hostname=`hostname` \
  --link mongodb3:mongodb3 \
  -v `pwd`/production.conf:/opt/docker/conf/production.conf \
  -v /var/log/notification-server/:/var/log/notification-server/ \
  -v `pwd`/certs:/opt/docker/conf/certs/ \
  netbulls/notification-server:1.1.0

⁠Is it working?

Just open the /api/status/info page, e.g. http//localhost/api/status/info, application should display name, current version, MongoDB status connection as well as the status of individual push services.

⁠How to use it?

We recommend that it is used in the following way but of course it can be modified : )

IMPORTANT
All REST API documentation with JSON object details are available from Swagger. 
You can access it through 
http://notification_server_address/swagger?key=accessKey 
where accessKey is the value of property swagger.accessKey defined in the 
production.conf file.

IMPORTANT
Each request from your backend to the notification-server has to be 
authenticated by header X-AUTH-TOKEN with the same value that was 
specified for security.authToken property in production.conf file

⁠Registering a client app

⁠Mobile apps

1. Client application registers in the push service corresponding to the device's operating system.

2. The received token (or in the case of MPSN - URI) is sent to your backend which in turn forwards it to the notification-server (the backend does not have to remember any of these tokens because everything is saved on the side of the notification-server). The backend, depending on the type of the push service, must use different APIs to register the token.

   POST /api/v1/users/{userId}/gcm with body {'token': 'token'}
   POST /api/v1/users/{userId}/apn with body {'token': 'token'}
   POST /api/v1/users/{userId}/mpns with body {'uri': 'uri'}
   

   Copy

⁠Web application (via socket.io)

1. The client app asks your backend about the connection data of the push notification channel (in most cases it will be executed after a successful authentication)

2. Your backend app registers the user in the notification-server executing the method: PUT /api/v1/users/{userId}/socket.io and as an answer receives a notification-socket.io server address and a connectionId which will be used to authenticate the client application.

3. The backend sends an answer to the browser with a connectionId and url to the notification-socket.io obtained from the server.

4. Client app connects and authenticates to notification-socket.io (using socket.io lib):

   var socket = io.connect(notificationSocketIo.url);
   socket.on('connect', function() {
       socket.emit('register', userId, notificationSocketIo.connectionId);
   });
   

   Copy

5. Register the client app to receive push notifications. Use socket.io to listen to messages using the identifier message:

   socket.on('message', function(msg) {
        //handle your message
   });
   

   Copy

⁠Sending a push notifications

1. Your backend wants to send the push notification to all user applications with an id {userId}. To do this it must run:

   POST /api/v1/users/{userId}/notification with a body:
   {
     "id": "notification_identifier",
     "type": "notification_type",
     "persist": false,
     "title": "title",
     "body": "body",
     "params": [
       {
         "name": "param1",
         "value": "value1"
       }
      ]
    }
   

   Copy

   IMPORTANT
   All JSON model fields are described in Swagger documentation. 
   Next the notification-server saves this notification in the 
   data base (if the parameter persist was set to true) with the 
   "read" flag set to false.
   

   Copy

2. Notification-server sends notifications to all user apps using native communication channels.

   IMPORTANT
   All registered notification channels for a user are collected 
   and held by the notification server. Thanks to this the 
   backend needs to use only one method to send notifications 
   to the user through all registered channels.
   

   Copy

⁠Removing notification channels

Every mobile notification channel can be removed from the notification server. This is possible by executing the api method related to the push service:

DELETE /api/v1/users/{userId}/gcm/{token}  with X-AUTH-TOKEN
DELETE /api/v1/users/{userId}/apn/{token}  with X-AUTH-TOKEN
DELETE /api/v1/users/{userId}/mpns/{uir}  with X-AUTH-TOKEN

The socket.io channel will be removed automatically after disconnecting from the web application or by executing function:

socket.emit('disconnect')

⁠Managing notifications

Notifications can be stored in the database. You may notice that it is possible to check notifications as persistent when sending to the user:

{
    ...
    "persist": true,
    ...
}

The notification server allows access to saved notifications through the API.

Get all user notifications

GET /api/v1/users/{userId}/notifications

Get the number of user notifications (you can count all, read or unread messages)

GET /api/v1/users/{userId}/notifications/count

Mark notification as read:

PUT /api/v1/users/{userId}/notifications/{notificationId}/read

Or delete them:

DELETE /api/v1/users/{userId}/notifications/{notificationId}

⁠Database indexes

We are currently working on this. Contact us if you need this solution.

⁠Clustering

If the need arises the system can also be activated in a cluster and the database can be sharded. The instructions on how to do this will be prepared soon. Write to us if you need this solution now.

⁠Security

⁠Access to api

There is a simple mechanism using X-AUTH-TOKEN header to authenticate your application in notification server. Each request from your backend needs this header.The token has to have the same value that was specified for security.authToken property in the production.conf file.

⁠Access to Swagger

To access Swagger documentation you need to provide accessKey with the value of swagger.accessKey property defined in the production.conf file. e.g. http://notification_server_address/swagger?key=accessKey

⁠License

Notification-server can be used without any limitations in any type of a project, including commercial ones.

⁠Contact

If you have any suggestions as to how our product could be improved, have questions or need more customized solutions write to the address [email protected]⁠.