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:
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.
The PubNub APIs and Events return network data that can be stored directly in Core Data using the appropriate
DataProvider
methods found insideChatProvider
.The UI Components use
NSFetchedResultsController
to createNSPredicate
against the stored (managed) data. This controller automatically updates the component's data source if the new matching data is added, updated, or removed.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. |