search

sujrd / suj-pusher

Simple stand alone push notification server that supports APN and GCM services.
MIT License
2 stars 0 forks source link

readme

Suj Pusher Server

This is a simple pusher server that can push notifications to iOS and Android devices using the APN and GCM push services respectively.

NOTICE: This project is deprecated and no longer under development. With new services like AWS SNS and Google FCM this daemon is no longer relevant.

Features

Installation

Via gems simply install the suj-pusher gem on your system:

gem install suj-pusher

or download the source via git:

git clone https://github.com/sujrd/suj-pusher.git

after cloning the gem make sure to run bundle install to install the dependencies:

cd suj-pusher
bundle install

Usage

To run the server simply run the pusher daemon:

pusher start|start_nodetach|stop|restart|status  <options>

options:

The pusher daemon runs under the current user and current folder. If you specify the logid, piddir and certs folders make sure these exists and that the current user can create/write files inside those folder.

To start the server run:

/path/to/bin/pusher start -H localhost -P 6379 -b 0 -n pusher -p /var/run/pids

To start the server in nodetach mode (for supervisor):

/path/to/bin/pusher start_nodetach -H localhost -P 6379 -b 0 -n pusher

To stop the server run:

/path/to/bin/pusher stop -H localhost -P 6379 -b 0 -n pusher -p /var/run/pids

If you set a piddir (using -p option) when starting the server then you must supply the same option when stopping or restarting the server.

The certs option (-c) is to temporarily store APN certificates. These are deleted when the APN connection is closed.

Sending Notifications

Once the pusher daemon is running and connected to your redis server you can push notifications by publishing messages to redis. The message format is a simple JSON string.

JSON string format

Example JSON message:

{
  'apn_ids': ["xxxxx"],
  'gcm_ids': ["xxxxx", "yyyyyy"],
  'development': true,
  'cert': "cert string",
  'api_key': "secret key",
  'time_to_live': 0,
  'data': {
    'aps': {
      'alert': "This is a message"
    }
  }
}

Apple Certificate

Usually you get the Apple certificates and private key in a single p12 file. To extract the key needed to send push notifications you can use the following command:

openssl pkcs12 -in MyCert.p12 -out MyCert.key.pem -nocerts -nodes

the contents of the MyCert.key.pem is the one you need to set in the cert key on the hash. In ruby the following code can be used to generate the hash:

msg = {
  apn_ids: ["apns id"],
  development: false,
  cert: File.read("MyCert.key.pem"),
  data: {
    aps: {
      alert: "This is the message #{rand(100)}"
    }
  }

}

Apple aps hash

When sending push notifications to iOS devices you must provide an aps hash inside the data hash that follows the format:

"aps": { "alert": { "action-loc-key": "Open", "body": "Hello, world!" }, "badge": 2, "sound": "default" }

Read the official documentation for details on the aps hash format. Note that this hash must not exceed the 256 bytes or it will be rejected by the APN service.

Sending one message to WNS

message hash: { wnstype: "type" , wnsrequeststatus: true, wnsids: ["xxx"], secret: "app-secret", development: false, sid: "secret-id", data: "notif"} wnstype: type of the notification to send, posibles values are: "wns/badge", "wns/tile", "wns/toast", "wns/raw" data: a string with de notifiaction to send, please use the xml templates provided by Microsoft(http://msdn.microsoft.com/en-us/library/windows/apps/hh779725.aspx) for each wnstype listed above. secret and sid: App identification credentials provided by microsoft when registering a new application to use wns services. wnsrequeststatus: boolean, if true, the response from wns server will have aditional information wnsids: jsonArray of target devices.

Sending one message to WPNS

message hash: { wptype: "type", wpids: ["xxx"], secret: "unicId", development: false, wpnotificationclass: number, data: notif}

wptype: ype of the notification to send, posible values are: "toast" or "badge", if this parameter is not present, a "raw" type notifications will be sent. secret: a unic hash to identify a conection, internal use, each notification sent must have a diferent id wpids: jsonArray of ids for target devices
data: notification data to send, please use de xsml template provided by Microsoft(http://msdn.microsoft.com/en-us/library/windowsphone/develop/hh202945(v=vs.105).aspx) for each wptype listed above

Examples

A simple example using ruby code to send a push notification to iOS devices.

require 'multi_json'
require 'redis'

# Build a message hash
msg = {
  apn_ids: ["xxxxx"],
  development: true,
  cert: File.read(pemfile),
  data: {
    aps: {
      alert: "This is a message"
    }
  }
}

# Format the hash as a JSON string. We use multi_json gem for this but you are free to use any JSON encoder you want.
msg_json = MultiJson.dump(msg)

# Obtain a redis instance
redis = Redis.new({ host: "localhost", port: 6379})

# Push the message to the *suj_pusher_queue* in the redis server:
redis.lpush "pusher:suj_pusher_msgs", msg_json

Once you push the JSON message to the suj_pusher_msgs queue the pusher workers will retrieve and process it.

Issues

Troubleshooting