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:
uniqush-push/versionuniqush-push -version to get the version of uniqush-pushuniqush-push/stopNOTE: You need to stop the program or it may not synchronize the cache with the database.
/addpsp| 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
| 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
| 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).
| 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
/rmpsp| 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
| 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
| 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
| 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| 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
| 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
| 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
| 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
These are optional user-defined fields, which can be passed in when subscribing.
These will be returned later when fetching subscriptions in /subscriptions.
The below parameters can safely be changed if resubscribing, and resubscribing will update existing subscriptions without creating duplicate delivery points. (i.e. the below parameters don’t change the delivery point’s internal ID, and they shouldn’t be passed in when unsubscribing.)
Storing these parameters requires uniqush-push 2.6.0+. Older releases will ignore these optional parameters if they are fetched from the database.
| Parameter | Description |
| app_version | Application version string. (useful if clients plan to send different pushes (or different contents) to different application versions) |
| subscribe_date | Unix timestamp when the subscription was created (in seconds). This must be an integer. |
| locale | User-defined string. This may be useful if you wish to store individual device’s locales in uniqush’s database. |
| devid | An identifier uniquely identifying the device, to help clients identify duplicate subscriptions (E.g. identifierForVendor for APNS, ANDROID_ID (or Advertising ID, depending on the usage) for GCM/FCM). This can be used (e.g. in combination with subscribe_date) by clients to delete duplicate subscriptions. |
| old_devid | Can be used manually by clients if the way device ids was generated changed in a later app release, to identify duplicate subscriptions. Rarely needed. |
Example: curl http://127.0.0.1:9898/subscribe -d service=myservice -d subscriber=uniqush.client -d pushservicetype=apns -d devtoken=some-device-token -d app_version=1.2.3 -d subscribe_date=1234567890 -d locale=fr_FR -d devid=MyAppABCDE124ZY
/unsubscribe| 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.
| 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.
| 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
| 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
/subscriptionsCalling this API will return the subscriptions (i.e. delivery points) created
| Parameter | Description |
| services | Service Name(s) |
| subscriber | Subscriber ID |
| include_delivery_point_ids | Set this to 1 if you want to return the internal delivery_point_id along with the subscription data. The delivery_point_id can be passed to /push to limit pushes to a subset of a subscriber’s devices. (Requires uniqush-push 2.6.0+. |
Example: curl http://127.0.0.1:9898/subscriptions -d services=myservice,myotherservice -d subscriber=uniqush.client
| 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.
/pspsReturns JSON representing the PSPs stored in Uniqush, along with their configs (API keys, paths to certificates, service type, etc.).
/rebuildservicesetInitializes the set of all service names. This API is needed for the /subscriptions and the /psps APIs to work(and be efficient).
/push| 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) |
| delivery_point_id | A comma separated list of 1 or more delivery points (belonging to the provided subscriber(s) and service(s)) to push to, e.g. delivery_point_id=apns:abcdef0123456789,apns:1111aaaaacafe. The delivery point ids can be requested from /subscriptions. (Requires uniqush-push 2.6.0+) |
| 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:
Push to one subscriber:
curl http://127.0.0.1:9898/push -d service=myservice -d subscriber=uniqush.client -d msg="Hello World"
Push to multiple subscribers:
curl http://127.0.0.1:9898/push -d service=myservice -d subscriber=uniqush.client1,uniqush.client2 -d msg="Hello World"
Push with user defined parameter
curl http://127.0.0.1:9898/push -d service=myservice -d subscriber=uniqush.client -d msg="Hello World" -d userdefinedparam=somearbitraryvalue
Push to multiple subscribers with pattern:
curl http://127.0.0.1:9898/push -d service=myservice -d subscriber=uniqush.* -d msg="Hello World"
Push to all subscribers under some service (you probably do not want to do that):
curl http://127.0.0.1:9898/push -d service=myservice -d subscriber=* -d msg="Hello World"
Push GCM “notification” payload to GCM subscribers (these are rendered directly on the device by GCM, similarly to APNs’s default behavior)
curl http://127.0.0.1:9898/push -d service=mygcmservice -d subscriber=uniqush.client -d uniqush.payload.gcm='{"title":"MyTitle","body":"NotifBodyText"}'
/previewpush| 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:
Preview the payload sent to GCM, APNs, or ADM clients:
curl http://127.0.0.1:9898/previewpush -d pushservicetype=gcm -d msg="Hello World"curl http://127.0.0.1:9898/previewpush -d pushservicetype=apns -d msg="Hello World"curl http://127.0.0.1:9898/previewpush -d pushservicetype=adm -d msg="Hello World"/nrdp| Parameter | Description |
| service | Service Name |
| subscriber | Subscriber ID |
Example: curl http://127.0.0.1:9898/nrdp -d service=myservice -d subscriber=uniqush.client
