com.stackmob.sdkapi
Interface PushService

public interface PushService

The push notification service.

Nested Class Summary

static class	PushService.TokenAndType
static class	PushService.TokenType

Method Summary

void	broadcastPush(int badge, String sound, String alert) Deprecated. use broadcastPush(java.util.Map) instead. this method only broadcasts to iOS devices
void	broadcastPush(Map<String,String> pairs) broadcast a push to all devices registered to the current application.
Map<PushService.TokenAndType,Long>	getAllExpiredTokens(boolean clear) get all of the tokens that are expired for this app
Map<String,List<PushService.TokenAndType>>	getAllTokensForUsers(List<String> users) get all of the tokens for each of the given users
Map<String,Long>	getExpiredTokens(boolean clear) Deprecated. use getAllExpiredTokens(boolean) instead. This method only gets/removes iOS expired tokens,
Set<PushService.TokenType>	getSendableDevicesForPayload(Map<String,String> pairs) get the devices that can be sent to with the given payload.
Map<String,String>	getTokensForUsers(List<String> users) Deprecated. use getAllTokensForUsers(java.util.List) instead. This method only gets iOS tokens.
void	registerToken(String username, String token) Deprecated. use registerTokenForUser(String, TokenAndType) instead. This method only registers iOS tokens
void	registerTokenForUser(String username, PushService.TokenAndType token) register a token for a given user
void	removeToken(PushService.TokenAndType token) remove a token from the list of registered tokens
void	removeToken(String token) Deprecated. use removeToken(TokenAndType) instead. This method can only remove iOS tokens.
void	sendPush(List<String> tokens, int badge, String sound, String alert) Deprecated. use sendPushToTokens(java.util.List, java.util.Map) instead. This method only pushes to iOS devices
void	sendPush(List<String> recipients, int badge, String sound, String alert, boolean recipientsAreTokens) Deprecated. use sendPushToUsers(java.util.List, java.util.Map) instead. This only sends to iOS devices
void	sendPushToTokens(List<PushService.TokenAndType> tokens, Map<String,String> pairs) Send a push notification to each device identified by the tokens provided.
void	sendPushToUsers(List<String> users, Map<String,String> pairs) send a push notification to all of the devices registered to the given users.

Method Detail

sendPushToTokens

void sendPushToTokens(List<PushService.TokenAndType> tokens,
                      Map<String,String> pairs)
                      throws PushServiceException

Send a push notification to each device identified by the tokens provided. Note that the total JSON encoded size (ie: the payload) of the pairs parameter must be no larger than 256 bytes to push to iOS devices, and 1024 bytes to push to Android devices.

Payload Sizes

As it supports multiple devices as its push destination, this method takes a best effort approach in sending push notifications. Below is a table outlining to which devices the push notification will be sent for various payload size ranges.

Payload size range (bytes)	Behavior
[0, 256]	Sends to both Android and iOS devices
(256, 1024]	Sends to Android only, logs the iOS tokens to which the send would fail, and throws
(1024,infinity)	Sends to no devices, logs the failed tokens, and throws

This table should only be used as a guide. Use getSendableDevicesForPayload(java.util.Map) in your code to check which devices can be sent to given a payload.

The pairs parameter

The following table outlines how this method handles the data in the pairs parameter for each device.

Device	Behavior
iOS	Any value whose key is "badge", "sound" or "alert" will be automatically put into the reserved "aps" dictionary. Per the iOS push notification documentation: "badge" specifies the number to be displayed with the app icon "sound" specifies the sound to be played by the device "alert" specifies the text to be displayed by the device All other key/value pairs will be sent to the client in a custom dictionary called "smob".
Android	any value whose key is "collapse_key" will be used as the collapse key for the push notification. if no collapse key is given, "smob" will be used as the collapse key. if a collapse key is given, it will be removed from the payload prior to sending.

Parameters:

tokens - the tokens to send to

pairs - the key/value pairs to send

Throws:

PushServiceException - if an error occurred

See Also:

getSendableDevicesForPayload(java.util.Map)

sendPushToUsers

void sendPushToUsers(List<String> users,
                     Map<String,String> pairs)
                     throws PushServiceException

send a push notification to all of the devices registered to the given users.

Parameters:

users - the users to which to send

pairs - the payload to send. This function treats this parameter exactly as does sendPushToTokens(java.util.List, java.util.Map)

Throws:

PushServiceException - if an error occurred

See Also:

sendPushToTokens(java.util.List, java.util.Map)

broadcastPush

void broadcastPush(Map<String,String> pairs)
                   throws PushServiceException

broadcast a push to all devices registered to the current application.

Parameters:

pairs - the payload to send. This function treats this parameter exactly as does sendPushToTokens(java.util.List, java.util.Map), for both size restrictions and content

Throws:

PushServiceException - if an error occurred

See Also:

sendPushToTokens(java.util.List, java.util.Map)

getAllTokensForUsers

Map<String,List<PushService.TokenAndType>> getAllTokensForUsers(List<String> users)
                                                                throws DatastoreException

get all of the tokens for each of the given users

Parameters:

users - the users for which to get tokens

Returns:

a mapping from the user to a set containing all of the tokens registered to that user

Throws:

DatastoreException - if an error occurred

removeToken

void removeToken(PushService.TokenAndType token)
                 throws DatastoreException

remove a token from the list of registered tokens

Parameters:

token - the token to remove

Throws:

DatastoreException - if an error occurred

getSendableDevicesForPayload

Set<PushService.TokenType> getSendableDevicesForPayload(Map<String,String> pairs)
                                                        throws PushServiceException

get the devices that can be sent to with the given payload. this method is useful to use as a check before calling sendPushToTokens(java.util.List, java.util.Map) or sendPushToUsers(java.util.List, java.util.Map)

Parameters:

pairs - the proposed payload to test

Returns:

a set of the TokenTypes representing the devices that could be sent to

Throws:

PushServiceException - if an error occurred

registerTokenForUser

void registerTokenForUser(String username,
                          PushService.TokenAndType token)
                          throws DatastoreException

register a token for a given user

Parameters:

username - the user to which to register the token

token - the token to register

Throws:

DatastoreException - if an error occurred

getAllExpiredTokens

Map<PushService.TokenAndType,Long> getAllExpiredTokens(boolean clear)
                                                       throws DatastoreException

get all of the tokens that are expired for this app

Parameters:

clear - if true, remove all of the returned tokens after this method returns

Returns:

a mapping from expired token to expiration time of that token, represented in milliseconds since January 1, 1970 UTC

Throws:

DatastoreException - if an error occurred

sendPush

@Deprecated
void sendPush(List<String> tokens,
                         int badge,
                         String sound,
                         String alert)
              throws PushServiceException

Deprecated. use sendPushToTokens(java.util.List, java.util.Map) instead. This method only pushes to iOS devices

Send a push notification to all iOS devices identified by the tokens provided. This is a shorthand for sendPush(tokens, badge, sound, alert, true)

Parameters:

tokens - the device tokens to which the push notification should be sent

badge - the badge for the push notification; specifies the number to be displayed with the app icon

sound - the sound to be played by the devices

alert - the text of the alert to be displayed by the devices

Throws:

PushServiceException - if an error occurs

sendPush

@Deprecated
void sendPush(List<String> recipients,
                         int badge,
                         String sound,
                         String alert,
                         boolean recipientsAreTokens)
              throws PushServiceException

Deprecated. use sendPushToUsers(java.util.List, java.util.Map) instead. This only sends to iOS devices

Send a push notification to all iOS devices identified by the recipients list. The meaning of the entries in the recipients list is controlled by the recipientsAreTokens parameter. If true, the recipients list is considered to consist of device tokens. If false, the recipients list will be considered to be user IDs. In either case, tokens need to be registered via the registerToken(String, String) call, before they can be used.

Parameters:

recipients - the device tokens to which the push notification should be sent

badge - the badge for the push notification; specifies the number to be displayed with the app icon

sound - the sound to be played by the devices

alert - the text of the alert to be displayed by the devices

recipientsAreTokens - the type of entries in the recipients list. true if specifying tokens, false for users

Throws:

PushServiceException - if an error occurs

broadcastPush

@Deprecated
void broadcastPush(int badge,
                              String sound,
                              String alert)
                   throws PushServiceException

Deprecated. use broadcastPush(java.util.Map) instead. this method only broadcasts to iOS devices

Broadcast a push notification to all devices running this app.

Parameters:

badge - the badge for the push notification; specifies the number to be displayed with the app icon

sound - the sound to be played by the devices

alert - the text of the alert to be displayed by the devices

Throws:

PushServiceException - if an error occurs

getExpiredTokens

@Deprecated
Map<String,Long> getExpiredTokens(boolean clear)
                                  throws DatastoreException

Deprecated. use getAllExpiredTokens(boolean) instead. This method only gets/removes iOS expired tokens,

Get the tokens, which have been reported as expired by Apple's feedback service

Parameters:

clear - if true, the set of expired tokens will be cleared after the call. if false, the current token set will be retained on the server

Returns:

A list of expired tokens, represented as a Map, where the token is the key, and the value is the expiration time, represented as milliseconds since January 1, 1970 UTC

Throws:

DatastoreException - if an error occurs

registerToken

@Deprecated
void registerToken(String username,
                              String token)
                   throws DatastoreException

Deprecated. use registerTokenForUser(String, TokenAndType) instead. This method only registers iOS tokens

Assign a push token to the specified user. After a token is registered, it may be used to push messages to the user. If the username is null, or an empty string, the token will be registered without a username.

Parameters:

username - a username to associate with the specified token

token - iOS device token

Throws:

DatastoreException - if an error occurs

getTokensForUsers

@Deprecated
Map<String,String> getTokensForUsers(List<String> users)
                                     throws DatastoreException

Deprecated. use getAllTokensForUsers(java.util.List) instead. This method only gets iOS tokens.

Finds the device push tokens for the given user list. Will not return the tokens, which were marked as expired by the feedback service. Use getExpiredTokens(boolean) to get the expired tokens.

Parameters:

users - list of user IDs

Returns:

a map of user IDs to push tokens. If no token is registered for a user, then the user ID will not be included in the returned map

Throws:

DatastoreException - if an error occurs

removeToken

@Deprecated
void removeToken(String token)
                 throws DatastoreException

Deprecated. use removeToken(TokenAndType) instead. This method can only remove iOS tokens.

Removes the token from the list of registered tokens.

Parameters:

token - token to be removed

Throws:

DatastoreException - if an error occurs