PFPush

Objective-C


@interface PFPush : NSObject <NSCopying>

Swift

class PFPush : NSObject, NSCopying

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.

Creating a Push Notification


  • Declaration

    Objective-C

    + (nonnull instancetype)push;

Configuring a Push Notification

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

    Declaration

    Objective-C

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

    Swift

    func setChannel(_ channel: String?)

    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.

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

    Declaration

    Objective-C

    - (void)setChannels:(nullable NSArray<NSString *> *)channels;

    Swift

    func setChannels(_ channels: [String]?)

    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.

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

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

    Declaration

    Objective-C

    - (void)setQuery:(nullable PFQuery<PFInstallation *> *)query;

    Swift

    func setQuery(_ query: PFQuery?)

    Parameters

    query

    The installation query to set for this push.

  • Sets an alert message for this push notification.

    Warning

    This will overwrite any data specified in setData.

    Declaration

    Objective-C

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

    Swift

    func setMessage(_ message: String?)

    Parameters

    message

    The message to send in this push.

  • Sets an arbitrary data payload for this push notification.

    See the guide for information about the dictionary structure.

    Warning

    This will overwrite any data specified in setMessage.

    Declaration

    Objective-C

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

    Swift

    func setData(_ data: [AnyHashable : Any]?)

    Parameters

    data

    The data to send in this push.

  • Deprecated

    Please use a [PFInstallation query] with a constraint on deviceType. This method is deprecated and won’t do anything.

    Sets whether this push will go to Android devices.

    @deprecated Please use a PFInstallation.+query with a constraint on deviceType instead.

    Declaration

    Objective-C

    - (void)setPushToAndroid:(BOOL)pushToAndroid;

    Swift

    func setPushToAndroid(_ pushToAndroid: Bool)

    Parameters

    pushToAndroid

    Whether this push will go to Android devices.

  • Deprecated

    Please use a [PFInstallation query] with a constraint on deviceType. This method is deprecated and won’t do anything.

    Sets whether this push will go to iOS devices.

    @deprecated Please use a PFInstallation.+query with a constraint on deviceType instead.

    Declaration

    Objective-C

    - (void)setPushToIOS:(BOOL)pushToIOS;

    Swift

    func setPushToIOS(_ pushToIOS: Bool)

    Parameters

    pushToIOS

    Whether this push will go to iOS devices.

  • Sets the expiration time for this notification.

    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:.

    See

    expireAfterTimeInterval:

    Declaration

    Objective-C

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

    Swift

    func expire(at date: Date?)

    Parameters

    date

    The time at which the notification should expire.

  • Sets the time interval after which this notification should expire.

    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.

    Declaration

    Objective-C

    - (void)expireAfterTimeInterval:(NSTimeInterval)timeInterval;

    Swift

    func expire(afterTimeInterval timeInterval: TimeInterval)

    Parameters

    timeInterval

    The interval after which the notification should expire.

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

    Declaration

    Objective-C

    - (void)clearExpiration;

    Swift

    func clearExpiration()
  • Date at which to send this push notification.

    Push notificaitons with this date will be delivered at the local time matching the PFInstallation.timeZone.

    Warning

    The date cannot be in the past, and can be up to two weeks in the future.

    Declaration

    Objective-C

    @property (nonatomic, strong, nullable) NSDate *pushDate;

    Swift

    var pushDate: Date? { get set }

Sending Push Notifications

  • Asynchronously send a push message to a channel.

    Declaration

    Objective-C

    + (nonnull BFTask<NSNumber *> *)
        sendPushMessageToChannelInBackground:(nonnull NSString *)channel
                                 withMessage:(nonnull NSString *)message;

    Swift

    class func sendMessageToChannel(inBackground channel: String, withMessage message: String) -> BFTask<NSNumber>

    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.

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

    Declaration

    Objective-C

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

    Swift

    class func sendMessageToChannel(inBackground channel: String, withMessage message: String, block: PFBooleanResultBlock? = nil)

    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)

  • Asynchronously send a push message to a query.

    Declaration

    Objective-C

    + (nonnull BFTask<NSNumber *> *)
        sendPushMessageToQueryInBackground:
            (nonnull PFQuery<PFInstallation *> *)query
                               withMessage:(nonnull NSString *)message;

    Swift

    class func sendMessageToQuery(inBackground query: PFQuery, withMessage message: String) -> BFTask<NSNumber>

    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.

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

    Declaration

    Objective-C

    + (void)sendPushMessageToQueryInBackground:
                (nonnull PFQuery<PFInstallation *> *)query
                                   withMessage:(nonnull NSString *)message
                                         block:(nullable PFBooleanResultBlock)block;

    Swift

    class func sendMessageToQuery(inBackground query: PFQuery, withMessage message: String, block: PFBooleanResultBlock? = nil)

    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)

  • Asynchronously send this push message.

    Declaration

    Objective-C

    - (nonnull BFTask<NSNumber *> *)sendPushInBackground;

    Swift

    func sendInBackground() -> BFTask<NSNumber>

    Return Value

    The task, that encapsulates the work being done.

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

    Declaration

    Objective-C

    - (void)sendPushInBackgroundWithBlock:(nullable PFBooleanResultBlock)block;

    Swift

    func sendInBackground() async throws -> Bool

    Parameters

    block

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

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

    See the guide for information about the dictionary structure.

    Declaration

    Objective-C

    + (nonnull BFTask<NSNumber *> *)
        sendPushDataToChannelInBackground:(nonnull NSString *)channel
                                 withData:(nonnull NSDictionary *)data;

    Swift

    class func sendDataToChannel(inBackground channel: String, withData data: [AnyHashable : Any]) -> BFTask<NSNumber>

    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.

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

    See the guide for information about the dictionary structure.

    Declaration

    Objective-C

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

    Swift

    class func sendDataToChannel(inBackground channel: String, withData data: [AnyHashable : Any], block: PFBooleanResultBlock? = nil)

    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).

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

    See the guide for information about the dictionary structure.

    Declaration

    Objective-C

    + (nonnull BFTask<NSNumber *> *)
        sendPushDataToQueryInBackground:(nonnull PFQuery<PFInstallation *> *)query
                               withData:(nonnull NSDictionary *)data;

    Swift

    class func sendDataToQuery(inBackground query: PFQuery, withData data: [AnyHashable : Any]) -> BFTask<NSNumber>

    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.

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

    See the guide for information about the dictionary structure.

    Declaration

    Objective-C

    + (void)sendPushDataToQueryInBackground:
                (nonnull PFQuery<PFInstallation *> *)query
                                   withData:(nonnull NSDictionary *)data
                                      block:(nullable PFBooleanResultBlock)block;

    Swift

    class func sendDataToQuery(inBackground query: PFQuery, withData data: [AnyHashable : Any], block: PFBooleanResultBlock? = nil)

    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).

Handling Notifications

  • 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.

    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.

    Declaration

    Objective-C

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

    Parameters

    userInfo

    The userInfo dictionary you get in appplication:didReceiveRemoteNotification:.

Managing Channel Subscriptions

  • Store the device token locally for push notifications.

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

    Declaration

    Objective-C

    + (void)storeDeviceToken:(nonnull id)deviceToken;

    Swift

    class func storeDeviceToken(_ deviceToken: Any)

    Parameters

    deviceToken

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

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

    Declaration

    Objective-C

    + (nonnull BFTask<NSSet<NSString *> *> *)getSubscribedChannelsInBackground;

    Swift

    class func getSubscribedChannelsInBackground() -> BFTask<NSSet>

    Return Value

    The task, that encapsulates the work being done.

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

    Declaration

    Objective-C

    + (void)getSubscribedChannelsInBackgroundWithBlock:
        (nonnull PFSetResultBlock)block;

    Swift

    class func subscribedChannelsInBackground() async throws -> Set<AnyHashable>

    Parameters

    block

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

  • Asynchronously subscribes the device to a channel of push notifications.

    Declaration

    Objective-C

    + (nonnull BFTask<NSNumber *> *)subscribeToChannelInBackground:
        (nonnull NSString *)channel;

    Swift

    class func subscribeToChannel(inBackground channel: String) -> BFTask<NSNumber>

    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.

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

    Declaration

    Objective-C

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

    Swift

    class func subscribeToChannel(inBackground channel: String, block: PFBooleanResultBlock? = nil)

    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)

  • Asynchronously unsubscribes the device from a channel of push notifications.

    Declaration

    Objective-C

    + (nonnull BFTask<NSNumber *> *)unsubscribeFromChannelInBackground:
        (nonnull NSString *)channel;

    Swift

    class func unsubscribeFromChannel(inBackground channel: String) -> BFTask<NSNumber>

    Parameters

    channel

    The channel to unsubscribe from.

    Return Value

    The task, that encapsulates the work being done.

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

    Declaration

    Objective-C

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

    Swift

    class func unsubscribeFromChannel(inBackground channel: String, block: PFBooleanResultBlock? = nil)

    Parameters

    channel

    The channel to unsubscribe from.

    block

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

Sending Push Notifications

  • Asynchronously send a push message to a channel.

    @deprecated Please use PFPush.+sendPushMessageToChannelInBackground:withMessage:block: instead.

    Declaration

    Objective-C

    + (void)sendPushMessageToChannelInBackground:(nonnull NSString *)channel
                                     withMessage:(nonnull NSString *)message
                                          target:(nullable id)target
                                        selector:(nullable SEL)selector;

    Swift

    class func sendMessageToChannel(inBackground channel: String, withMessage message: String, target: Any?, selector: Selector?)

    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.

    target

    The object to call selector on.

    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSNumber *)result error:(NSError *)error. error will be nil on success and set if there was an error. [result boolValue] will tell you whether the call succeeded or not.

  • Deprecated

    Please use PFPush.-sendPushInBackgroundWithTarget:selector: instead.

    Asynchronously send this push message and calls the given callback.

    @deprecated Please use PFPush.-sendPushInBackgroundWithTarget:selector: instead.

    Declaration

    Objective-C

    - (void)sendPushInBackgroundWithTarget:(nullable id)target
                                  selector:(nullable SEL)selector;

    Swift

    func sendInBackground(withTarget target: Any?, selector: Selector?)

    Parameters

    target

    The object to call selector on.

    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSNumber *)result error:(NSError *)error. error will be nil on success and set if there was an error. [result boolValue] will tell you whether the call succeeded or not.

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

    See the guide for information about the dictionary structure.

    @deprecated Please use PFPush.+sendPushDataToChannelInBackground:withData:block: instead.

    Declaration

    Objective-C

    + (void)sendPushDataToChannelInBackground:(nonnull NSString *)channel
                                     withData:(nonnull NSDictionary *)data
                                       target:(nullable id)target
                                     selector:(nullable SEL)selector;

    Swift

    class func sendDataToChannel(inBackground channel: String, withData data: [AnyHashable : Any], target: Any?, selector: Selector?)

    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.

    target

    The object to call selector on.

    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSNumber *)result error:(NSError *)error. error will be nil on success and set if there was an error. [result boolValue] will tell you whether the call succeeded or not.

Managing Channel Subscriptions

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

    @deprecated Please use PFPush.+getSubscribedChannelsInBackgroundWithBlock: instead.

    Declaration

    Objective-C

    + (void)getSubscribedChannelsInBackgroundWithTarget:(nonnull id)target
                                               selector:(nonnull SEL)selector;

    Swift

    class func getSubscribedChannelsInBackground(withTarget target: Any, selector: Selector)

    Parameters

    target

    The object to call selector on.

    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSSet *)result error:(NSError *)error. error will be nil on success and set if there was an error.

  • Deprecated

    Please use PFPush.+subscribeToChannelInBackground:block: instead.

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

    @deprecated Please use PFPush.+subscribeToChannelInBackground:block: instead.

    Declaration

    Objective-C

    + (void)subscribeToChannelInBackground:(nonnull NSString *)channel
                                    target:(nullable id)target
                                  selector:(nullable SEL)selector;

    Swift

    class func subscribeToChannel(inBackground channel: String, target: Any?, selector: Selector?)

    Parameters

    channel

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

    target

    The object to call selector on.

    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSNumber *)result error:(NSError *)error. error will be nil on success and set if there was an error. [result boolValue] will tell you whether the call succeeded or not.

  • Deprecated

    Please use PFPush.+unsubscribeFromChannelInBackground:block: instead.

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

    @deprecated Please use PFPush.+unsubscribeFromChannelInBackground:block: instead.

    Declaration

    Objective-C

    + (void)unsubscribeFromChannelInBackground:(nonnull NSString *)channel
                                        target:(nullable id)target
                                      selector:(nullable SEL)selector;

    Swift

    class func unsubscribeFromChannel(inBackground channel: String, target: Any?, selector: Selector?)

    Parameters

    channel

    The channel to unsubscribe from.

    target

    The object to call selector on.

    selector

    The selector to call. It should have the following signature: (void)callbackWithResult:(NSNumber *)result error:(NSError *)error. error will be nil on success and set if there was an error. [result boolValue] will tell you whether the call succeeded or not.

Sending Push Notifications

  • Synchronously send this push message.

    Declaration

    Objective-C

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

    Swift

    func send() throws

    Parameters

    error

    Pointer to an NSError that will be set if necessary.

    Return Value

    Returns whether the send succeeded.

  • Synchronously send a push message to a channel.

    Declaration

    Objective-C

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

    Swift

    class func sendMessage(toChannel channel: String, withMessage message: String) throws

    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.

  • Send a push message to a query.

    Declaration

    Objective-C

    + (BOOL)sendPushMessageToQuery:(nonnull PFQuery<PFInstallation *> *)query
                       withMessage:(nonnull NSString *)message
                             error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func sendMessage(to query: PFQuery, withMessage message: String) throws

    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.

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

    See the guide for information about the dictionary structure.

    Declaration

    Objective-C

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

    Swift

    class func sendData(toChannel channel: String, withData data: [AnyHashable : Any]) throws

    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.

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

    See the guide for information about the dictionary structure.

    Declaration

    Objective-C

    + (BOOL)sendPushDataToQuery:(nonnull PFQuery<PFInstallation *> *)query
                       withData:(nonnull NSDictionary *)data
                          error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func sendData(to query: PFQuery, withData data: [AnyHashable : Any]) throws

    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.

Managing Channel Subscriptions

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

    Declaration

    Objective-C

    + (nullable NSSet<NSString *> *)getSubscribedChannels:
        (NSError *_Nullable *_Nullable)error;

    Swift

    class func getSubscribedChannels() throws -> Set<String>

    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.

  • Synchrnously subscribes the device to a channel of push notifications.

    Declaration

    Objective-C

    + (BOOL)subscribeToChannel:(nonnull NSString *)channel
                         error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func subscribe(toChannel channel: String) throws

    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.

  • Synchronously unsubscribes the device to a channel of push notifications.

    Declaration

    Objective-C

    + (BOOL)unsubscribeFromChannel:(nonnull NSString *)channel
                             error:(NSError *_Nullable *_Nullable)error;

    Swift

    class func unsubscribe(fromChannel channel: String) throws

    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.