PFPush Class Reference

Inherits from NSObject
Conforms to NSCopying
Declared in PFPush.h

Overview

The PFPush class defines a push notification that can be sent from a client device.

The preferred way of modifying or retrieving channel subscriptions is to use the PFInstallation class, instead of the class methods in PFPush.

Configuring a Push Notification

– setChannel:

Sets the channel on which this push notification will be sent.

- (void)setChannel:(nullable NSString *)channel

Parameters

channel

The channel to set for this push. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

Declared In

PFPush.h

– setChannels:

Sets the array of channels on which this push notification will be sent.

- (void)setChannels:(nullable NSArray PF_GENERIC ( NSString *) *)channels

Parameters

channels

The array of channels to set for this push. Each channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

Declared In

PFPush.h

– setQuery:

Sets an installation query to which this push notification will be sent.

- (void)setQuery:(nullable PFQuery PF_GENERIC ( PFInstallation *) *)query

Parameters

query

The installation query to set for this push.

Discussion

The query should be created via [PFInstallation query] and should not specify a skip, limit, or order.

Declared In

PFPush.h

– setMessage:

Sets an alert message for this push notification.

- (void)setMessage:(nullable NSString *)message

Parameters

message

The message to send in this push.

Discussion

Warning: This will overwrite any data specified in setData.

Declared In

PFPush.h

– setData:

Sets an arbitrary data payload for this push notification.

- (void)setData:(nullable NSDictionary *)data

Parameters

data

The data to send in this push.

Discussion

See the guide for information about the dictionary structure.

Warning: This will overwrite any data specified in setMessage.

Declared In

PFPush.h

– setPushToAndroid:

Sets whether this push will go to Android devices. (Deprecated: Please use a [PFInstallation query] with a constraint on deviceType instead.)

- (void)setPushToAndroid:(BOOL)pushToAndroid

Parameters

pushToAndroid

Whether this push will go to Android devices.

Declared In

PFPush.h

– setPushToIOS:

Sets whether this push will go to iOS devices. (Deprecated: Please use a [PFInstallation query] with a constraint on deviceType instead.)

- (void)setPushToIOS:(BOOL)pushToIOS

Parameters

pushToIOS

Whether this push will go to iOS devices.

Declared In

PFPush.h

– expireAtDate:

Sets the expiration time for this notification.

- (void)expireAtDate:(nullable NSDate *)date

Parameters

date

The time at which the notification should expire.

Discussion

The notification will be sent to devices which are either online at the time the notification is sent, or which come online before the expiration time is reached. Because device clocks are not guaranteed to be accurate, most applications should instead use expireAfterTimeInterval:.

Declared In

PFPush.h

– expireAfterTimeInterval:

Sets the time interval after which this notification should expire.

- (void)expireAfterTimeInterval:(NSTimeInterval)timeInterval

Parameters

timeInterval

The interval after which the notification should expire.

Discussion

This notification will be sent to devices which are either online at the time the notification is sent, or which come online within the given time interval of the notification being received by Parse’s server. An interval which is less than or equal to zero indicates that the message should only be sent to devices which are currently online.

Declared In

PFPush.h

– clearExpiration

Clears both expiration values, indicating that the notification should never expire.

- (void)clearExpiration

Declared In

PFPush.h

Sending Push Notifications

+ sendPushMessageToChannel:withMessage:error:

Synchronously send a push message to a channel.

+ (BOOL)sendPushMessageToChannel:(NSString *)channel withMessage:(NSString *)message error:(NSError **)error

Parameters

channel

The channel to send to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

message

The message to send.

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns whether the send succeeded.

Declared In

PFPush.h

+ sendPushMessageToChannelInBackground:withMessage:

Asynchronously send a push message to a channel.

+ (BFTask PF_GENERIC ( NSNumber *) *)sendPushMessageToChannelInBackground:(NSString *)channel withMessage:(NSString *)message

Parameters

channel

The channel to send to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

message

The message to send.

Return Value

The task, that encapsulates the work being done.

Declared In

PFPush.h

+ sendPushMessageToChannelInBackground:withMessage:block:

Asynchronously sends a push message to a channel and calls the given block.

+ (void)sendPushMessageToChannelInBackground:(NSString *)channel withMessage:(NSString *)message block:(nullable PFBooleanResultBlock)block

Parameters

channel

The channel to send to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

message

The message to send.

block

The block to execute. It should have the following argument signature: ^(BOOL succeeded, NSError *error)

Declared In

PFPush.h

+ sendPushMessageToQuery:withMessage:error:

Send a push message to a query.

+ (BOOL)sendPushMessageToQuery:(PFQuery PF_GENERIC ( PFInstallation *) *)query withMessage:(NSString *)message error:(NSError **)error

Parameters

query

The query to send to. The query must be a PFInstallation query created with [PFInstallation query].

message

The message to send.

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns whether the send succeeded.

Declared In

PFPush.h

+ sendPushMessageToQueryInBackground:withMessage:

Asynchronously send a push message to a query.

+ (BFTask PF_GENERIC ( NSNumber *) *)sendPushMessageToQueryInBackground:(PFQuery PF_GENERIC ( PFInstallation *) *)query withMessage:(NSString *)message

Parameters

query

The query to send to. The query must be a PFInstallation query created with [PFInstallation query].

message

The message to send.

Return Value

The task, that encapsulates the work being done.

Declared In

PFPush.h

+ sendPushMessageToQueryInBackground:withMessage:block:

Asynchronously sends a push message to a query and calls the given block.

+ (void)sendPushMessageToQueryInBackground:(PFQuery PF_GENERIC ( PFInstallation *) *)query withMessage:(NSString *)message block:(nullable PFBooleanResultBlock)block

Parameters

query

The query to send to. The query must be a PFInstallation query created with [PFInstallation query].

message

The message to send.

block

The block to execute. It should have the following argument signature: ^(BOOL succeeded, NSError *error)

Declared In

PFPush.h

– sendPush:

Synchronously send this push message.

- (BOOL)sendPush:(NSError **)error

Parameters

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns whether the send succeeded.

Declared In

PFPush.h

– sendPushInBackground

Asynchronously send this push message.

- (BFTask PF_GENERIC ( NSNumber *) *)sendPushInBackground

Return Value

The task, that encapsulates the work being done.

Declared In

PFPush.h

– sendPushInBackgroundWithBlock:

Asynchronously send this push message and executes the given callback block.

- (void)sendPushInBackgroundWithBlock:(nullable PFBooleanResultBlock)block

Parameters

block

The block to execute. It should have the following argument signature: ^(BOOL succeeded, NSError *error).

Declared In

PFPush.h

+ sendPushDataToChannel:withData:error:

Synchronously send a push message with arbitrary data to a channel.

+ (BOOL)sendPushDataToChannel:(NSString *)channel withData:(NSDictionary *)data error:(NSError **)error

Parameters

channel

The channel to send to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

data

The data to send.

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns whether the send succeeded.

Discussion

See the guide for information about the dictionary structure.

Declared In

PFPush.h

+ sendPushDataToChannelInBackground:withData:

Asynchronously send a push message with arbitrary data to a channel.

+ (BFTask PF_GENERIC ( NSNumber *) *)sendPushDataToChannelInBackground:(NSString *)channel withData:(NSDictionary *)data

Parameters

channel

The channel to send to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

data

The data to send.

Return Value

The task, that encapsulates the work being done.

Discussion

See the guide for information about the dictionary structure.

Declared In

PFPush.h

+ sendPushDataToChannelInBackground:withData:block:

Asynchronously sends a push message with arbitrary data to a channel and calls the given block.

+ (void)sendPushDataToChannelInBackground:(NSString *)channel withData:(NSDictionary *)data block:(nullable PFBooleanResultBlock)block

Parameters

channel

The channel to send to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

data

The data to send.

block

The block to execute. It should have the following argument signature: ^(BOOL succeeded, NSError *error).

Discussion

See the guide for information about the dictionary structure.

Declared In

PFPush.h

+ sendPushDataToQuery:withData:error:

Synchronously send a push message with arbitrary data to a query.

+ (BOOL)sendPushDataToQuery:(PFQuery PF_GENERIC ( PFInstallation *) *)query withData:(NSDictionary *)data error:(NSError **)error

Parameters

query

The query to send to. The query must be a PFInstallation query created with [PFInstallation query].

data

The data to send.

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns whether the send succeeded.

Discussion

See the guide for information about the dictionary structure.

Declared In

PFPush.h

+ sendPushDataToQueryInBackground:withData:

Asynchronously send a push message with arbitrary data to a query.

+ (BFTask PF_GENERIC ( NSNumber *) *)sendPushDataToQueryInBackground:(PFQuery PF_GENERIC ( PFInstallation *) *)query withData:(NSDictionary *)data

Parameters

query

The query to send to. The query must be a PFInstallation query created with [PFInstallation query].

data

The data to send.

Return Value

The task, that encapsulates the work being done.

Discussion

See the guide for information about the dictionary structure.

Declared In

PFPush.h

+ sendPushDataToQueryInBackground:withData:block:

Asynchronously sends a push message with arbitrary data to a query and calls the given block.

+ (void)sendPushDataToQueryInBackground:(PFQuery PF_GENERIC ( PFInstallation *) *)query withData:(NSDictionary *)data block:(nullable PFBooleanResultBlock)block

Parameters

query

The query to send to. The query must be a PFInstallation query created with [PFInstallation query].

data

The data to send.

block

The block to execute. It should have the following argument signature: ^(BOOL succeeded, NSError *error).

Discussion

See the guide for information about the dictionary structure.

Declared In

PFPush.h

Handling Notifications

+ handlePush:

A default handler for push notifications while the app is active that could be used to mimic the behavior of iOS push notifications while the app is backgrounded or not running.

+ (void)handlePush:(nullable NSDictionary *)userInfo

Parameters

userInfo

The userInfo dictionary you get in appplication:didReceiveRemoteNotification:.

Discussion

Call this from application:didReceiveRemoteNotification:. If push has a dictionary containing loc-key and loc-args in the alert, we support up to 10 items in loc-args (NSRangeException if limit exceeded).

Warning: This method is available only on iOS.

Declared In

PFPush.h

Managing Channel Subscriptions

+ storeDeviceToken:

Store the device token locally for push notifications.

+ (void)storeDeviceToken:(id)deviceToken

Parameters

deviceToken

Either as an NSData straight from application:didRegisterForRemoteNotificationsWithDeviceToken: or as an NSString if you converted it yourself.

Discussion

Usually called from you main app delegate’s didRegisterForRemoteNotificationsWithDeviceToken:.

Declared In

PFPush.h

+ getSubscribedChannels:

Synchronously get all the channels that this device is subscribed to.

+ (nullable NSSet PF_GENERIC ( NSString *) *)getSubscribedChannels:(NSError **)error

Parameters

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns an NSSet containing all the channel names this device is subscribed to.

Declared In

PFPush.h

+ getSubscribedChannelsInBackground

Asynchronously get all the channels that this device is subscribed to.

+ (BFTask PF_GENERIC ( NSSet<NSString*> *) *)getSubscribedChannelsInBackground

Return Value

The task, that encapsulates the work being done.

Declared In

PFPush.h

+ getSubscribedChannelsInBackgroundWithBlock:

Asynchronously get all the channels that this device is subscribed to.

+ (void)getSubscribedChannelsInBackgroundWithBlock:(PFSetResultBlock)block

Parameters

block

The block to execute. It should have the following argument signature: ^(NSSet *channels, NSError *error).

Declared In

PFPush.h

+ subscribeToChannel:error:

Synchrnously subscribes the device to a channel of push notifications.

+ (BOOL)subscribeToChannel:(NSString *)channel error:(NSError **)error

Parameters

channel

The channel to subscribe to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns whether the subscribe succeeded.

Declared In

PFPush.h

+ subscribeToChannelInBackground:

Asynchronously subscribes the device to a channel of push notifications.

+ (BFTask PF_GENERIC ( NSNumber *) *)subscribeToChannelInBackground:(NSString *)channel

Parameters

channel

The channel to subscribe to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

Return Value

The task, that encapsulates the work being done.

Declared In

PFPush.h

+ subscribeToChannelInBackground:block:

Asynchronously subscribes the device to a channel of push notifications and calls the given block.

+ (void)subscribeToChannelInBackground:(NSString *)channel block:(nullable PFBooleanResultBlock)block

Parameters

channel

The channel to subscribe to. The channel name must start with a letter and contain only letters, numbers, dashes, and underscores.

block

The block to execute. It should have the following argument signature: ^(BOOL succeeded, NSError *error)

Declared In

PFPush.h

+ unsubscribeFromChannel:error:

Synchronously unsubscribes the device to a channel of push notifications.

+ (BOOL)unsubscribeFromChannel:(NSString *)channel error:(NSError **)error

Parameters

channel

The channel to unsubscribe from.

error

Pointer to an NSError that will be set if necessary.

Return Value

Returns whether the unsubscribe succeeded.

Declared In

PFPush.h

+ unsubscribeFromChannelInBackground:

Asynchronously unsubscribes the device from a channel of push notifications.

+ (BFTask PF_GENERIC ( NSNumber *) *)unsubscribeFromChannelInBackground:(NSString *)channel

Parameters

channel

The channel to unsubscribe from.

Return Value

The task, that encapsulates the work being done.

Declared In

PFPush.h

+ unsubscribeFromChannelInBackground:block:

Asynchronously unsubscribes the device from a channel of push notifications and calls the given block.

+ (void)unsubscribeFromChannelInBackground:(NSString *)channel block:(nullable PFBooleanResultBlock)block

Parameters

channel

The channel to unsubscribe from.

block

The block to execute. It should have the following argument signature: ^(BOOL succeeded, NSError *error).

Declared In

PFPush.h