Location: Home / Documentation / Using Uniqush

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 link on how to get a 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 FCM Push Service Provider

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

Read this link on how to get a 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=fcm -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 Secret:

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.
apikey API Key

Read this link for how to get a 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 FCM Push Service Provider

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

Read this link for how to get a Project ID and API key.

Example: curl http://127.0.0.1:9898/rmpsp -d service=myservice -d pushservicetype=fcm -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 Secret:

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 Android Devices Using FCM

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

Example: curl http://127.0.0.1:9898/subscribe -d service=myservice -d subscriber=uniqush.client -d pushservicetype=fcm -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 Android Devices Using FCM

Parameter Description
service Service Name
subscriber Subscriber ID
pushservicetype For Android Device using FCM, this is always fcm
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=fcm -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 FCM 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 (not recommended for large lists of subscribers for performance reasons)
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.
title Optional. title for APNS
title-loc-key Optional. title-loc-key for APNS
title-loc-args Optional. title-loc-args for APNS
uniqush.apns_voip Set this to 1 to indicate that any APNS pushes should be subject to the VOIP payload size limit of 5120 bytes, instead of the default of 4096 bytes
uniqush.payload.gcm The raw JSON payload for GCM subscribers (for “data”). If this is specified, it replaces the GCM payload.
uniqush.payload.fcm The raw JSON payload for FCM subscribers (for “data”). If this is specified, it replaces the FCM payload.
uniqush.payload.apns The raw JSON payload for APNS subscribers. If this is specified, it replaces the APNS payload. (except ttl)
uniqush.notification.gcm The raw JSON payload for GCM subscribers (for “notification”). If this is specified, it is added alongside the “data” payload. (If there are no other fields, the “notification” will be the only section)
uniqush.notification.fcm The raw JSON payload for FCM subscribers (for “notification”). If this is specified, it is added alongside the “data” payload. (If there are no other fields, the “notification” will be the only section)
Reserved Parameter Any parameter whose name starts from “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 parameters 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:

The payload (currently always JSON) that would be sent for any client type can be viewed with the /previewpush endpoint

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:


Preview Push Payload

Parameters

Parameter Description
pushservicetype A supported push service type (“apns”, “gcm”, “fcm”, or “adm”).
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 Optional. action-loc-key for APNS.
uniqush.payload.gcm Optional. Raw JSON payload for GCM clients (for “data”). If this is specified, it replaces the GCM payload.
uniqush.payload.fcm The raw JSON payload for FCM subscribers (for “data”). If this is specified, it replaces the FCM payload.
uniqush.payload.apns Optional. Raw JSON payload for APNS clients. If this is specified, it replaces the APNS payload. (except ttl)
uniqush.notification.gcm The raw JSON payload for GCM subscribers (for “notification”). If this is specified, it is added alongside the “data” payload. (If there are no other fields, the “notification” will be the only section)
uniqush.notification.fcm The raw JSON payload for FCM subscribers (for “notification”). If this is specified, it is added alongside the “data” payload. (If there are no other fields, the “notification” will be the only section)
Reserved Parameter Optional. Any parameter whose name starts from “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 parameters should be provided, or it will be an empty message. This API returns the same error code /push would.

See the section for “Push Notifications”.

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