CocoaCocoaiOSSwiftCocoa Swift Storage & Playback API Reference for Realtime Apps

Go to Channel Groups


Requires Storage & Playback add-on XRequires that the Storage & Playback add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.
This function fetches historical messages of a channel.
PubNub Storage/Playback Service provides real-time access to an unlimited history for all messages published to PubNub. Stored messages are replicated across multiple availability zones in several geographical data center locations. Stored messages can be encrypted with AES-256 message encryption ensuring that they are not readable while stored on PubNub's network.
It is possible to control how messages are returned and in what order, for example you can:
  • Search for messages starting on the newest end of the timeline (default behavior - reverse = false)
  • Search for messages from the oldest end of the timeline by setting reverse to true.
  • Page through results by providing a startDate OR endDate time token.
  • Retrieve a slice of the time line by providing both a startDate AND endDate time token.
  • Limit the number of messages to a specific quantity using the limit parameter.
 
Start & End parameter usage clarity:
If only the startDate parameter is specified (without endDate), you will receive messages that are older than and up to that startDate timetoken value.
If only the endDate parameter is specified (without startDate) you will receive messages that match that endDate timetoken value and newer.
Specifying values for both startDate and endDate parameters will return messages between those timetoken values (inclusive on the endDate value).
Keep in mind that you will still receive a maximum of 100 messages even if there are more messages that meet the timetoken values. Iterative calls to history adjusting the startDate timetoken is necessary to page through the full set of results if more than 100 messages meet the timetoken values.
To run History you can use the following method(s) in the Swift SDK
  1. ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the History information.
    closurePNHistoryCompletionBlockYesThe completion closure has two arguments: result - in case of successful processing (data field will contain results of history request operation);status - in case if error occurred during request processing (errorData contains error information).
  2. ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the History information.
    startDateNSNumberNoTime token delimiting the start of time slice (exclusive) to pull messages from.
    endDateNSNumberNoTime token delimiting the end of time slice (inclusive) to pull messages from.
    closurePNHistoryCompletionBlockYesThe completion closure has two arguments: result - in case of successful processing (data field will contain results of history request operation);status - in case if error occurred during request processing (errorData contains error information).
  3. ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the History information.
    startDateNSNumberNoTime token delimiting the start of time slice (exclusive) to pull messages from.
    endDateNSNumberNoTime token delimiting the end of time slice (inclusive) to pull messages from.
    limitUIntYes

    Specifies the number of historical messages to return.

    default/maximum is 100.

    closurePNHistoryCompletionBlockYesThe completion closure has two arguments: result - in case of successful processing (data field will contain results of history request operation);status - in case if error occurred during request processing (errorData contains error information).
  4. ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the History information.
    startDateNSNumberNoTime token delimiting the start of time slice (exclusive) to pull messages from.
    endDateNSNumberNoTime token delimiting the end of time slice (inclusive) to pull messages from.
    shouldIncludeTimeTokenBoolYesIf true the message post timestamps will be included in the history response.
    closurePNHistoryCompletionBlockYesThe completion closure has two arguments:
    • result - in case of successful processing (data field will contain results of history request operation);
    • status - in case if error occurred during request processing (errorData contains error information).
  5. ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the History information.
    startDateNSNumberNoTime token delimiting the start of time slice (exclusive) to pull messages from.
    endDateNSNumberNoTime token delimiting the end of time slice (inclusive) to pull messages from.
    limitUIntYes

    Specifies the number of historical messages to return.

    default/maximum is 100.

    shouldIncludeTimeTokenBoolYesIf true the message post timestamps will be included in the history response.
    closurePNHistoryCompletionBlockYesThe completion closure has two arguments:
    • result - in case of successful processing (data field will contain results of history request operation);
    • status - in case if error occurred during request processing (errorData contains error information).
  6. ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the History information.
    startDateNSNumberNoTime token delimiting the start of time slice (exclusive) to pull messages from.
    endDateNSNumberNoTime token delimiting the end of time slice (inclusive) to pull messages from.
    limitUIntYes

    Specifies the number of historical messages to return.

    Default/maximum is 100.

    shouldReverseOrderBoolYes

    Setting to true will traverse the time line in reverse starting with the oldest message first.

    Default is false. If both start and end arguments are provided, reverse is ignored and messages are returned starting with the newest message.

    closurePNHistoryCompletionBlockYesThe completion closure has two arguments:
    • result - in case of successful processing (data field will contain results of history request operation);
    • status - in case if error occurred during request processing (errorData contains error information).
  7. ParameterTypeRequiredDescription
    channelStringYesChannel name to retrieve the History information.
    startDateNSNumberNoTime token delimiting the start of time slice (exclusive) to pull messages from.
    endDateNSNumberNoTime token delimiting the end of time slice (inclusive) to pull messages from.
    limitUIntYesSpecifies the number of historical messages to return. default/maximum is 100.
    shouldReverseOrderBoolYesSetting to true will traverse the time line in reverse starting with the oldest message first. Default is false. If both start and end arguments are provided, reverse is ignored and messages are returned starting with the newest message.
    shouldIncludeTimeTokenBoolYesIf true the message post timestamps will be included in the history response.
    closurePNHistoryCompletionBlockYesThe completion closure has two arguments: result - in case of successful processing (data field will contain results of history request operation);status - in case if error occurred during request processing (errorData contains error information).
Retrieve the last 100 messages on a channel:
self.client.historyForChannel("history_channel", withCompletion: { (result, status) in

	if status == nil {

		/**
		 Handle downloaded history using:
			result.data.start - oldest message time stamp in response
			result.data.end - newest message time stamp in response
			result.data.messages - list of messages
		 */
	}
	else {

		/**
		 Handle message history download error. Check 'category' property
		 to find out possible reason because of which request did fail.
		 Review 'errorData' property (which has PNErrorData data type) of status
		 object to get additional information about issue.

		 Request can be resent using: status.retry()
		 */
	}
})

Response objects which is returned by client when History API for channel used:

open class PNHistoryData : PNServiceData {
    
    // Channel history messages.
    open var messages: [Any] { get }
    // History time frame start time.
    open var start: NSNumber { get }
    // History time frame end time.
    open var end: NSNumber { get }
}

open class PNHistoryResult : PNResult {
    
    // Stores reference on channel history request processing information.
    open var data: PNHistoryData { get }
}
  1. self.client.historyForChannel("my_channel", start: nil, end: nil, limit: 3,
    						      reverse: true, withCompletion: { (result, status) in
    										
    	if status == nil {
    		
    		/**
    		 Handle downloaded history using:
    			result.data.start - oldest message time stamp in response
    			result.data.end - newest message time stamp in response
    			result.data.messages - list of messages
    		 */
    	}
    	else {
    		
    		/**
    		 Handle message history download error. Check 'category' property
    		 to find out possible reason because of which request did fail.
    		 Review 'errorData' property (which has PNErrorData data type) of status
    		 object to get additional information about issue.
    		 
    		 Request can be resent using: status.retry()
    		 */
    	}
    })
     [
    	["Pub1","Pub2","Pub3"],
    	13406746729185766,
    	13406746780720711
    ]
    
  2. let start = NSNumber(value: (13406746780720711 as CUnsignedLongLong))
    self.client.historyForChannel("my_channel", start: start, end: nil, limit: 100, 
    							  reverse: true, withCompletion: { (result, status) in
    								
    	if status == nil {
    		
    		/**
    		 Handle downloaded history using:
    			result.data.start - oldest message time stamp in response
    			result.data.end - newest message time stamp in response
    			result.data.messages - list of messages
    		 */
    	}
    	else {
    		
    		/**
    		 Handle message history download error. Check 'category' property
    		 to find out possible reason because of which request did fail.
    		 Review 'errorData' property (which has PNErrorData data type) of status
    		 object to get additional information about issue.
    		 
    		 Request can be resent using: status.retry()
    		 */
    	}
    })
     [
    	["Pub3","Pub4","Pub5"],
    	13406746780720711,
    	13406746845892666
    ]
    
  3. let end = NSNumber(value: (13406746780720711 as CUnsignedLongLong))
    self.client.historyForChannel("my_channel", start: nil, end: end, limit: 100, reverse: true, 
    							  withCompletion: { (result, status) in
    
    	if status == nil {
    
    		/**
    		 Handle downloaded history using:
    			result.data.start - oldest message time stamp in response
    			result.data.end - newest message time stamp in response
    			result.data.messages - list of messages
    		 */
    	}
    	else {
    
    		/**
    		 Handle message history download error. Check 'category' property
    		 to find out possible reason because of which request did fail.
    		 Review 'errorData' property (which has PNErrorData data type) of status
    		 object to get additional information about issue.
    
    		 Request can be resent using: status.retry()
    		 */
    	}
    })
    [
    	["Pub3","Pub4","Pub5"],
    	13406746780720711,
    	13406746845892666
    ]
    
  4.  
    Usage!
    You can call the method by passing 0 or a valid time token as the argument.
    // Pull out all messages newer then message sent at 14395051270438477.
    let date = NSNumber(value: (14395051270438477 as CUnsignedLongLong));
    self.historyNewerThen(date, onChannel: "history_channel", withCompletion:  { (messages) in
    	
    	print("Messages from history: \(messages)")
    })
    
    
    func historyNewerThen(_ date: NSNumber, onChannel channel: String, 
    					  withCompletion closure: @escaping (Array<Any>) -> Void) {
    		
    	var msgs: Array<Any> = []
    	self.historyNewerThen(date, onChannel: channel, withProgress: { (messages) in
    		
    		msgs.append(contentsOf: messages)
    		if messages.count < 100 { closure(msgs) }
    	})
    }
    	
    private func historyNewerThen(_ date: NSNumber, onChannel channel: String, 
    							  withProgress closure: @escaping (Array<Any>) -> Void) {
    	
    	self.client?.historyForChannel(channel, start: date, end: nil, limit: 100, 
    								   reverse: false, withCompletion: { (result, status) in
    									
    		if status == nil {
    			
    			closure((result?.data.messages)!)
    			if result?.data.messages.count == 100 {
    				
    				self.historyNewerThen((result?.data.end)!, onChannel: channel, 
    									  withProgress: closure)
    			}
    		}
    		else {
    			
    			/**
    			 Handle message history download error. Check 'category' property
    			 to find out possible reason because of which request did fail.
    			 Review 'errorData' property (which has PNErrorData data type) of status
    			 object to get additional information about issue.
    			 
    			 Request can be resent using: [status retry];
    			 */
    		}
    	})
    }
This function fetches historical messages of a channel.
 This method uses the builder pattern, you can remove the args which are optional.
To run History Builder you can use the following method(s) in the Swift SDK
  1. ParameterTypeRequiredDescription
    channels[String]YesList of channels for which history should be returned.
    limitUIntNoMaximum number of messages which should be returned for each channel.

    Maximum: 25.
    completionPNHistoryCompletionBlockYesHistory pull processing completion block which pass two arguments: result - in case of successful request processing data field will contain results of history request operation; status - in case if error occurred during request processing.
self.client.history().channels(["my_channel"]).limit(15).performWithCompletion({ (result, status) in

    if status == nil {

        /**
         Handle downloaded history using:
         result.data.channels - dictionary with channels' history. Each key is channel name and value is 
         list of fetched messages.
         */
    }
    else {

        /**
         Handle message history download error. Check 'category' property
         to find out possible reason because of which request did fail.
         Review 'errorData' property (which has PNErrorData data type) of status
         object to get additional information about issue.

         Request can be resent using: [status retry]
         */
    }
})
Requires Storage & Playback add-on XRequires that the Storage & Playback add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.
Removes the messages from the history of a specific channel.
 
There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable Delete-From-History checkbox in the key settings for your key in the Administration Portal.

Requires Initialization with secret key.

To Delete Messages from History you can use the following method(s) in the Swift SDK.
  1. open func deleteMessagesFromChannel(_ channel: String, start startDate: NSNumber?, end endDate: NSNumber?, withCompletion closure: PubNub.PNMessageDeleteCompletionBlock? = nil)
    ParameterTypeRequiredDescription
    channelStringYesName of the channel from which events should be removed.
    startDateNSNumberNoTime token delimiting the start of time slice (inclusive) to delete messages from.
    endDateNSNumberNoTime token delimiting the end of time slice (exclusive) to delete messages from.
    closurePNMessageDeleteCompletionBlockNoEvents remove processing completion closure which pass only one argument - request processing status to report about how data pushing was successful or not.
let startDate = NSNumber(value: (15101397027611671 as CUnsignedLongLong))
let endDate = NSNumber(value: (15101397427611671 as CUnsignedLongLong))
self.client.deleteMessagesFromChannel("channel", start: startDate, end: endDate, withCompletion: { (status) in
                        
    if !status.isError {
        // Messages within specified time frame has been removed.
    } else {
       /**
        * Handle message history download error. Check 'category' property to find out possible 
        * issue because of which request did fail.
        *
        * Request can be resent using: status.retry()
        */
    }
})

  1. To delete a specific message, pass the publish timetoken (received from a successful publish) in the End parameter and timetoken +/- 1 in the Start parameter. e.g. if 15526611838554310 is the publish timetoken, pass 15526611838554309 in Start and 15526611838554310 in End parameters respectively as shown in the following code snippet.
    let startDate = NSNumber(value: (15526611838554309 as CUnsignedLongLong))
    let endDate = NSNumber(value: (15526611838554310 as CUnsignedLongLong))
    self.client.deleteMessagesFromChannel("channel", start: startDate, end: endDate, withCompletion: { (status) in
                            
        if !status.isError {
            // Messages within specified time frame has been removed.
        } else {
           /**
            * Handle message history download error. Check 'category' property to find out possible 
            * issue because of which request did fail.
            *
            * Request can be resent using: status.retry()
            */
        }
    })
Requires Storage & Playback add-on XRequires that the Storage & Playback add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.
Removes the messages from the history of a specific channel.
 
There is a setting to accept delete from history requests for a key, which you must enable by checking the Enable Delete-From-History checkbox in the key settings for your key in the Administration Portal.

Requires Initialization with secret key.

To Delete Messages from History you can use the following method(s) in the Swift SDK.
  1. deleteMessage().channel(String).start(NSNumber?).end(NSNumber?).performWithCompletion(PubNub.PNMessageDeleteCompletionBlock? = nil)
    ParameterTypeRequiredDescription
    channelStringYesName of the channel from which events should be removed.
    startDateNSNumberNoTime token delimiting the start of time slice (exclusive) to delete messages from.
    endDateNSNumberNoTime token delimiting the end of time slice (inclusive) to delete messages from.
    closurePNMessageDeleteCompletionBlockNoEvents remove processing completion closure which pass only one argument - request processing status to report about how data pushing was successful or not.
let startDate = NSNumber(value: (15101397027611671 as CUnsignedLongLong))
let endDate = NSNumber(value: (15101397427611671 as CUnsignedLongLong))
self.client.deleteMessage().channel("channel").start(startDate).end(endDate).performWithCompletion({ (status) in
                        
    if !status.isError {
        // Messages within specified time frame has been removed.
    } else {
       /**
        * Handle message history download error. Check 'category' property to find out possible 
        * issue because of which request did fail.
        *
        * Request can be resent using: status.retry()
        */
    }
})
Requires Storage & Playback add-on XRequires that the Storage & Playback add-on is enabled for your key. See this page on enabling add-on features on your keys:

http://www.pubnub.com/knowledge-base/discussion/644/how-do-i-enable-add-on-features-for-my-keys.
Returns the number of messages published on one or more channels since a given time. The count returned is the number of messages in history with a timetoken value greater than the passed value in the timetokensparameter.
 For keys with unlimited message retention enabled, this method considers only messages published in the last 7 days.
You can use the following method(s) in the Swift SDK:
  1. ParameterTypeRequiredDefaultsDescription
    channels[String]YesThe channels to fetch the message count
    timetokens[Int]YesList with single or multiple timetokens, where each timetoken position in correspond to target channel location in channel names list.
    completion PNMessageCountCompletionBlockYesMessages count fetch completion closure which pass two arguments: result - in case of successful request processing data field will contain results of message count fetch operation; status - in case of error occurred during request processing.
let timetoken = NSNumber(value: (15501015683744028 as CUnsignedLongLong))
self.client.messageCounts().channels(["unread-channel-1", "unread-channel-2"])
    .timetokens([timetoken])
    .performWithCompletion({ (result, status) in
  
        if !status.isError {
            // Client state retrieved number of messages for channels.
        } else {
            /**
             Handle client state modification error. Check 'category' property
             to find out possible reason because of which request did fail.
             Review 'errorData' property (which has PNErrorData data type) of status
             object to get additional information about issue.
 
             Request can be resent using: status.retry()
            */
        }
    });
 Channels without messages have a count of 0. Channels with 10,000 messages or more have a count of 10000.
open class PNMessageCountData : PNServiceData {
     
    // Dictionary where each key is name of channel and value is number of messages in it.
    var channels: [String:Int] { get }
}
 
open class PNMessageCountResult : PNResult {
     
    // Message count request processing information.
    var data: PNMessageCountData { get }
}
  1. let timetoken = NSNumber(value: (15501015683744028 as CUnsignedLongLong))
    let timetoken2 = NSNumber(value: (15501015683744130 as CUnsignedLongLong))
    self.client.messageCounts().channels(["unread-channel-1", "unread-channel-2"])
        .timetokens([timetoken, timetoken2])
        .performWithCompletion({ (result, status) in
      
            if !status.isError {
                // Client state retrieved number of messages for channels.
            } else {
                /**
                 Handle client state modification error. Check 'category' property
                 to find out possible reason because of which request did fail.
                 Review 'errorData' property (which has PNErrorData data type) of status
                 object to get additional information about issue.
     
                 Request can be resent using: status.retry()
                */
            }
        });

Go to Mobile Push