Tickaroo Pushservice

The Pushservice helps you to send notifications to millions of users. It takes care of the following tasks:

  • Registeration/deregistration of device tokens
  • Mangement of subscriptions to notification channels
  • Sending a notification to millions of devices at once
  • Cancelles out differences of pushing to different kinds of devices
  • Client libraries allow easy integration in apps

Devices and Channels

Pushservice Overview

Notifications are sent to devices based on subscriptions to so called “channels”. Any number of devices can subscribe to a channel. When a notification is sent to this channel, all subscribed devices will receive the notification. Devices can subscribe to any number of channels and will receive all notifications sent to those channels. A notification can be sent to more than one channel at once. The Pushservice will automatically deduplicate devices, so even though a device might be subscribed to more than one target channel, only one notification will be sent to the device.

When the backend provider indicates a device has become invalid the Pushservice will first mark it as “broken token” and will stop sending further notifications. If the device updates it’s token within two weeks, all subscriptions will be restored. After that time the device and it’s subscriptions will be permanently deleted.

A Channel is basically just a String. You can build a subchannel hierarchy by giving channels well formed names. For instance game.123 and game.123.goal where game.123.goal can be seen as subchannel of game.123 since its a prefix of. Note that the dot (.) is just a character and has no deeper meaning. One could model the same channel by giving such names for channels: game/123/goal. Remember, its just a String.

Supported Devices

Supported Backends

At the moment, the Pushservice supports the following backends/devices:

  • Apple Push Notification Service (APNS)
  • Google Cloud Messaging (GCM)
  • Windows Notification Service (WNS)
  • Web Push (Web)

Client Libraries

Client libraries exist for:

  • iOS
  • Android
  • Windows Store Apps
  • Javascript

Sending Notifications

Notifications are sent to the Pushservice via HTTPS POST requests with a JSON payload. No special library is needed.

Security

All communication with the Pushservice runs over an encrypted HTTPS connection. Every request is secured with a shared secret (now called “token”). There are two kinds of tokens:

  • push tokens: Must be used to send notifications
  • subscribe tokens: Must be used to subscribe to channels and receive notifications

Tokens can be created and destroyed in the admin UI and are uniquely affiliated with an App.

Statistics

For every notifications, the Pushservice records the following statistics:

  • Time it took to send the push
  • Total number of recipients per backend
  • Number of notifications succesfully transmitted to the backend
  • Number of failed devices

Admin UI

The Pushservice comes with an Administrative UI which help you with the following tasks:

  • Looking at statistics
  • Debugging device subscriptions
  • Testing Pushes
  • Setting up the connection to backends

Sending Notifications from your System

Sending notifications requires you to Post a JSON file to the following endpoint:

POST https://pushservice-notify.tickaroo.com/v2/notification/create?auth_token=[PUSH_TOKEN]

Request Body

The JSON has the following keys:

uid

  • Name: uid
  • Type: String
  • Constraints: Must match /^[a-zA-Z0-9\._-]{1,255}$/
  • Required: YES

Uniquely identifies the notification. If a notification with the same uid is received twice, the second one will be ignored.

channels

  • Name: channels
  • Type: Array
  • Constraints: Element must match /^(\$\.)?([a-zA-Z0-9()-]+\.)*[a-zA-Z0-9()-]+$/
  • Required: YES

The channel names to send the notifications to. There are special channels starting with $. for example $.apns.8AAC148902ACA8222C4E354CEA28D03C463B6B7837B52362C122AB59B2CDFB1A will send a notification to that specific apns identifier.

devices

  • Name: devices
  • Type: Array
  • Constraints: Allowed values are “gcm”, “wns” and “apns” in any combindation
  • Required: NO
  • Default Value: all

Limits the device types the notification should be sent to.

ttl

  • Name: ttl
  • Type: Integer
  • Required: NO
  • Constraint: >= 0

Limits the amount of time the notification is pending until it’s discarded if the user has his phone turned off. The value is in seconds.

headline

  • Name: headline
  • Type: String
  • Required: No

Headline of the displayed message. Fully supported on WNS and GCM, but will just be prepended to the message on iOS.

message

  • Name: message
  • Type: String
  • Required: NO

The text of the displayed message. Must be set to display a visible notification.

badge

  • Name: badge
  • Type: Integer
  • Required: NO

Badge Icon Number. Directly supported on ios and windows, for android this translates to a badge field in the payload data, collapse_key=badge and delay_while_idle=true as it seems to only server passive notification purposes.

image

  • Name: badge
  • Type: String
  • Required: NO

Image to display in the notification (only supported on Windows!)

data

  • Name: data
  • Type: Object<String, String>
  • Required: NO
  • Constraints: Only strings are supported cross plattform

Additional data to send with the push notification.

gcm

  • Name: gcm
  • Type: Object<String, String>
  • Required: NO
  • Constraints: Only strings are supported cross plattform

Additional data to send with the push notification on GCM. Will be merged with data

apns

  • Name: apns
  • Type: Object
  • Required: NO

Additional data to send with the push notification on APNS. Will be merged with data. Contrary to GCM, Apple allows to send rich JSON data.

wns

  • Name: wns
  • Type: Object
  • Required: NO

Additional data to send with the push notification on WNS. Will be merged with data

web

  • Name: web
  • Type: Object
  • Required: No

Additional data to send with the push notification on Web. Will be merged with data

Example Request

{
  "uid": "testmessage-1",
  "channels": ["testchannel"],
  "message": "Hello World"
}

Response on Success

The Pushservice will respond with response code 201 when a notification is postet. If the uid of the messgae is a duplicate, it will still respond with 201 but ignore the duplicate message. The response body will contain the uid of the message.

Response on Error

If a response code other than 201 is returned, there was an error in the request.

  • Error code 400 indicates a problem with the submitted JSON. The response body will contain a detailed error message as JSON object.
  • Error code 401 indicates an invalid auth_token
  • Error codes >= 500 indicate a temporary problem, please retry later. If the error persists contact the Tickaroo support team.

Registering Devices and Subscriptions from your Backend

Registering a devices and subscribing to channels happens in one call. To register a device or change a channel subscription a post request with a JSON file must be sent to the following endpoint:

POST https://pushservice.tickaroo.com/v2/subscriptions/update?auth_token=[APP_SUBSCRIBE_TOKEN]

The first time a specific device is seen, it will be automatically registered. Subscriptions are cumulative e.g. if one request subscribes a device to “channel1” and a second request subscribes it to “channel2” the device will be registered for BOTH channels. Subscriptions can be cancelled explicitly by updating a subscription (see “The Subscription Object”).

Request Body

The JSON has the following keys:

device

  • Name: device
  • Type: Object
  • Required: YES

An object identifying the device. If the device is unknown it will be registered, otherwise it will be updated.

subscriptions

  • Name: subscriptions
  • Type: Array
  • Required: YES

A list of subscription changes to apply to the device.

The Device Object

The Device object has the following keys:

type

  • Name: type
  • Type: String
  • Constraints: Allowed values are “apns”, “gcm” and “wns”
  • Required: YES

Defines which kind of push service must be used for this device

token

  • Name: token
  • Type: String
  • Constraints: Depending on type format must match a valid push token
  • Required: YES

The current push token of the device

wastoken

  • Name: wastoken
  • Type: String
  • Constraints: Depending on type format must match a valid push token
  • Required: NO

If the pushtoken changed, this should contain the previous push token of the device for one successful request. If this is set, all subscriptions will be transfered to the new token.

The Subscription Object

The subscription object has the following keys:

channel

  • Name: channel
  • Type: String
  • Constraints: Must match /^(\$\.)?([a-zA-Z0-9()-]+\.)*[a-zA-Z0-9()-]+$/
  • Required: YES

The name of the channel

status

  • Name: status
  • Type: String
  • Constraints: Allowed values are “s” and “c”
  • Required: YES

The new status of the subscription. “s” means subscribed. “c” means cancelled.

expiresAt

  • Name: expiresAt
  • Type: Integer
  • Constraints: Represents a 32-BIT unsigned UNIX Timestamp
  • Required: NO

If set, the subscription automatically expires at the given time. New notifications will not be sent to the device after this timestamp.

Example Request

{
  "device": {
    "type": "gcm",
    "token": "I_AM_A_TOKEN"
  },
  "subscriptions": [
    {"channel": "news", "status": "s"},
    {"channel": "match_day", "status": "c"}
  ]
}

Response on Success

The Pushservice will respond with response code 200 on success.

Response on Error

If a response code other than 200 is returned, there was an error in the request.

Error code 400 indicates a problem with the submitted JSON. The response body will contain a detailed error message as JSON object. Error code 401 indicates an invalid auth_token Error codes >= 500 indicate a temporary problem, please retry later. If the error persists contact the Tickaroo support team.