Data components

Data components are responsible for managing data between the UI Components and the persistence layer. They also interact with the PubNub service by sending and receiving messages and signals.

Available components include:

• Channel Data
• User Data
• Member Data
• Message Data

Overview

PubNub Chat Components for iOS utilize several layers of configurable data to drive the functionality found in the UI Components. The goal of the data layer is to provide a simple and robust foundation that can be used across any chat implementation. The two main forms of data used by the components are managed and network objects.

Managed data

PubNub Chat Components for iOS rely on Core Data - an Apple framework to manage the model layer of the application - to provide a persistent, abstracted, and reliable local state to the UI Components.

This is achieved by defining data schemas and relationships inside a Managed Object Model. There is also a pre-configured set of managed entities provided by default to support rapid prototyping.

Network data

A drawback of using Core Data managed objects is they can only be handled on the main queue of the application. To avoid any issues or errors while using concurrency, the managed objects are able to be converted to and from network object types. The objects attempt to mirror the default managed object schema, but can be further customized to match any schema that's needed by the application.

Network objects are most commonly used when interacting with PubNub APIs, but should be used whenever the applications might use multiple threads.

Data flow

The typical data flow through the components revolves around storing incoming data into the Core Data instance and updating that data automatically in UI Components if the data matches the UI Components population query.

1. The PubNub APIs and Events return network data that can be stored directly in Core Data using the appropriate DataProvider methods found inside ChatProvider.

2. The UI Components use NSFetchedResultsController to create NSPredicate against the stored (managed) data. This controller automatically updates the component's data source if the new matching data is added, updated, or removed.

3. The UI Components provide actions that can be configured to call PubNub APIs through DataProvider or update existing objects and store the result.

Channel

A channel is commonly viewed as a collection of associated users with a specific purpose or goal. A channel could be created for direct communication between two or more users, a group of users, or other use-case specific scenarios.

Managed data

The default Managed Object Model inside the Chat Components defines a Core Data NSManagedObject named PubNubManagedChannel.

If a custom Managed Object Model is used, a NSManagedObject entity must implement the ManagedChatChannel protocol before it can be used by the Chat Components framework.

Managed channel

The PubNubManagedChannel entity is defined with the following attributes:

Name	Type	Description
id	String	Unique identifier for the object.
type	String	Functional type of the channel. Common examples are common and group.
name	String?	Name of the channel.
details	String?	Channel details you can display alongside the name.
avatarURL	URL?	Image you can use to visually represent the channel.
custom	Data	Custom key value pairs that can be stored with the channel.
lastUpdated	Date?	Last time the remote object was changed.
eTag	String?	Caching value that changes whenever the remote object changes.

Relationships

The PubNubManagedChannel entity has relationships with the following entities:

Name	Type	Description
members	Set<PubNubManagedMember>	Entity that connects to the users of a channel.
messages	Set<PubNubManagedMessage>	Entity that connects to the messages of a channel.

Managed channel protocol

To allow for a custom Managed Object Model, the ManagedChatChannel protocol is used when referring to the managed object.

The protocol requires the following properties and methods:

• pubnubChannelID

Identifier used when interacting with PubNub APIs. It can be different from the primary key ID used by the managed object.

var pubnubChannelID: String { get }

• convert()

Converts the managed object to a network object with the appropriately typed custom channel data.

func convert<Custom: ChannelCustomData>() -> ChatChannel<Custom>

Returns

The base network object transformed to use the specified ChannelCustomData.

• insertOrUpdate(channel:into:)

Inserts or updates the managed object from a network object.

@discardableResult
static func insertOrUpdate<Custom: ChannelCustomData>(
  channel: ChatChannel<Custom>,
  into context: NSManagedObjectContext
) throws -> Self

Parameters

Name	Type	Description
channel	ChatChannel<ChannelCustomData>	ChatChannel to be updated or inserted.
into	NSManagedObjectContext	Core Data context where the object is inserted or updated.

Returns

The managed object that was inserted or updated.

Observing the NSManagedObjectContextDidSave notification will indicate whether a new managed object was created or an existing object was updated.

• remove(channelId:from:)

Removes a managed object matching the channelId parameter.

@discardableResult
static func remove(
  channelId: String,
  from context: NSManagedObjectContext
) -> Self?

Parameters

Name	Type	Description
channelId	String	Unique identifier for the channel.
from	NSManagedObjectContext	Core Data context where the object is removed.

Returns

The managed object that was removed.

Observing the NSManagedObjectContextDidSave notification will indicate whether a managed object was removed.

• channelBy(channelID:)

Creates NSFetchRequest that gets a channel matching the channelId parameter.

static func channelBy(channelID: String) -> NSFetchRequest<Self>

Parameters

Name	Type	Description
channelID	String	Unique identifier for the channel.

Returns

NSFetchRequest whose predicate is set to get the channel that matches the channelID parameter.

Network data

The generic ChatChannel class implements the PubNubChannelMetadata protocol that can be used whenever a Swift PubNub API requires a Channel object.

Name	Type	Description
id	String	Unique identifier for the object.
type	String	Functional type of the channel. Common examples would be common and group.
name	String	Name of the channel.
details	String?	Channel details you can display alongside the name.
avatarURL	URL?	Image you can use to visually represent the channel.
customChannel	ChannelCustomData	Custom key value pairs that can be stored with the channel.
lastUpdated	Date?	Last time the remote object was changed.
eTag	String?	Caching value that changes whenever the remote object changes.

Custom channel data

Use the ChannelCustomData protocol to provide custom data to the generic ChatChannel class. This protocol is implemented by an object that can be represented as a flat JSON structure through the use of the Codable protocol.

By default, all custom data is implemented as an empty object VoidCustomData.

The default implementation of ChatChannel is a typealias of the following:

public typealias PubNubChatChannel = ChatChannel<VoidCustomData>

Data provider actions

DataProvider contains several convenience methods that streamline the ability to fetch and manage channel data. You can access DataProvider through ChatProvider.

• load()

Inserts or updates a list of channels in the Core Data store batching based on the supplied batchSize.

public func load(
  channels: [ChatChannel<ChannelCustomData>],
  batchSize: Int = 256,
  batchHandler: (([ChatChannel<ChannelCustomData>], Error?) -> Void)? = nil,
  completion: (() -> Void)? = nil
)

Parameters

Name	Type	Description
channels	[ChatChannel<ChannelCustomData>]	Channels to store.
batchSize	Int	Size of each chunk of channels to store.
batchHandler	(([ChatChannel<ChannelCustomData>], Error?) -> Void)?	Closure called after storing each batch.
completion	(() -> Void)?	Closure called after storing all channels.

• removeStoredChannel()

Removes a managed channel matching the supplied channelId.

public func removeStoredChannel(
  channelId: String,
  completion: ((Error?) -> Void)? = nil
)

Parameters

Name	Type	Description
channelId	String	Unique identifier for the channel.
completion	((Error?) -> Void)?	Closure called after removing the channel.

• syncRemoteChannel()

Calls the fetch(channel:) PubNub endpoint and stores the response inside the Core Data store.

public func syncRemoteChannel(
  _ request: ObjectMetadataIdRequest,
  completion: ((Result<ChatChannel<ChannelCustomData>, Error>) -> Void)? = nil
)

Parameters

Name	Type	Description
_ request	ObjectMetadataIdRequest	Request object that sets the PubNub API method parameters.
completion	((Result<ChatChannel<ChannelCustomData>, Error>) -> Void)?	Result of either the fetched and stored channel or an Error.

• syncAllRemoteChannels()

Calls the allChannelMetadata() PubNub endpoint and stores the response inside the Core Data store.

public func syncAllRemoteChannels(
  _ request: ObjectsFetchRequest,
  completion: ((Result<(channels: [ChatChannel<ChannelCustomData>], next: ObjectsFetchRequest?), Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	ObjectsFetchRequest	Request object that sets the PubNub API method parameters.
completion	((Result<(channels: [ChatChannel<ChannelCustomData>], next: ObjectsFetchRequest?), Error>) -> Void)?	Result of either the fetched and stored channels (with the next request for pagination) or an Error.

• setRemoteChannel()

Calls the set(channel:) PubNub endpoint and stores the response inside the Core Data store.

public func setRemoteChannel(
  _ request: ChannelMetadataRequest<ChannelCustomData>,
  completion: ((Result<ChatChannel<ChannelCustomData>, Error>) -> Void)? = nil
)

Parameters

Name	Type	Description
_ request	ChannelMetadataRequest<ChannelCustomData>	Request object that sets the PubNub API method parameters.
completion	((Result<ChatChannel<ChannelCustomData>, Error>) -> Void)?	Result of either the fetched and stored channel or an Error.

• removeRemoteChannel()

Calls the remove(channel:) PubNub endpoint and stores the response inside the Core Data store.

public func removeRemoteChannel(
  _ request: ObjectRemoveRequest,
  completion: ((Result<String, Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	ObjectRemoveRequest	Request object that sets the PubNub API method parameters.
completion	((Result<String, Error>) -> Void)?	Result of either the removed channelId or an Error.

User

A user is an individual that's using the chat application and can be associated with both channels (through members) and messages.

Managed data

The default Managed Object Model inside the Chat Components defines a Core Data NSManagedObject named PubNubManagedUser.

If a custom Managed Object Model is used, then a NSManagedObject entity must implement the ManagedChatUser protocol before it can be used by the Chat Components framework.

Managed user

The PubNubManagedUser entity is defined with the following attributes:

Name	Type	Description
id	String	Unique identifier for the object.
name	String?	Name of the channel.
occupation	String?	Role or title of the user.
email	String?	Email address for the user.
externalId	String?	External identifier for the object.
avatarURL	URL?	Image you can use to visually represent the user.
custom	Data	Custom key value pairs that can be stored with the user.
lastUpdated	Date?	Last time the remote object was changed.
eTag	String?	Caching value that changes whenever the remote object changes.

Relationships

The PubNubManagedUser entity has relationships with the following entities:

Name	Type	Description
memberships	Set<PubNubManagedMember>	Entity that connects to the users of a channel.
messages	Set<PubNubManagedMessage>	Entity that connects to the messages of a channel.

Managed user protocol

To allow for a custom Managed Object Model, the ManagedChatUser protocol is used when referring to the managed object.

The protocol requires the following properties and methods:

• pubnubUserID

Identifier used when interacting with PubNub APIs. It can be different from the primary key ID used by the managed object.

var pubnubUserID: String { get }

• convert()

Converts the managed object to a network object with the appropriately typed custom user data.

func convert<Custom: UserCustomData>() -> ChatUser<Custom>

Returns

The base network object transformed to use the specified UserCustomData.

• insertOrUpdate(user:into:)

Inserts or updates the managed object from a network object.

@discardableResult
static func insertOrUpdate<Custom: UserCustomData>(
  user: ChatUser<Custom>,
  into context: NSManagedObjectContext
) throws -> Self

Parameters

Name	Type	Description
user	ChatUser<UserCustomData>	ChatUser to be updated or inserted.
into	NSManagedObjectContext	Core Data context where the object is inserted or updated.

Returns

The managed object that was inserted or updated.

Observing the NSManagedObjectContextDidSave notification will indicate whether a new managed object was created or an existing object was updated.

• remove(userId:from:)

Removes a managed object matching the userId parameter.

@discardableResult
static func remove(
  userId: String,
  from context: NSManagedObjectContext
) -> Self?

Parameters

Name	Type	Description
userId	String	Unique identifier for the user.
from	NSManagedObjectContext	Core Data context where the object is removed.

Returns

The managed object that was removed.

Observing the NSManagedObjectContextDidSave notification will indicate whether a managed object was removed.

• userBy(userId:)

Creates NSFetchRequest that gets ManagedChatUser matching the userId parameter.

static func userBy(userId: String) -> NSFetchRequest<Self>

Parameters

Name	Type	Description
userId	String	Unique identifier for ManagedChatUser.

Returns

NSFetchRequest whose predicate is set to get ManagedChatUser that matches the userId parameter.

Network data

The generic ChatUser class implements the PubNubUserMetadata protocol that can be used whenever a Swift PubNub API requires a User object.

Name	Type	Description
id	String	Unique identifier for the object.
name	String?	Name of the channel.
occupation	String?	Role or title of the user.
email	String?	Email address for the user.
externalId	String?	External identifier for the object.
avatarURL	URL?	Image you can use to visually represent the user.
customUser	UserCustomData	Custom key value pairs that can be stored with the user.
lastUpdated	Date?	Last time the remote object was changed.
eTag	String?	Caching value that changes whenever the remote object changes.

Custom user data

Use the UserCustomData protocol to provide custom data to the generic ChatUser class. This protocol is implemented by an object that can be represented as a flat JSON structure through the use of the Codable protocol.

By default, all custom data is implemented as as an empty object VoidCustomData.

The default implementation of ChatUser is a typealias of the following:

public typealias PubNubChatUser = ChatUser<VoidCustomData>

Data provider actions

DataProvider contains several convenience methods that streamline the ability to fetch and manage user data. You can DataProvider through ChatProvider,

• load()

Insets or updates a list of users in the Core Data store batching based on the supplied batchSize.

public func load(
  users: [ChatUser<UserCustomData>],
  batchSize: Int = 256,
  batchHandler: (([ChatUser<UserCustomData>], Error?) -> Void)? = nil,
  completion: (() -> Void)? = nil
)

Parameters

Name	Type	Description
users	[ChatUser<UserCustomData>]	Users to store.
batchSize	Int	Size of each chunk of users to store.
batchHandler	(([ChatUser<UserCustomData>], Error?) -> Void)?	Closure called after storing each batch.
completion	(() -> Void)?	Closure called after storing all users.

• removeStoredUser()

Removes a managed user matching the supplied userId.

public func removeStoredUser(
  userId: String,
  completion: ((Error?) -> Void)? = nil
)

Parameters

Name	Type	Description
userId	String	Unique identifier for the user.
completion	((Error?) -> Void)?	Closure called after removing the user.

• syncRemoteUser()

Calls the fetch(user:) PubNub endpoint and stores the response inside the Core Data store.

public func syncRemoteUser(
  _ request: ObjectMetadataIdRequest,
  completion: ((Result<ChatUser<UserCustomData>, Error>) -> Void)? = nil
)

Parameters

Name	Type	Description
_ request	ObjectMetadataIdRequest	Request object that sets the PubNub API method parameters.
completion	((Result<ChatUser<UserCustomData>, Error>) -> Void)?	Result of either the fetched and stored user or an Error.

• syncAllRemoteUsers()

Calls the allUserMetadata() PubNub endpoint and stores the response inside the Core Data store.

public func syncAllRemoteUsers(
  _ request: ObjectsFetchRequest,
  completion: ((Result<(channels: [ChatUser<UserCustomData>], next: ObjectsFetchRequest?), Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	ObjectsFetchRequest	Request object that sets the PubNub API method parameters.
completion	((Result<(channels: [ChatUser<UserCustomData>], next: ObjectsFetchRequest?), Error>) -> Void)?	Result of either the fetched and stored users (with the next request for pagination) or an Error.

• setRemoteUser()

Calls the set(user:) PubNub endpoint and stores the response inside the Core Data store.

public func setRemoteUser(
  _ request: UserMetadataRequest<UserCustomData>,
  completion: ((Result<ChatUser<UserCustomData>, Error>) -> Void)? = nil
)

Parameters

Name	Type	Description
_ request	UserMetadataRequest<UserCustomData>	Request object that sets the PubNub API method parameters.
completion	((Result<ChatUser<UserCustomData>, Error>) -> Void)?	Result of either the fetched and stored user or an Error.

• removeRemoteUser()

Calls the remove(user:) PubNub endpoint and stores the response inside the Core Data store.

public func removeRemoteUser(
  _ request: ObjectRemoveRequest,
  completion: ((Result<String, Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	ObjectRemoveRequest	Request object that sets the PubNub API method parameters.
completion	((Result<String, Error>) -> Void)?	Result of either the removed userId or an Error.

Member

The users that are associated with a channel are also known as its members. A user might have many channel memberships and a channel might have multiple members.

Managed data

The default Managed Object Model inside the Chat Components defines a Core Data NSManagedObject named PubNubManagedMember.

If a custom Managed Object Model is used, a NSManagedObject entity must implement the ManagedChatMember protocol before it can be used by the Chat Components framework.

Managed member

The PubNubManagedMember entity is defined with the following attributes:

Name	Type	Description
id	String	Unique identifier for the object.
custom	Data	Custom key value pairs that can be stored with the user.
isPresent	Bool	Presence status of the user on the channel.
presenceState	Data?	Presence state of the user on the channel.
channelId	String	Denormalized channel identifier that's derived from the channel relationship entity.
userId	String	Denormalized user identifier that's derived from the user relationship entity.

Relationships

The PubNubManagedMember entity has relationships with the following entities:

Name	Type	Description
user	PubNubManagedUser	Entity that connects to the user.
channel	PubNubManagedChannel	Entity that connects to the channel.

Managed member protocol

To allow for a custom Managed Object Model, the ManagedChatMember protocol is used when referring to the managed object.

The protocol requires the following properties and methods:

• convert()

Converts the managed object to a network object with the appropriately typed Custom Chat data.

func convert<Custom: ChatCustomData>() -> ChatMember<Custom>

Returns

The base network object transformed to use the specified ChatCustomData.

• insertOrUpdate(member:into:)

Inserts or updates the managed object from a network object.

@discardableResult
static func insertOrUpdate<Custom: ChatCustomData>(
  member: ChatMember<Custom>,
  into context: NSManagedObjectContext
) throws -> Self

Parameters

Name	Type	Description
member	ChatMember<ChatCustomData>	ChatMember to be updated or inserted.
into	NSManagedObjectContext	Core Data context where the object is inserted or updated.

Returns

The managed object that was inserted or updated.

Observing the NSManagedObjectContextDidSave notification will indicate whether a new managed object was created or an existing object was updated.

• remove(channelId:userId:from:)

Removes a managed object matching the channelId parameter.

@discardableResult
static func remove(
  channelId: String,
  userId: String,
  from context: NSManagedObjectContext
) -> Self?

Parameters

Name	Type	Description
channelId	String	Unique identifier for the channel.
userId	String	Unique identifier for the user.
from	NSManagedObjectContext	Core Data context where the object is removed.

Returns

The managed object that was removed.

Observing the NSManagedObjectContextDidSave notification will indicate whether a managed object was removed.

• membershipsBy(userId:)

Creates NSFetchRequest that gets ManagedChatMember whose connected ManagedChatUser has the userId passed as the parameter.

static func membershipsBy(userId: String) -> NSFetchRequest<Self>

Parameters

Name	Type	Description
userId	String	Unique identifier for ManagedChatUser.

Returns

NSFetchRequest whose predicate is set to get ManagedChatMember that matches the userId of the connected ManagedChatUser.

• membersBy(channelID:excludingUserId:onlyPresent)

Creates NSFetchRequest that gets a list of ManagedChatMember for a specific ManagedChatChannel.

static func membersBy(channelID: String, excludingUserId: String?, onlyPresent: Bool) -> NSFetchRequest<Self>

Parameters

Name	Type	Description
channelID	String	Unique identifier for ManagedChatChannel.
excludingUserId	String?	Optional user identifier to be excluded. You can use it to remove the current user from a predicate.
onlyPresent	Bool	Whether the predicate should return only these channel members that are online.

Returns

NSFetchRequest whose predicate is set to a list of ManagedChatMember for a specific ManagedChatChannel.

• memberBy(pubnubChannelId:pubnubUserId:)

Creates NSFetchRequest that gets ManagedChatMember for specific ManagedChatChannel and ManagedChatUser using their PubNub identifiers.

static func memberBy(pubnubChannelId: String, pubnubUserId: String) -> NSFetchRequest<Self>

Parameters

Name	Type	Description
pubnubChannelId	String	Unique PubNub identifier for ManagedChatChannel.
pubnubUserId	String	Unique PubNub identifier for ManagedChatUser.

Returns

NSFetchRequest whose predicate is set to get ManagedChatMember for specific ManagedChatChannel and ManagedChatUser using their PubNub identifiers.

Network data

The generic ChatMember class implements the PubNubMembershipMetadata protocol that can be used whenever a Swift PubNub API requires a Member or Membership object.

Name	Type	Description
id	String	Computed property that's a combination of pubnubChannelId and pubnubUserId.
pubnubChannelId	String	Unique identifier for the channel.
pubnubUserId	String	Unique identifier for the user.
customMember	MemberCustomData	Custom key value pairs that can be stored with the member.
chatChannel	ChatChannel<ChannelCustomData>?	Optional ChatChannel object that should match pubnubChannelId.
chatUser	ChatUser<UserCustomData>?	Optional ChatUser object that should match pubnubUserId.
lastUpdated	Date?	Last time the remote object was changed.
eTag	String?	Caching value that changes whenever the remote object changes.
presence	MembershipPresence?	Presence status and state information for ChatMember.

Custom chat data

Use the ChatCustomData and MemberCustomData protocols to provide custom data to the generic ChatMember class. ChatMember can have its own custom data set by using the MemberCustomData protocol. To allow for generic type adherence for both ChatUser and ChatChannel properties, the ChatCustomData protocol is required. Both protocols are implemented by an object that can be represented as a flat JSON structure through the use of the Codable protocol.

By default, all custom data is implemented as an empty object VoidCustomData.

The default implementation of ChatMember is a typealias of the following:

public typealias PubNubChatMember = ChatMember<VoidCustomData>

Data provider actions

DataProvider contains several convenience methods that streamline the ability to fetch and manage member data. DataProvider. You can access DataProvider through ChatProvider.

• load(members:batchSize:batchHandler:completion)

Inserts or updates a list of members in the Core Data store batching based on the supplied batchSize.

public func load(
  members: [ChatMember<ModelData>],
  batchSize: Int = 256,
  batchHandler: (([ChatMember<ModelData>], Error?) -> Void)? = nil,
  completion: (() -> Void)? = nil
)

Parameters

Name	Type	Description
members	[ChatMember<ChatCustomData>]	Members to store.
batchSize	Int	Size of each chunk of members to store.
batchHandler	(([ChatUser<UserCustomData>], Error?) -> Void)?	Closure called after storing each batch.
completion	(() -> Void)?	Closure called after storing all members.

• removeStoredMember(channelId:userId:completion:)

Removes a managed member matching the supplied channelId and userId.

public func removeStoredMember(
  channelId: String,
  userId: String,
  completion: ((Error?) -> Void)? = nil
)

Parameters

Name	Type	Description
channelId	String	Unique identifier for the channel.
userId	String	Unique identifier for the user.
completion	((Error?) -> Void)?	Closure called after removing the member.

• syncRemoteMembers(_:completion:)

Calls the fetchMembers() PubNub endpoint and stores the response inside the Core Data store.

public func syncRemoteMembers(
  _ request: MemberFetchRequest,
  completion: ((Result<([ChatMember<ModelData>], next: MemberFetchRequest?), Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	MemberFetchRequest	Request object that sets the PubNub API method parameters.
completion	((Result<([ChatMember<ChatCustomData>], next: MemberFetchRequest?), Error>) -> Void)?	Result of either the existing members that are stored locally ( with the next page of members) or an Error.

• syncRemoteMemberships(_:completion:)

Calls the fetchMemberships() PubNub endpoint and stores the response inside the Core Data store.

public func syncRemoteMemberships(
  _ request: MembershipFetchRequest,
  completion: ((Result<([ChatMember<ModelData>], next: MembershipFetchRequest?), Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	MembershipFetchRequest	Request object that sets the PubNub API method parameters.
completion	((Result<([ChatMember<ModelData>], next: MembershipFetchRequest?), Error>) -> Void)?	Result of either the existing members that are stored locally (with the next page of members) or an Error.

• setRemoteMembers(_:completion:)

Calls the setMembers() PubNub endpoint and stores the response inside the Core Data store.

public func setRemoteMembers(
  _ request: MemberModifyRequest,
  completion: ((Result<([ChatMember<ModelData>], next: MemberModifyRequest?), Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	MemberModifyRequest	Request object that sets the PubNub API method parameters.
completion	((Result<([ChatMember<ModelData>], next: MemberModifyRequest?), Error>) -> Void)?	Result of either the existing members that are stored locally (with the next page of members) or an Error.

• setRemoteMemberships(_:completion:)

Calls the setMemberships() PubNub endpoint and stores the response inside the Core Data store.

public func setRemoteMemberships(
  _ request: MembershipModifyRequest,
  completion: ((Result<([ChatMember<ModelData>], next: MembershipModifyRequest?), Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	MembershipModifyRequest	Request object that sets the PubNub API method parameters.
completion	((Result<([ChatMember<ModelData>], next: MembershipModifyRequest?), Error>) -> Void)?	Result of either the existing members that are stored locally (with the next page of members) or an Error.

• removeRemoteMembers(_:completion:)

Calls the removeMembers() PubNub endpoint and stores the response inside the Core Data store.

public func removeRemoteMembers(
  _ request: MemberModifyRequest,
  completion: ((Result<([ChatMember<ModelData>], next: MemberModifyRequest?), Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	MemberModifyRequest	Request object that sets the PubNub API method parameters.
completion	((Result<([ChatMember<ModelData>], next: MemberModifyRequest?), Error>) -> Void)?	Result of either the existing members that are stored locally (with the next page of members) or an Error.

• removeRemoteMemberships(_:completion:)

Calls the removeMemberships() PubNub endpoint and stores the response inside the Core Data store.

public func removeRemoteMemberships(
  _ request: MembershipModifyRequest,
  completion: ((Result<([ChatMember<ModelData>], next: MembershipModifyRequest?), Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	MembershipModifyRequest	Request object that sets the PubNub API method parameters.
completion	((Result<([ChatMember<ModelData>], next: MembershipModifyRequest?), Error>) -> Void)?	Result of either the existing members that are stored locally (with the next page of members) or an Error.

Message

A message is the dynamic content that a user sends to other users inside a channel.

Managed data

The default Managed Object Model inside the Chat Components defines a Core Data NSManagedObject named PubNubManagedMessage.

If a custom Managed Object Model is used, a NSManagedObject entity must implement the ManagedChatMessage protocol before it can be used by the Chat Components framework.

Managed message

The PubNubManagedMessage entity is defined with the following attributes:

Name	Type	Description
id	String	Unique identifier for the object.
timetoken	Timetoken	Int64 timestamp for the message.
dateCreated	Date	Local UTC date-time the message was created on the client.
dateSent	Date?	UTC date-time the message was successfully published to PubNub.
dateReceived	Date?	UTC date-time the message was received by the channel.
contentType	String	Type identifier of the message payload.
content	Data	Payload of the message.
custom	Data	Custom key value pairs that can be stored with the message.
pubnubChannelId	String	Denormalized channel identifier that's derived from the channel relationship entity.
pubnubUserId	String	Denormalized user identifier that's derived from the user relationship entity.

Relationships

The PubNubManagedMessage entity has relationships with the following entities:

Name	Type	Description
author	PubNubManagedUser	Entity that connects to the user.
channel	PubNubManagedChannel	Entity that connects to the channel.

Managed message protocol

To allow for a custom Managed Object Model, the ManagedChatMessage protocol is used when referring to the managed object.

The protocol requires the following properties and methods:

• pubnubMessageID

Identifier used when interacting with PubNub APIs.

var pubnubMessageID: Timetoken { get }

• convert()

Converts the managed object to a network object with the appropriately typed custom chat data.

  func convert<Custom: ChatCustomData>() throws -> ChatMessage<Custom>

Returns

The base network object transformed to use the specified ChatCustomData.

• insertOrUpdate(message:into:)

Inserts or updates the managed object from a network object.

@discardableResult
static func insertOrUpdate<Custom: ChatCustomData>(
  message: ChatMessage<Custom>,
  into context: NSManagedObjectContext
) throws -> Self

Parameters

Name	Type	Description
message	ChatMessage<ChatCustomData>	ChatMessage to be updated or inserted.
into	NSManagedObjectContext	Core Data context where the object is inserted or updated.

Returns

The managed object that was inserted or updated.

Observing the NSManagedObjectContextDidSave notification will indicate whether a new managed object was created or an existing object was updated.

• remove(messageId:from:)

Removes a managed object matching the messageId parameter.

@discardableResult
static func remove(
  messageId: String,
  from context: NSManagedObjectContext
) ->

Parameters

Name	Type	Description
messageId	String	Unique identifier for the message.
from	NSManagedObjectContext	Core Data context where the object is removed.

Returns

The managed object that was removed.

Observing the NSManagedObjectContextDidSave notification will indicate whether a managed object was removed.

• messagesBy(pubnubUserId:)

NSFetchRequest whose predicate is set to a list of ManagedChatMessage for a specific ManagedChatUser.

static func messagesBy(pubnubUserId: String) -> NSFetchRequest<Self>

Parameters

Name	Type	Description
pubnubUserId	String	Unique identifier for ManagedChatUser.

Returns

NSFetchRequest whose predicate is set to get a list of ManagedChatMessage for a specific ManagedChatUser.

• messagesBy(pubnubChannelId:)

NSFetchRequest whose predicate is set to a list of ManagedChatMessage for a specific ManagedChatChannel.

static func messagesBy(pubnubChannelId: String) -> NSFetchRequest<Self>

Parameters

Name	Type	Description
pubnubChannelId	String	Unique identifier for ManagedChatChannel.

Returns

NSFetchRequest whose predicate is set to get a list of ManagedChatMessage for a specific ManagedChatChannel.

• messagesBy(messageId:)

Creates NSFetchRequest that gets ManagedChatMessage matching the messageId parameter.

static func messagesBy(messageId: String) -> NSFetchRequest<Self>

Parameters

Name	Type	Description
messageId	String	Unique identifier for ManagedChatMessage.

Returns

NSFetchRequest whose predicate is set to get ManagedChatMessage matching the messageId parameter.

Network data

The generic ChatMessage class implements the PubNubMessage protocol so it can be used whenever a Swift PubNub API requires or supplies a PubNubMessage object.

Name	Type	Description
id	String	Unique identifier for the object.
timetoken	Timetoken	Int64 timestamp for the message.
dateCreated	Date	Local UTC date-time the message was created on the client.
dateSent	Date?	UTC date-time the message was successfully published to PubNub.
dateReceived	Date?	UTC date-time the message was received by the channel.
contentType	String	Type identifier of the message payload.
content	MessageContent	Payload of the message.
custom	MessageCustomData	Custom key value pairs that can be stored with the message.
pubnubUserId	String	Unique identifier for the user.
userModel	ChatUser<UserCustomData>?	Optional ChatUser object that should match pubnubUserId.
pubnubChannelId	String	Unique identifier for the channel.
channelModel	ChatChannel<ChannelCustomData>?	Optional ChatChannel object that should match pubnubChannelId.

Custom chat data

Use the ChatCustomData and MessageCustomData protocols to provide custom data to the generic ChatMessage class. ChatMessage can have its own custom data set by using the MessageCustomData protocol. To allow for generic type adherence for both ChatUser and ChatChannel properties, the ChatCustomData protocol is required. These protocols are implemented by an object that can be represented as a flat JSON structure through the use of the Codable protocol.

By default, all custom data is implemented as an empty object VoidCustomData.

The default implementation of ChatMember is a typealias of the following:

public typealias PubNubChatMessage = ChatMessage<VoidCustomData>

Data provider actions

DataProvider contains several convenience methods that streamline the ability to fetch and manage message data. You can access DataProvider through ChatProvider.

• load(messages:batchSize:batchHandler:completion)

Inserts or updates a list of messages in the Core Data store batching based on the supplied batchSize.

public func load(
  messages: [ChatMessage<ModelData>],
  batchSize: Int = 256,
  batchHandler: (([ChatMessage<ModelData>], Error?) -> Void)? = nil,
  completion: (() -> Void)? = nil
)

Parameters

Name	Type	Description
messages	[ChatMessage<ChatCustomData>]	Messages to store.
batchSize	Int	Size of each chunk of messages to store.
batchHandler	(([ChatUser<UserCustomData>], Error?) -> Void)?	Closure called after storing each batch.
completion	(() -> Void)?	Closure called after storing all messages.

• removeStoredMessage(messageId:completion:)

Removes a managed message matching the supplied messageId.

public func removeStoredMessage(
  messageId: String,
  completion: ((Error?) -> Void)? = nil
)

Parameters

Name	Type	Description
messageId	String	Unique identifier for the message.
completion	((Error?) -> Void)?	Closure called after removing the message.

• sendRemoteMessage(_:completion:)

Calls the publish() PubNub endpoint and stores the response inside the Core Data store.

public func sendRemoteMessage(
  _ request: SendMessageRequest<ChatCustomData>,
  completion: ((Result<ChatMessage<ModelData>, Error>) -> Void)?
)

Parameters

Name	Type	Description
_ request	SendMessageRequest<ChatCustomData>	Request object that sets the PubNub API method parameters.
completion	((Result<ChatMessage<ModelData>, Error>) -> Void)?	Result of either the published and stored message or an Error.

• syncRemoteMessages(_:completion:)

Calls the fetchMessageHistory() PubNub endpoint and stores the response inside the Core Data store.

public func syncRemoteMessages(
  _ request: MessageHistoryRequest,
  completion: ((Result<(messageByChannelId: [String: [ChatMessage<ModelData>]], next: MessageHistoryRequest?), PaginationError<MessageHistoryRequest>>) -> Void)?
)

Parameters

Name	Type	Description
_ request	MessageHistoryRequest	Request object that sets the PubNub API method parameters.
completion	((Result<(messageByChannelId: [String: [ChatMessage<ModelData>]], next: MessageHistoryRequest?), PaginationError<MessageHistoryRequest>>) -> Void)?	Result of either the existing messages that are stored locally (with the next page of messages) or PaginationError that contains MessageHistoryRequest that failed.