Location: Home / Documentation / Using Uniqush Language: en

Using Uniqush

This document describes how to use Uniqush by sending HTTP POST request to uniqush-push. Please make sure you understand Basic Operations Provided by Uniqush. Parameters of a request should be properly URL encoded. We will use curl to show some examples.

Before executing any command below, make sure you have already started uniqush-push. It will be under /usr/bin directory if you installed Uniqush from official binary files.

NOTE: uniqush-push is only a server side program. You need to use the native client code for each platform. For more information on how to support push notification on client side, please look at the corresponding documents for each platform:


Get the Version of uniqush-push


Stop uniqush-push

NOTE: You need to stop the program or it may not synchronize the cache with the database.


Adding Push Service Provider

Parameters for GCM Push Service Provider

Parameter Description
service Service Name
pushservicetype For GCM Push Service Provider, this is always gcm
projectid Project ID.
apikey API Key

Read this article on how to get Project ID and API key. Note: you need to make a Server key not an Android key.

Example: curl http://127.0.0.1:9898/addpsp -d service=myservice -d pushservicetype=gcm -d projectid=123 -d apikey=somekey

Parameters for APNS Push Service Provider

Parameter Description
service Service Name
pushservicetype For APNS Push Service Provider, this is always apns
cert The absolute path to the certificate file in .pem format
key The absolute path to the private key file in .pem format
sandbox Optional. true for sandbox; otherwise for production environment

Example: curl http://127.0.0.1:9898/addpsp -d service=myservice -d pushservicetype=apns -d cert=/path/to/certificate.pem -d key=/path/to/privatekey.pem -d sandbox=true

See this blog for details how to acquire the PEM files (certificate and private key).

Parameters for ADM Push Service Provider

Parameter Description
service Service Name
pushservicetype For ADM Push Service Provider, this is always adm
clientid The Client ID.
clientsecret The Client Secret.

To obtain the Client ID and Client Scret:

Here is an example of a Client ID: amzn1.iba-client.b2b360f8a77d457981625636121d6edf

Here is an example of a Client Secret: c559965801308f2bb79ca787b1dfc8deece8a2fd7d7618946cec1635d26dcbfb

NOTE: The method mentioned above may be changed. Please refer to the Document from Amazon for more details.

Example: curl http://127.0.0.1:9898/addpsp -d service=myservice -d clientid=someClientId -d clientsecret=ClientSecret -d pushservicetype=adm


Removing Push Service Provider

Parameters for GCM Push Service Provider

Parameter Description
service Service Name
pushservicetype For GCM Push Service Provider, this is always gcm
projectid Project ID.

Read this article on how to get Project ID and API key.

Example: curl http://127.0.0.1:9898/rmpsp -d service=myservice -d pushservicetype=gcm -d projectid=123

Parameters for APNS Push Service Provider

Parameter Description
service Service Name
pushservicetype For APNS Push Service Provider, this is always apns
cert The absolute path to the certificate file in .pem format
key The absolute path to the private key file in .pem format

Example: curl http://127.0.0.1:9898/rmpsp -d service=myservice -d pushservicetype=apns -d cert=/path/to/certificate.pem -d key=/path/to/privatekey.pem

Parameters for ADM Push Service Provider

Parameter Description
service Service Name
pushservicetype For ADM Push Service Provider, this is always adm
clientid The Client ID.
clientsecret The Client Secret.

To obtain the Client ID and Client Scret:

Here is an example of a Client ID: amzn1.iba-client.b2b360f8a77d457981625636121d6edf

Here is an example of a Client Secret: c559965801308f2bb79ca787b1dfc8deece8a2fd7d7618946cec1635d26dcbfb

NOTE: The method mentioned above may be changed. Please refer to the Document from Amazon for more details.

Example: curl http://127.0.0.1:9898/addpsp -d service=myservice -d clientid=someClientId -d clientsecret=ClientSecret -d pushservicetype=adm


Subscribe

Parameters for Android Devices Using GCM

Parameter Description
service Service Name
subscriber Subscriber ID
pushservicetype For Android Device using GCM, this is always gcm
regid Registration ID

Example: curl http://127.0.0.1:9898/subscribe -d service=myservice -d subscriber=uniqush.client -d pushservicetype=gcm -d regid=fakeregid

Parameters for iOS Devices Using APNS

Parameter Description
service Service Name
subscriber Subscriber ID
pushservicetype For iOS device using APNS, this is always apns
devtoken Device token

Example: curl http://127.0.0.1:9898/subscribe -d service=myservice -d subscriber=uniqush.client -d pushservicetype=apns -d devtoken=some-device-token

Parameters for Kindle Devices Using ADM

Parameter Description
service Service Name
subscriber Subscriber ID
pushservicetype For Kindle Device using ADM, this is always adm
regid Registration ID

Example: curl http://127.0.0.1:9898/subscribe -d service=myservice -d pushservicetype=adm -d subscriber=firehd -d regid=RegistrationId


Unsubscribe

Parameters for Android Devices Using GCM

Parameter Description
service Service Name
subscriber Subscriber ID
pushservicetype For Android Device using GCM, this is always gcm
regid Registration ID. NOTE: This registration ID must be exactly the same one used to subscribe.

Example: curl http://127.0.0.1:9898/unsubscribe -d service=myservice -d subscriber=uniqush.client -d pushservicetype=gcm -d regid=fakeregid

The registration ID should be same one used to subscribe the service. That is: you don’t need to consider if the GCM will update the registration ID for the device. Uniqush can handle it.

Parameters for iOS Devices Using APNS

Parameter Description
service Service Name
subscriber Subscriber ID
pushservicetype For iOS device using APNS, this is always apns
devtoken Device token

Example: curl http://127.0.0.1:9898/unsubscribe -d service=myservice -d subscriber=uniqush.client -d pushservicetype=apns -d devtoken=devtoken

Parameters for Kindle Devices Using ADM

Parameter Description
service Service Name
subscriber Subscriber ID
pushservicetype For Kindle Device using ADM, this is always adm
regid Registration ID

Example: curl http://127.0.0.1:9898/subscribe -d service=myservice -d pushservicetype=adm -d subscriber=firehd -d regid=RegistrationId

Get Subscriptions

Parameters for getting subscriptions for a set of service names

Parameter Description
services Service Name(s)
subscriber Subscriber ID

Example: curl http://127.0.0.1:9898/subscriptions -d services=myservice,myotherservice -d subscriber=uniqush.client

Parameters for getting subscriptions across each service

Parameter Description
subscriber Subscriber ID

Example: curl http://127.0.0.1:9898/subscriptions -d subscriber=uniqush.client

If this fails to return results for some valid services, then use the /rebuildserviceset API.

Get PSPs

Returns JSON representing the PSPs stored in Uniqush, along with their configs (API keys, paths to certificates, service type, etc.).

Migrating from 1.0 to 2.0

Initializes the set of all service names. This API is needed for the /subscriptions and the /psps APIs to work(and be efficient).


Push Message

Parameters

Parameter Description
service Service Name.
subscriber Subscriber ID. Could be more than one subscriber. Comma separated. Asterisk (*) could be used as a wildcard to match any string
msg Optional. Message Body
ttl Optional. Time to live. How long (in seconds) the message should be kept on push service provider’s server if the device is offline
badge Optional. Badge
img Optional. Image
sound Optional. Sound
loc-key Optional. loc-key for APNS
loc-args Optional. loc-args for APNS. It is a comma-separated string.
action-loc-key Option. action-loc-key for APNS.
Reserved Parameter Any parameter whose name starts with “uniqush.” is reserved by Uniqush. Users should avoid using those parameter names.
User Defined Parameter Optional. Any other parameter is accepted which will be sent to mobile devices

At least one of the optional parameter should be provided, or it will be an empty message and won’t be sent.

For android and kindle client, the message will be received as Intent containing key-value pairs. msg, badge, img, sound, loc-key, loc-args and User Defined Parameters will be put as key-value pairs in the Intent. You can use getExtras() method of the Intent to get all key-value pairs.

For iOS client, the notification is sent as JSON encoded message to APNS. All parameters are mapped to their corresponding place as follows:

Parameter Mapped To
msg “aps” > “alert” > “body”
badge “aps” > “badge”
img “aps” > “alert” > “launch-image”
sound “aps” > “sound”
loc-key “aps” > “alert” > “loc-key”
loc-args “aps” > “alert” > “loc-args”
action-loc-key “aps” > “alert” > “action-loc-key”
content-available “aps” > “content-available”

For user defined parameters, they are key-value pairs in the same hash table with “aps”.

Examples:


Getting The Number of Delivery Points for a Subscriber to a Service

Parameters for getting the number of delivery points

Parameter Description
service Service Name
subscriber Subscriber ID

Example: curl http://127.0.0.1:9898/nrdp -d service=myservice -d subscriber=uniqush.client