com.parse
Class PushService

Object
  extended by android.content.Context
      extended by android.content.ContextWrapper
          extended by android.app.Service
              extended by com.parse.PushService
All Implemented Interfaces:
ComponentCallbacks

public final class PushService
extends Service

A service to listen for push notifications. This operates in the same process as the parent application. To use this class, the PushService must be registered. Add this XML right before the </application> tag in your AndroidManifest.xml:

 <service android:name="com.parse.PushService" />
 <receiver android:name="com.parse.ParseBroadcastReceiver">
   <intent-filter>
     <action android:name="android.intent.action.BOOT_COMPLETED" />
     <action android:name="android.intent.action.USER_PRESENT" />
   </intent-filter>
 </receiver>
 
Next, you must ensure your app has the permissions needed to show a notification. Make sure that these permissions are present in your AndroidManifest.xml, typically immediately before the </manifest> tag:
 <uses-permission android:name="android.permission.INTERNET" />
 <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED" />
 <uses-permission android:name="android.permission.VIBRATE" />
 
Once push notifications are configured in the manifest, you can subscribe to a push channel by calling
 PushService.subscribe(context, "the_channel_name", YourActivity.class);
 
When the client receives a push message, a notification will appear in the system tray. When the user taps the notification, they will enter the application through a new instance of YourActivity.


Field Summary
 
Fields inherited from class android.content.Context
ACTIVITY_SERVICE, ALARM_SERVICE, AUDIO_SERVICE, BIND_AUTO_CREATE, BIND_DEBUG_UNBIND, CLIPBOARD_SERVICE, CONNECTIVITY_SERVICE, CONTEXT_IGNORE_SECURITY, CONTEXT_INCLUDE_CODE, INPUT_METHOD_SERVICE, KEYGUARD_SERVICE, LAYOUT_INFLATER_SERVICE, LOCATION_SERVICE, MODE_APPEND, MODE_PRIVATE, MODE_WORLD_READABLE, MODE_WORLD_WRITEABLE, NOTIFICATION_SERVICE, POWER_SERVICE, SEARCH_SERVICE, SENSOR_SERVICE, TELEPHONY_SERVICE, VIBRATOR_SERVICE, WALLPAPER_SERVICE, WIFI_SERVICE, WINDOW_SERVICE
 
Constructor Summary
PushService()
          Client code should not construct a PushService directly.
 
Method Summary
static Set<String> getSubscriptions(Context context)
          Accesses the current set of channels for which the current installation is subscribed.
 IBinder onBind(Intent intent)
          onBind should not be called directly.
 void onCreate()
          Client code should not call onCreate directly.
 void onDestroy()
          Client code should not call onDestroy directly.
static void setDefaultPushCallback(Context context, Class<? extends Activity> cls)
          Provides a default Activity class to handle pushes.
static void setDefaultPushCallback(Context context, Class<? extends Activity> cls, int icon)
          Provides a default Activity class to handle pushes.
static void startServiceIfRequired(Context context)
           
static void subscribe(Context context, String channel, Class<? extends Activity> cls)
          Helper function to subscribe to push notifications with the default application icon.
static void subscribe(Context context, String channel, Class<? extends Activity> cls, int icon)
          Call this function when the user should be subscribed to a new push channel.
static void unsubscribe(Context context, String channel)
          Cancels a previous call to subscribe.
 
Methods inherited from class android.app.Service
dump, finalize, getApplication, onConfigurationChanged, onLowMemory, onRebind, onStart, onUnbind, setForeground, stopSelf, stopSelf, stopSelfResult
 
Methods inherited from class android.content.ContextWrapper
attachBaseContext, bindService, checkCallingOrSelfPermission, checkCallingOrSelfUriPermission, checkCallingPermission, checkCallingUriPermission, checkPermission, checkUriPermission, checkUriPermission, clearWallpaper, createPackageContext, databaseList, deleteDatabase, deleteFile, enforceCallingOrSelfPermission, enforceCallingOrSelfUriPermission, enforceCallingPermission, enforceCallingUriPermission, enforcePermission, enforceUriPermission, enforceUriPermission, fileList, getApplicationContext, getAssets, getBaseContext, getCacheDir, getClassLoader, getContentResolver, getDatabasePath, getDir, getFilesDir, getFileStreamPath, getMainLooper, getPackageCodePath, getPackageManager, getPackageName, getPackageResourcePath, getResources, getSharedPreferences, getSystemService, getTheme, getWallpaper, getWallpaperDesiredMinimumHeight, getWallpaperDesiredMinimumWidth, grantUriPermission, openFileInput, openFileOutput, openOrCreateDatabase, peekWallpaper, registerReceiver, registerReceiver, removeStickyBroadcast, revokeUriPermission, sendBroadcast, sendBroadcast, sendOrderedBroadcast, sendOrderedBroadcast, sendStickyBroadcast, setTheme, setWallpaper, setWallpaper, startActivity, startInstrumentation, startService, stopService, unbindService, unregisterReceiver
 
Methods inherited from class android.content.Context
getString, getString, getText, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes, obtainStyledAttributes
 
Methods inherited from class Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

PushService

public PushService()
Client code should not construct a PushService directly.

Method Detail

startServiceIfRequired

public static void startServiceIfRequired(Context context)

subscribe

public static void subscribe(Context context,
                             String channel,
                             Class<? extends Activity> cls)
Helper function to subscribe to push notifications with the default application icon.

Parameters:
context - This is used to access local storage to cache the subscription, so it must currently be a viable context.
channel - A string identifier that determines which messages will cause a push notification to be sent to this client. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.
cls - This should be a subclass of Activity. An instance of this Activity is started when the user responds to this push notification. If you are not sure what to use here, just use your application's main Activity subclass.
Throws:
IllegalArgumentException - if the channel name is not valid.

subscribe

public static void subscribe(Context context,
                             String channel,
                             Class<? extends Activity> cls,
                             int icon)
Call this function when the user should be subscribed to a new push channel. When push notifications are sent out on this channel subsequently, this device will display a "toast" notification in the system tray. This function returns immediately, even when there is no internet access. In that case the subscription is cached and when internet access is next available the client will inform the server of its subscription. This starts a PushService running in the background that will not permanently terminate as long as the user is subscribed to some channel, unless the application is uninstalled.

Parameters:
context - This is used to access local storage to cache the subscription, so it must currently be a viable context.
channel - A string identifier that determines which messages will cause a push notification to be sent to this client. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.
cls - This should be a subclass of Activity. An instance of this Activity is started when the user responds to this push notification. If you are not sure what to use here, just use your application's main Activity subclass.
icon - The icon to show for the notification.
Throws:
IllegalArgumentException - if the channel name is not valid.

unsubscribe

public static void unsubscribe(Context context,
                               String channel)
Cancels a previous call to subscribe. If the user is not subscribed to this channel, this is a no-op. This call does not require internet access. It returns without blocking.

Parameters:
context - A currently viable Context.
channel - The string defining the channel to unsubscribe from.

setDefaultPushCallback

public static void setDefaultPushCallback(Context context,
                                          Class<? extends Activity> cls)
Provides a default Activity class to handle pushes. Setting a default allows your program to handle pushes that aren't registered with a subscribe call. This can happen when your application changes its subscriptions directly through the ParseInstallation or via push-to-query.

Parameters:
context - This is used to access local storage to cache the subscription, so it must currently be a viable context.
cls - This should be a subclass of Activity. An instance of this Activity is started when the user responds to this push notification. If you are not sure what to use here, just use your application's main Activity subclass.

setDefaultPushCallback

public static void setDefaultPushCallback(Context context,
                                          Class<? extends Activity> cls,
                                          int icon)
Provides a default Activity class to handle pushes. Setting a default allows your program to handle pushes that aren't registered with a subscribe call. This can happen when your application changes its subscriptions directly through the ParseInstallation or via push-to-query.

Parameters:
context - This is used to access local storage to cache the subscription, so it must currently be a viable context.
cls - This should be a subclass of Activity. An instance of this Activity is started when the user responds to this push notification. If you are not sure what to use here, just use your application's main Activity subclass.
icon - The icon to show for the notification.

getSubscriptions

public static Set<String> getSubscriptions(Context context)
Accesses the current set of channels for which the current installation is subscribed. It is important to remember that the device may receive pushes by means other than channels. This method returns the local cache, so it returns without blocking on network IO. In rare circumstances this may be stale, but only after the installation was edited via the REST API using the master key.

Parameters:
context - A currently viable Context.
Returns:
A set containing all of the channels this application is currently subscribed to.

onCreate

public void onCreate()
Client code should not call onCreate directly.

Overrides:
onCreate in class Service

onBind

public IBinder onBind(Intent intent)
onBind should not be called directly.

Specified by:
onBind in class Service

onDestroy

public void onDestroy()
Client code should not call onDestroy directly.

Overrides:
onDestroy in class Service