gorush/README.md

Gopush

A push notification server using Gin framework written in Go (Golang).

Support Platform

• APNS
• GCM

Feature

• Support Google Cloud Message using go-gcm library for Android.
• Support HTTP/2 Apple Push Notification Service using apns2 library.
• Support YAML configuration.
• Support command line to send single Android or iOS notification.
• Support Web API to send push notification.
• Support zero downtime restarts for go servers using endless.
• Support HTTP/2 or HTTP/1.1 protocol.

See the YAML config example:

core:
  port: "8088"
  max_notification: 100
  mode: "release"
  ssl: false
  cert_path: "cert.pem"
  key_path: "key.pem"

api:
  push_uri: "/api/push"
  stat_go_uri: "/api/status"

android:
  enabled: true
  apikey: "YOUR_API_KEY"

ios:
  enabled: false
  pem_cert_path: "cert.pem"
  pem_key_path: "key.pem"
  production: false

log:
  format: "string" # string or json
  access_log: "stdout" # stdout: output to console, or define log path like "log/access_log"
  access_level: "debug"
  error_log: "stderr" # stderr: output to console, or define log path like "log/error_log"
  error_level: "error"

Basic Usage

How to send push notification using gopush command? (Android or iOS)

Download a binary

The pre-compiled binaries can be downloaded from release page.

Send Android notification

Send single notification with the following command.

$ gopush -android -m="your message" -k="API Key" -t="Device token"

• -m: Notification message.
• -k: Google cloud message api key
• -t: Device token.

Send iOS notification

Send single notification with the following command.

$ gopush -ios -m="your message" -i="API Key" -t="Device token"

• -m: Notification message.
• -i: Apple Push Notification Certificate path (pem file).
• -t: Device token.

The default endpoint is APNs development. Please add -production flag for APNs production push endpoint.

$ gopush -ios -m="your message" -i="API Key" -t="Device token" -production

Run gopush web server

Please make sure your config.yml exist. Default port is 8088.

$ gopush -c config.yml

Test status of api server using httpie tool:

$ http -v --verify=no --json GET https://localhost:8088/api/status

Run gopush in Docker

Set up gopush in the cloud in under 5 minutes with zero knowledge of Golang or Linux shell using our gopush Docker image.

$ docker pull appleboy/gopush
$ docker run -name gopush -p 80:8088 appleboy/gopush

Testing your gopush server.

$ http -v --verify=no --json GET http://your.docker.host/api/status

Web API

Gopush support the following API.

• GET /api/status Golang cpu, memory, gc, etc information. Thanks for golang-stats-api-handler.
• POST /api/push push ios and android notifications.

POST /api/push

Simple send iOS notification example, the platform value is 1:

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!"
    }
  ]
}

Simple send Android notification example, the platform value is 2:

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!"
    }
  ]
}

Send multiple notifications as below:

{
  "notifications": [
    {
      "tokens": ["token_a", "token_b"],
      "platform": 1,
      "message": "Hello World iOS!"
    },
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World Android!"
    },
    {
      "tokens": ["token_a", "token_b"],
      "platform": 2,
      "message": "Hello World!"
    },
    .....
  ]
}

Request body must has a notifications array. The following is a parameter table for each notification.

name	type	description	required	note
tokens	string array	device tokens	o
platform	int	platform(iOS,Android)	o	1=iOS, 2=Android
message	string	message for notification	o
priority	string	Sets the priority of the message.	-
content_available	bool	data messages wake the app by default.	-
api_key	string	Android api key	-	only Android
to	string	The value must be a registration token, notification key, or topic.	-	only Android
collapse_key	string	a key for collapsing notifications	-	only Android
delay_while_idle	bool	a flag for device idling	-	only Android
time_to_live	int	expiration of message kept on GCM storage	-	only Android
restricted_package_name	string	the package name of the application	-	only Android
dry_run	bool	allows developers to test a request without actually sending a message	-	only Android
data	string array	data payload of a GCM message	-	only Android
notification	string array	payload of a GCM message	-	only Android
expiration	int	expiration for notification	-	only iOS
apns_id	string	A canonical UUID that identifies the notification	-	only iOS
topic	string	topic of the remote notification	-	only iOS
badge	int	badge count	-	only iOS
sound	string	sound type	-	only iOS
category	string	the UIMutableUserNotificationCategory object	-	only iOS
extend	string array	extensible partition	-	only iOS
alert	string array	payload of a iOS message	-	only iOS

License

Copyright 2016 Bo-Yi Wu @appleboy.

Licensed under the MIT License.