SwiftSwift Native Storage & Playback API Reference for Realtime Apps

 
These docs are for the new PubNub Swift SDK written purely in Swift. To view the docs for the older version (the PubNub Objective-C SDK wrapper for Swift), have a look here.

The PubNub Storage and Playback Service provides real-time access to history for all messages published to PubNub. Each published message is timestamped to the nearest 10 nanoseconds, and is stored 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.

Messages can be stored for a configurable duration or forever, as controlled by the retention policy that is configured on your account. The following options are available: 1 day, 7 days, 1 month, and Forever.


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 from multiple channels. The includeMessageActions flag also allows you to fetch message actions along with the messages.

It's 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.
  • Search for messages from the oldest end of the timeline.
  • Page through results by providing a start OR end time token.
  • Retrieve a slice of the time line by providing both a start AND end time token.
  • Limit the number of messages to a specific quantity using the max parameter.

Batch history returns up to 25 messages per channel, on a maximum of 500 channels. Use the start and end timestamps to page through the next batch of messages.

Start and End parameter usage clarity

If you specify only the start parameter (without end), you will receive messages that are older than and up to that start timetoken.

If you specify only the end parameter (without start), you will receive messages from that end timetoken and newer.

Specify values for both start and end parameters to retrieve messages between those timetokens (inclusive of the end value).

Keep in mind that you will still receive a maximum of 25 messages even if there are more messages that meet the timetoken values. Iterative calls to history adjusting the start timetoken is necessary to page through the full set of results if more than 25 messages meet the timetoken values.

To run Fetch History, you can use the following method(s) in the Swift SDK:
  1. ParameterTypeRequiredDefaultDescription
    for[String]YesThe list of channels to fetch history messages from.
    fetchActionsBoolOptionalfalseInclude MessageAction in response.
    maxInt?Optional25The maximum number of messages to retrieve.
    Values over 25 are ignored.
    startTimetoken?OptionalnilTime token delimiting the start of time slice (exclusive) to pull messages from.
    endTimetoken?OptionalnilTime token delimiting the end of time slice (inclusive) to pull messages from.
    metaInResponseBoolOptionalfalseIf set to true the meta properties of messages will be returned as well (if existing).
Retrieve the last 25 messages on a channel:
pubnub.fetchMessageHistory(for: ["my_channel"]) { result in
  switch result {
  case let .success(response):
    print("Successful History Fetch Response: \(response)")
  case let .failure(error):
    print("Failed History Fetch Response: \(error.localizedDescription)")
  }
})
public typealias MessageHistoryChannelsPayload = [String: MessageHistoryChannelPayload]

public struct MessageHistoryChannelPayload: Codable {
  public let messages: [MessageHistoryMessagesPayload]
  public let startTimetoken: Timetoken
  public let endTimetoken: Timetoken
}

public struct MessageHistoryMessagesPayload: Codable {
  public let message: AnyJSON
  public let timetoken: Timetoken
  public let meta: AnyJSON?
  public let actions: [MessageActionPayload]
}

public struct MessageActionPayload: Codable, Hashable {
  public let uuid: String
  public let type: String
  public let value: String
  public let actionTimetoken: Timetoken
  public let messageTimetoken: Timetoken
}
  1. pubnub.fetchMessageHistory(
      for: ["channelSwift"],
      max: 25
    ) { result in
      switch result {
      case let .success(response):
        print("Successful History Fetch Response: \(response)")
      case let .failure(error):
        print("Failed History Fetch Response: \(error.localizedDescription)")
      }
    }
  2. pubnub.fetchMessageHistory(
      for: ["channelSwift"],
      end: 13406746780720711
    ) { result in
      switch result {
      case let .success(response):
        print("Successful History Fetch Response: \(response)")
      case let .failure(error):
        print("Failed History Fetch Response: \(error.localizedDescription)")
      }
    }
  3. pubnub.fetchMessageHistory(
      for: ["channelSwift"],
      start: 13406746780720711
    ) { result in
      switch result {
      case let .success(response):
        print("Successful History Fetch Response: \(response)")
      case let .failure(error):
        print("Failed History Fetch Response: \(error.localizedDescription)")
      }
    }
  4. pubnub.fetchMessageHistory(
      for: ["channelSwift", "otherChannel", "myChannel"],
      max: 25
    ) { result in
      switch result {
      case let .success(response):
        print("Successful History Fetch Response: \(response)")
      case let .failure(error):
        print("Failed History Fetch Response: \(error.localizedDescription)")
      }
    }
  5. pubnub.fetchMessageHistory(
      for: ["channelSwift"],
      metaInResponse: true
    ) { result in
      switch result {
      case let .success(response):
        print("Successful History Fetch Response: \(response)")
      case let .failure(error):
        print("Failed History Fetch Response: \(error.localizedDescription)")
      }
    }
  6. pubnub.fetchMessageHistory(
      for: ["channelSwift"],
      fetchActions: true
    ) { result in
      switch result {
      case let .success(response):
        print("Successful History Fetch Response: \(response)")
      case let .failure(error):
        print("Failed History Fetch Response: \(error.localizedDescription)")
      }
    }

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. ParameterTypeRequiredDefaultsDescription
    fromStringYesThe channel to delete the messages from.
    startTimetoken?OptionalnilTime token delimiting the start of time slice (inclusive) to delete messages from.
    endTimetoken?OptionalnilTime token delimiting the end of time slice (exclusive) to delete messages from.
pubnub.deleteMessageHistory(
  from: "channelSwift"
) { result in
  switch result {
  case let .success(response):
    print("Successful Message Deletion Response: \(response)")
  case let .failure(error):
    print("Failed Message Deletion Response: \(error.localizedDescription)")
  }
}
GenericServicePayloadResponse(
  message: PubNub.EndpointResponseMessage.acknowledge, 
  details: [], 
  service: "No Service Provided", 
  status: 200, 
  error: false, 
  channels: [:]
)
  1. pubnub.deleteMessageHistory(
      from: "channelSwift",
      start: 15526611838554309,
      end: 15526611838554310
    ) { result in
      switch result {
      case let .success(response):
        print("Successful Message Deletion Response: \(response)")
      case let .failure(error):
        print("Failed Message Deletion Response: \(error.localizedDescription)")
      }
    }

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 timetokenparameter.
 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. ParameterTypeRequiredDescription
    channels[String: Timetoken]YesThe map of channels and the timetoken to get the message count for.
  2. ParameterTypeRequiredDefaultsDescription
    channels[String]YesThe list of channels to get message counts for.
    timetokenTimetokenOptional1The timetoken for all channels in the list to get message counts for.
pubnub.messageCounts(channels: ["channelSwift"]) { result in
  switch result {
  case let .success(response):
    print("Successful Message Count Response: \(response)")
  case let .failure(error):
    print("Failed Message Count Response: \(error.localizedDescription)")
  }
}
// Channel and that channel's message count
[String: Int]
  1. pubnub.messageCounts(
      channels: ["channelSwift", "otherChannel", "myChannel"],
      timetoken: 15526611838554310
    ) { result in
      switch result {
      case let .success(response):
        print("Successful Message Count Response: \(response)")
      case let .failure(error):
        print("Failed Message Count Response: \(error.localizedDescription)")
      }
    }
  2. pubnub.messageCounts(
      channels: [
        "channelSwift": 15526611838554310,
        "otherChannel": 15526611838554309,
        "myChannel": 1
      ]
    ) { result in
      switch result {
      case let .success(response):
        print("Successful Message Count Response: \(response)")
      case let .failure(error):
        print("Failed Message Count Response: \(error.localizedDescription)")
      }
    }