https://github.com/adorsys/notification-service
notification-service
https://github.com/adorsys/notification-service
Last synced: 6 months ago
JSON representation
notification-service
- Host: GitHub
- URL: https://github.com/adorsys/notification-service
- Owner: adorsys
- License: mit
- Created: 2018-06-22T13:59:15.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2022-12-11T14:00:01.000Z (almost 3 years ago)
- Last Synced: 2024-04-14T12:53:55.032Z (over 1 year ago)
- Language: JavaScript
- Size: 548 KB
- Stars: 5
- Watchers: 8
- Forks: 4
- Open Issues: 14
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Notification-server
Notification-server is a ready to use push notification server supporting multi-session and authentication. It was built using [Node.js](https://nodejs.org) and [Socket.IO](http://socket.io/). The main purpose of notification-server is to provide an **easy**, **stable** and **secure** solution which can be used to send push notifications to a client application.
## Version
1.0.0
## Features
* support for old browsers which do not support WebSockets
* REST JSON API
* authentication to API and push notification channels
* supports multi-session where the same user can be connected to the notification server from many applications and tabs at the same time
* easy to run
* easy to use
## How to run it
### Docker
#### Build the container
```sh
docker build -t notification-server .
```
#### Run the container
```sh
docker run -d -p 3000:3000 \
--name notification-server \
-e "AUTH_TOKEN=" \
notification-server:latest
```
> IMPORTANT:
> <secret> - has to be changed into a secure token which will be used as an
> authentication token to notification-server API from your backend application.
### Manual installation
* install Node.js and npm
* fetch the git repository
```sh
git clone https://github.com/adorsys/notification-service.git
```
* install app dependencies using npm
```sh
npm install
```
* set env variable with the authentication token - this token will be used to secure access to REST API
```sh
export AUTH_TOKEN=your_secret
```
* run the server
```sh
npm start
```
## Is it working
Open the ```/api/status/info``` page, e.g. ```http//localhost:3000/api/status/info``` and the application should display the name and current version of the server.
## How to use it
We recommend that it is used in the following way but of course it can be modified :)
### Register a client app
> IMPORTANT:
> each request from your backend to notification-server has to be authenticated by a
> HEADER X-AUTH-TOKEN with the same value as the env variable AUTH_TOKEN of notification-server
1. 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 generates a random `connectionId` - it should be unique and secure - we recommend UUID
3. Your backend app registers the user in notification-server executing the method:
```PUT /api/{userId}/register?connectionId={connectionId} with X-AUTH-TOKEN header```
> IMPORTANT
> where userId is the unique id of your user in your application we will use the
> userId in the future to send one push notification to all clients of this user
4. Your backend app returns `connectionId` and `url` to notification-server to client app
5. Client app connects and authenticates to notification-server (using socket.io lib):
```js
var socket = io.connect(notificationSocketIo.url);
socket.on('connect', function() {
socket.emit('register', userId, notificationSocketIo.connectionId);
});
```
6. Register client apps which are to receive push notifications. Use socket.io to listen to messages with an identifier `message`:
```js
socket.on('message', function(msg) {
//handle your message
});
```
### Send a push notification
1. When your backend application wants to send a push notification to a client just execute:
```POST /api/{userId}/push with X-AUTH-TOKEN header```
and send the content of the push notification message, format of message {"message": message_json}, e.g.
```json
{
"message": {
"title":"Title of message",
"body": "Body of message",
"params": {}
}
}
```
2. Client app will receive a push notification in callback registered in step 6
### Disconnect
1. To stop receiving push notifications your client app has to execute:
```js
socket.emit('disconnect')
```
## 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 `e.g. /api/{userId}/register` and `/api/{userId}/push` requires this header. The token has to have the same value as the env variable `AUTH_TOKEN` of notification-server.
### Access to the push notification channel
The first thing a client application has to do after connecting is to register in notification-server. In order to do this it has to use the `connectionId` generated by the backend. Only registered applications will receive push notifications.
## Monitoring
You can execute `GET /api/status/ping` to check if the application is live.
You can execute `GET /api/status/info` to obtain the application's version.