Oracle Help Center | Oracle Push Cloud Service (Standalone) title

Server API

There are two ways to send push notifications via Push IO:

  1. On the Web Dashboard, through our "Compose" feature, or
  2. Using our APIs, through RESTful cURL commands via a terminal, such as Mac's Terminal or Windows Command Prompt/PowerShell 3.0.

The Compose feature can be handy for sending notifications quickly, however, using the API will prove more effective if trying to automate your push notifications or tie your application to your backend (for instance, for sending notifications to individual users).

Prerequisites:

To begin sending via API, you will need to have created an application on the Web Dashboard and have acquired three credentials:

"PushIO Web Dashboard, API page"

"PushIO Web Dashboard, Platform API Key page"

NOTE: The API Key contains the value of your Application ID, followed by a four letter subvalue related to the platform you are using. For example:

General cURL Structure:

Before sending our first API call, lets understand the general structure of a cURL command. Featured to the right is a basic cURL command you can call to Push IO:

curl "https://api.pushio.com/api/v1/notify_app/[APP_ID]/[SENDER_SECRET]" -d 'payload={"message":"Test"}&audience=broadcast'

A typical Push IO cURL command contains two parts:

The first half is used to target your specific application (by using your unique Application ID and Sender Secret, and by targeting the notify_app or notify_devices pathway):

`"https://api.pushio.com/api/v1/notify_app/eg6DmFeI5A/G7Nq5qWLZLjpJjzpdqQo"`

Application ID and Sender Secret were filled in from our example above.

NOTE: You will typically use notify_app as the primary pathway for push notifications. The notify_devices pathway is used when sending to individual UUIDs generated by our SDKs.


The second half of the cURL command contains payload data specific to your application's supported platforms (iOS versus Android, for example).

`-d 'payload={"message":"Test"}&audience=broadcast'`

As mentioned, this is a basic push notification and will send the message "Test" to all of your platforms.

However, what if you wanted to send unique messages to each of your platforms, or, tap into features that are unique to the platforms themselves (for instance, iOS's badge feature)? Push IO supports sending in this manner, the payloads just have to be configured for each platform.

Payload Structure

The payload itself has three separate containers of data:

curl 'https://api.pushio.com/api/v1/notify_app/[APP_ID]/[SENDER_SECRET]' -d 'payload={"message":"Test","payload_gcm":{"alert":"Hello Android Users!","sound":"rooster"},"payload_apns":{"alert":"Hello iOS Users!","sound":"default.wav","badge":10}}&audience=broadcast'
  1. General, app-wide payload data
  2. Unique, platform-specific data
  3. Targeting/Segmentation data (such as Audiences, Categories, Location, and Advanced Segmentation)

The general, app-wide payload data applies to all platforms supported by your application. For instance, the payload={"message":"Test"} will send the message "Test" to iOS, Android, and Windows Phone if you support them.

The unique, platform specific data (payload_apns, payload_gcm) then overrides any information contained in the general payload for the platform(s) you're targeting. From the example cURL:

"payload_gcm":{"alert":"Hello Android Users!","sound":"rooster"}, "payload_apns":{"alert":"Hello iOS Users!","sound":"default.wav","badge":10}

These platform specific payloads will change the original message from "Test" to "Hello Android Users!" for Android and "Hello iOS Users!" for iOS. However, if you were also supporting a Windows Phone platform, the message would still show up as "Test" as it was never overridden with a platform payload.

The last part of the payload is dedicated to targeting and segmentation, so that you can push content that your users prefer instead of an app-wide, broadcast push notification.

From the cURL example, the &audience=broadcast parameter means that the notification will be sent to all of your application users.

NOTE: By default, the Push IO SDK enrolls your app users in a broadcast category, so that you can target your entire userbase.

However, your users can be queried a handful of ways:

Tip: Guides and example cURLs for setting up location-based push can be found here for iOS and here for Android. In addition, the Example cURLs guide in this section contains a comprehensive list of cURL commands as well.

Lastly, you can also use query logic to further segment your pushes:

Supported Logic: AND, OR, NOT Supported Operators: <, >, <=, >=, =, BETWEEN

For example, this push notification will be sent to those who are interested in the SPORTS category, but are not MALE and are not AMERICAN.

curl "https://api.pushio.com/api/v1/notify_app/[APP_ID]/[SENDER_SECRET]" -d 'payload={"message":"EU Soccer - Women's League"}&tag_query=Sports NOT (MALE OR AMERICAN)'

Likewise, this notification uses an operator to send a push to users who had just installed your application within the last day.

curl "https://api.pushio.com/api/v1/notify_app/[APP_ID]/[SENDER_SECRET]" -d 'payload={"message":"Welcome!"}&tag_query=$installed_at < days_ago(1)'