Push IO API
Integration Guide
Copyright © 2009 - 2013 Push IO Inc. All Rights Reserved.
Push IO® is a registered trademark in the United States. All other trademarks are the property of their respective owners.
Software License Information
The use of any and all Push IO software regardless of release state is governed by the terms of a Software License Agreement and Terms of Use that are not included here but required by reference.
Privacy Information
The use of Push IO services is subject to various privacy policies and restrictions on the use of end user information. For complete information please refer to your Master Agreement, our website privacy policies, and/or other related documents.
Billing
For information on your account and billing, please contact sales@push.io
Contact Info
Push IO
1035 Pearl Street, Suite 400
Boulder, CO 80302 USA
303-335-0903
support@push.io
www.push.io
Preface
Push IO is a leading provider of real-time push notification alerts and mobile data delivery.This document provides the necessary information to leverage Push IO for your mobile application. This document corresponds to the latest version of PushIOManager for Android.
Definitions
App ID
Each individual application has a unique ID used by the application to communicate with the Push IO service.
Sender Secret
This is a secret shared between Push IO and the developer using direct device messaging which authorizes them to send to an account.
Category
A category defines a specific content type that your app has which users might be interested in. For example, if your app is a sports app, a category may be a specific team.
Audience
An audience defines a group of users based on one or more categories or platforms. For example, you might make an audience out of all of the users who have registered to a category for a team in the Western Conference who are using your app on Android.
Test Device
A device specially registered with Push IO to help you troubleshoot, test, and preview push notifications.
API Integration
Overview
Push IO provides a simple RESTful API with JSON responses.
The API offers methods for sending broadcast, targeted (category-based), and test device push notifications. Sending through the API allows you to target users on all of your platforms with a single call.
Push IO is the only push notification provider which provides data that allows you to understand how push notification engagement leads your users to high-value actions like in-app purchases, premium content viewing, and more. The PushIOManager library provides a simple mechanism to capture this push conversion information, which is available to you via the Push IO Manager dashboard.
API Prerequisites
Before continuing, be sure you have what you need to integrate Push IO into your app.
- Sign up for an account at https://manage.push.io
- Complete PushIOManager integration for your app (see Push IO Integration Guides
All set? Now you’re ready to integrate with the Push IO API!
API Setup
Sign in to your Push IO Manager dashboard
Navigate to Set Up > API
Locate your App ID
Generate a Service Secret required to send to the Push IO REST API.
You may always re-generate your Service Secret from Set Up > API in order to maintain a high-level of security for sending to your app users.
Sample API Calls
The Push IO production endpoint is:
https://manage.push.io
Test Device Push
Send a message to your test devices.
POST
api/v1/test_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={“message”: “Test Device Push”}
Broadcast Push
Send a message to all your users.
POST
api/v1/notify_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={“message”: “Broadcast Push”}&audience=broadcast
Targeted Push
Send a message to some of your users.
POST
api/v1/notify_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={“message”: “Targeted Push”}&tag_query=$YOUR_CATEGORY_NAME
Advanced API Calls
Newsstand Content Available Notification
If your iOS app is part of Newstand, you can broadcast to all your users the content available notification. This is not user-facing, but tells your app to begin downloading new content in the background.
POST
api/v1/notify_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={"payload_apns":{"aps_extra":{"content-available":1}}}&audience=broadcast
Broadcast Push with Extra Data
Send a message to all your users, with the text “Hello All Users” with all other parameters set as platform defaults. In addition, the app will receive the JSON key value pair “key” : ”value”.
POST
api/v1/notify_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={“message”: “Hello All Users”, “extra” : {“key” : “value”}}&audience=broadcast
Broadcast Push with Platform Specific Data
Send a message to all your users, with alternative data sent to your iOS app. Users on all platforms EXCEPT iOS will see the text “Hello All Users” and receive the JSON pair “key” : ”value”. Users on iOS will see the text “Hello iOS Users”, receive a badge number of 2 and the JSON pair “ioskey”:”iosvalue”.
POST
api/v1/notify_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={“message”: “Hello All Users”, “extra” : {“key” : “value”}, “payload_apns” : { “alert” : “Hello iOS Users”, “badge” : 2, “extra” : {“ioskey” : “iosvalue”}}&audience=broadcast
Targeted Push with AND Logic
Send a message targeted to users who are registered for both categories specified.
POST
api/v1/notify_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={“message”: “Targeted Push”}&tag_query=$CATEGORY_ONE and $CATEGORY_TWO
Targeted Push with OR Logic
Send a message targeted to users who are registered for one of two categories.
POST
api/v1/notify_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={“message”: “Targeted Push”}&tag_query=$CATEGORY_ONE or $CATEGORY_TWO
Targeted Push with AND/OR Logic
Send a message targeted to users who are registered for one of two categories, and also registered for another category.
POST
api/v1/notify_app/$YOUR APP ID/$YOUR SERVICE SECRET
POST Data
payload={“message”: “Targeted Push”}&tag_query=($CATEGORY_ONE or $CATEGORY_TWO) and $CATEGORY_THREE
Payload Fields
Most of the example API commands described thus far have sent a text alert message to the user. Each platform supports a slightly different set of features. For instance, iOS supports playing a sound via push notification. Push IO allows you to send data to your app using JSON key pairs. These pairs are contained within the payload parameter in your POST command. The following is a list of all the allowable pairs and a description.
payload
| Parameter | Description |
| "message" | The default message for each platform. This message will be displayed as the notification text unless overridden at the platform payload level |
| "extra" | General JSON key/value pairs added as appropriate to each platform, unless overridden by platform-specific extra |
| "payload_apns" | A shipment_payload_apns JSON object (described below) which contains key/value pair which will apply only to iOS devices |
| "payload_gcm" | A shipment_payload_gcm JSON object (described below) which contains key/value pair which will apply only to notifications sent through Google's Cloud Messaging service for Android |
| "payload_mpns" | A shipment_payload_mpns JSON object (described below) which contains key/value pair which will apply only to Windows Phones |
payload_apns
| Parameter | Description |
| "alert" | The text that will be displayed in the notification |
| "badge" | The number that will appear over the top left corner of an app’s icon |
| "sound" | The name of the sound file to be played when the notification arrives. This file must be contained in your app’s bundle |
| "aps_extra" | iOS specific key/value pairs (provided in JSON) that are inserted into the 'aps' payload. This is most useful for Newsstand apps that need to trigger background content downloading by sending a push notification payload consisting of: "content-available" : 1 |
| "extra" | iOS specific key/value pairs (provided in JSON) that are passed along with the 'aps' payload. If any value is provided for this it will override the entire payload-level extra values; i.e. it is not merged with the extra data in the parent platform object |
payload_gcm
| Parameter | Description |
| "alert" | The value of the data.alert field that is shown as the notification text on Android by the Push IO client library |
| "badge" | The value of the data.badge field that is sent to Android devices |
| "sound" | The value of the data.sound field that is sent to Android devices |
| "extra" | GCM-specific key/value pairs (provided in JSON) that are passed as children of the 'data' element of the payload. If any value is provided for this it will override the entire payload-level extra values; i.e. it is not merged with the extra data in the parent platform object |
| "collapse_key" | The GCM collapse key, used for send-to-sync messages, as described here: http://developer.android.com/guide/google/gcm/adv.html#collapsible |
| "delay_while_idle" | Boolean value, default false, which GCM servers use to determine if the message will be delivered immediately or when the device becomes active |
| "time_to_live" | Integer value determining how long (in seconds) the message should be kept for delay_while_idle situations, default 4 weeks |
payload_mpns
| Parameter | Description |
| "toast_text1" | Text that displays in a bold typeface in one row along with text2, approx 40 characters fit if just text1 is shown. |
| "toast_text2" | Text that displays in a roman typeface after toast_text1. This is where the global payload's 'message' parameter will be copied unless overridden. Approx 47 characters fit if only text2 is used, if text1 and text2 are evenly split, approx 41 characters fit |
| "tile_id" | The id of the secondary tile to update, which is an exact navigation Uri of the secondary tile, ex: SecondaryTile.xaml?DefaultTitle=FromTile |
| "tile_count" | An integer value from 1-99 shown on the front of the tile. This value is copied down from the global payload's 'badge' parameter unless overridden |
| "tile_background_image" | The image shown as the backgound on the front of the tile, full url, host must be authorized on device by app, must not be https, .jpg or .png image, 173x173px, 80k or less, must download within 30 seconds |
| "tile_back_title" | Like the tile_title but on the back of the tile, 15 characters max |
| "tile_back_background_image" | Full url of the image shown on the back of the tile, same rules as tile_background_image |
| "tile_back_content" | Text displayed at the top of the back tile, approx 40 characters fit |
| "props_to_clear" | Comma separated string of tile elements to be reset to defaults |
Python Module
A python module is available for making it simple to send via the Push IO API. To install the module, you can use your favorite python manager.
pip install pushio
Send a Broadcast Push Notification
from pushio import pushio
# You can locate this from the Set Up > API at manage.push.io
appID = "Your Push IO App ID"
serviceSecret = "Your Push IO Service Secret"
# Create a pushioAPI instance
pushioAPI = pushio.API(appID, serviceSecret, debug=True)
message = "This is a broadcast push notification via the Push IO python module"
notification = pushio.Notification(message=message)
pushioAPI.sendBroadcastPushNotification(notification)
Send a Targeted Push Notification
# Send to all users registered for the category specified
category = "Sports"
pushioAPI.sendCategoryPushNotification(notification, category)
Send a Targeted Push Notification with OR Logic
notification = pushio.Notification(message="Hello, Sports or US World")
categories = "Sports or US"
pushioAPI.sendCategoryPushNotification(notification, categories)
Send to Test Devices
testNotification = pushio.Notification(message="Hello, Test World")
pushioAPI.sendTestDevicePushNotification(testNotification)
Trigger a iOS Newsstand Content Update Notification
If your app is an iOS Newsstand app, you can initiate background content update downloads.
pushioAPI.sendNewsstandContentAvailablePushNotification()
Send a Custom Message to One Platform
You can even do complex things like pass platform specific values, with each other platform getting the Notification object values. The python module supports all of the elements of each platform payload enumerated in the Payload Fields section earlier in this document.
apns = pushio.APNS(alert="Hello, iOS World", sound="beep.wav")
notification = pushio.Notification(message="Hello, Rest of World", payload_apns=apns.payload)
pushioAPI.sendBroadcastPushNotification(notification)