Data components for PubNub Chat Components for iOS

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 (with Message Reactions 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.

Data payloads

PubNub Chat Components for iOS enforce you to use the unified JSON schemas (data models) for such common entity types as users, channels, and messages when transferring data over the PubNub network. These common data payloads allow you to create cross-platform applications and ensure that such applications developed in different technologies (Swift, Kotlin, or JavaScript) communicate with one another properly, avoiding any unexpected errors.

Validate your payload

To avoid any parsing errors, validate the data payload you prepared for users, channels, and messages in an online validator.

Users

Follow this schema for the user data in your apps:

1{
2  "$schema": "https://json-schema.org/draft/2020-12/schema",
3  "title": "User",
4  "type": "object",
5  "description": "User of a chat application",
6  "properties": {
7    "id": {
8      "description": "Unique identifier for a user",
9      "type": "string"
10    },
11    "name": {
12      "description": "Name of the user that you can display in the UI",
13      "type": "string"
14    },
15    "email": {
16      "description": "User's email address",
17      "type": "string"
18    },
19    "externalId": {
20      "description": "Reference to user identifier from an external system",
21      "type": "string"
22    },
23    "profileUrl": {
24      "description": "URL to a user avatar that you can display in the UI",
25      "type": "string"
26    },
27    "type": {
28      "description": "Type of the user",
29      "type": "string",
30      "examples": ["default", "admin", "moderator"],
31      "default": "default"
32    },
33    "status": {
34      "description": "Status of the user",
35      "type": "string",
36      "examples": ["default", "deleted"]
37    },
38    "custom": {
39      "description": "Any additional payload information",
40      "type": "object",
41      "properties": {
42        "description": {
43          "description": "Description, job title, or some other information that you can display in the UI",
44          "type": "string"
45        }
46      }
47    },
48    "eTag": {
49      "description": "Identifier used for cache invalidation",
50      "type": "string"
51    },
52    "updated": {
53      "description": "ISO8601 date string of when the user has been last updated",
54      "type": "string"
55    },
56  },
57  "required": ["id", "type"]
58}

show all 58 lines

Example:

1{
2  "id": "some-user-id",
3  "name": "Jane Doe",
4  "email": "jane.doe@example.com",
5  "externalId": "some-external-user-id",
6  "profileUrl": "https://randomuser.me/api/portraits/men/1.jpg",
7  "type": "default",
8  "status": "default",
9  "custom": {
10    "description": "Office Assistant",
11  },
12  "eTag": "AYGyoY3gre71eA",
13  "updated": "2020-09-23T09:23:34.598494Z"
14}

Channels

Follow this schema for the channel data in your apps:

1{
2  "$schema": "https://json-schema.org/draft/2020-12/schema",
3  "title": "Channel",
4  "description": "Channel in the chat application",
5  "type": "object",
6  "properties": {
7    "id": {
8      "description": "Unique identifier for a channel",
9      "type": "string"
10    },
11    "name": {
12      "description": "Name of the channel that you can display in the UI",
13      "type": "string"
14    },
15    "description": {
16      "description": "Description of the channel that you can display in the UI",
17      "type": "string"
18    },
19    "type": {
20      "description": "Type of the channel",
21      "type": "string",
22      "examples": ["default", "group", "direct"],
23      "default": "default"
24    },
25    "status": {
26      "description": "Status of the channel",
27      "type": "string",
28      "examples": ["default", "deleted"]
29    },
30    "custom": {
31      "description": "Any additional payload information",
32      "type": "object",
33      "properties": {
34        "profileUrl": {
35          "description": "URL to a channel avatar that you can display in the UI",
36          "type": "string"
37        }
38      }
39    },
40    "eTag": {
41      "description": "Identifier used for cache invalidation",
42      "type": "string"
43    },
44    "updated": {
45      "description": "ISO8601 date string of when the channel has been last updated",
46      "type": "string"
47    },
48  },
49  "required": ["id", "type"]
50}

show all 50 lines

Example:

1{
2  "id": "some-channel-id",
3  "name": "Off-topic",
4  "description": "Off-topic channel for random chatter and fun",
5  "type": "default",
6  "status": "default",
7  "custom": {
8    "profileUrl": "https://www.gravatar.com/avatar/149e60f311749f2a7c6515f7b34?s=256&d=identicon"
9  },
10  "eTag": "AbOx6N+6vu3zoAE",
11  "updated": "2020-09-23T09:23:37.175764Z"
12}

Messages

Follow this schema for the message data in your apps:

Supported message types

PubNub Chat Components for iOS support only text message data types.

1{
2  "$schema": "https://json-schema.org/draft/2020-12/schema",
3  "title": "Message Content",
4  "description": "Message content in the chat application",
5  "type": "object",
6  "properties": {
7    "id": {
8      "description": "Unique identifier for a message. Use the UUID v4 algorithm.",
9      "type": "string"
10    },
11    "text": {
12      "description": "Text of the message that you can display in the UI",
13      "type": "string"
14    },
15    "contentType": {
16      "description": "If a message contains any extra content, this field describes its type. Currently, PubNub Chat Components support only text messages.",
17      "type": "string",
18      "examples": ["externalUrl", "imageUrl"]
19    },
20    "content": {
21      "description": "Extra content for the message. It can contain any feature-specific data like URLs to external images.",
22      "type": "object"
23    },
24    "createdAt": {
25      "description": "ISO8601 date string of when the message was created",
26      "type": "string"
27    },
28    "custom": {
29      "description": "Any additional payload information",
30      "type": "object"
31    }
32  },
33  "required": ["id", "text", "createdAt"]
34}

show all 34 lines

Example:

1{
2  "id": "6da72b98-e211-4724-aad4-e0fb9f08999f",
3  "text": "Let's sync on the topic in this thread.",
4  "contentType": "none",
5  "content": {},
6  "custom": {},
7  "createdAt": "2022-05-10T14:48:00.000Z"
8}

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, an NSManagedObject entity must implement the ManagedChatChannel protocol before it can be used by the Chat Components framework.

Managed channel

The PubNubManagedChannel entity is a CoreData managed Channel class used whenever a ChatChannel needs to be stored locally. It is defined with the following attributes:

Name	Type	Description
id	String	Unique identifier for the object.
name	String?	Name of the channel.
type	String	Functional type of the channel. The default value is set to "default".
status	String?	Status of the channel.
details	String?	Channel details you can display alongside the name.
avatarURL	URL?	URL to a channel avatar that you can display in the UI.
custom	Data	Custom key value pairs that can be stored with the channel.
lastUpdated	Date?	Last time the remote object was changed. This field references the updated field from ChatChannel.
eTag	String?	Caching value that changes whenever the remote object changes.
memberCount	Int	Total number of members that are currently active on the channel.

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.

  1var pubnubChannelID: String { get }

• convert()

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

  1func 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.

  1@discardableResult
  2static func insertOrUpdate<Custom: ChannelCustomData>(
  3  channel: ChatChannel<Custom>,
  4  into context: NSManagedObjectContext
  5) 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.

• patch(usingPatch:into:)

1@discardableResult
2static func patch<Custom: ChannelCustomData>(
3  usingPatch patcher: ChatChannel<Custom>.Patcher,
4  into context: NSManagedObjectContext
5) throws -> Self

Parameters

Name	Type	Description
usingPatch	ChatChannel<ChannelCustomData>.Patcher	ChatChannel.Patcher changeset that is applied to an existing channel if one exists.
into	NSManagedObjectContext	Core Data context where the object is inserted or updated.

Returns

The managed object that was updated.

Observing the NSManagedObjectContextDidSave notification will indicate whether an existing object was updated.

• remove(channelId:from:)

  Removes a managed object matching the channelId parameter.

  1@discardableResult
  2static func remove(
  3  channelId: String,
  4  from context: NSManagedObjectContext
  5) -> 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.

  1static 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 contains the channel payload fields and is used whenever a Swift PubNub API requires a Space object.

Name	Type	Description
id	String	Unique identifier for the object.
name	String?	Name of the channel.
type	String	Functional type of the channel. The default value is set to "default".
status	String?	Status of the channel.
details	String?	Channel details you can display alongside the name.
avatarURL	URL?	URL to a channel avatar that you can display in the UI. This field references the profileUrl field from the channel payload specification.
updated	Date?	Last time the remote object was changed.
eTag	String?	Caching value that changes whenever the remote object changes.
custom	ChannelCustomData	Custom key value pairs that can be stored with the channel.

Custom channel data

Implement the ChannelCustomData protocol to provide custom data to the generic ChatChannel class.

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

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

1public typealias PubNubChatChannel = ChatChannel<VoidCustomData>

APIs

• patch(:)

Patches the properties of an existing ChatUser from a real-time changeset.

1  public func patch(
2    _ patcher: ChatChannel<Custom>.Patcher
3  ) -> ChatChannel<Custom>

Parameters

Name	Type	Description
user	ChatChannel<Custom>.Patcher	Channel changeset that will be applied to an existing ChatChannel.

Returns

An updated ChatChannel if the Patcher was able to perform the update, otherwise the duplicate ChatChannel.

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.

  1public func load(
  2  channels: [ChatChannel<ModelData.Channel>],
  3  batchSize: Int = 256,
  4  batchHandler: (([ChatChannel<ModelData.Channel>], Error?) -> Void)? = nil,
  5  completion: (() -> Void)? = nil
  6)

Parameters

Name	Type	Description
channels	[ChatChannel<ModelData.Channel>]	Channels to store.
batchSize	Int	Size of each chunk of channels to store.
batchHandler	(([ChatChannel<ModelData.Channel>], 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.

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

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.

  1public func syncRemoteChannel(
  2  _ request: ChatChannelRequest<ModelData.Channel>,
  3  completion: ((Result<ChatChannel<ModelData.Channel>, Error>) -> Void)? = nil
  4)

Parameters

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

• syncRemoteChannelsPaginated()

Calls the fetchPagesPublisher(channels:) PubNub endpoint and stores the response inside the Core Data store.

1public func syncRemoteChannelsPaginated(
2  _ request: ChannelsFetchRequest,
3  pageHandler: (([ChatChannel<ModelData.Channel>], ChannelsFetchRequest?, Error?) -> Void)? = nil,
4  completion: ((PaginationError<ChannelsFetchRequest>?) -> Void)? = nil
5)

Parameters

Name	Type	Description
_ request	ChannelsFetchRequest	Request object that sets the PubNub API method parameters.
pageHandler	(([ChatChannel<ModelData.Channel>], ChannelsFetchRequest?, Error?) -> Void)?	The latest batch of ChatChannel that was fetched and stored.
completion	((PaginationError<ChannelsFetchRequest>?) -> Void)?	Result of either the fetched and stored channels (with the next request for pagination) or an Error.

• createRemoteChannel()

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

1public func createRemoteChannel(
2  _ request: ChatChannelRequest<ModelData.Channel>,
3  completion: ((Result<ChatChannel<ModelData.Channel>, Error>) -> Void)? = nil
4)

Parameters

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

• updateRemoteChannel()

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

1public func updateRemoteChannel(
2  _ request: ChatChannelRequest<ModelData.Channel>,
3  completion: ((Result<ChatChannel<ModelData.Channel>, Error>) -> Void)? = nil
4)

Parameters

Name	Type	Description
_ request	ChatChannelRequest<ModelData.Channel>	Request object that sets the PubNub API method parameters.
completion	((Result<ChatChannel<ModelData.Channel>, 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.

1public func removeRemoteChannel(
2  _ request: ChatChannelRequest<ModelData.Channel>,
3  completion: ((Result<Void, Error>) -> Void)?
4)

Parameters

Name	Type	Description
_ request	ChatChannelRequest<ModelData.Channel>	Request object that sets the PubNub API method parameters.
completion	((Result<Void, Error>) -> Void)?	Result of either the fetched and stored channel 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 an NSManagedObject entity must implement the ManagedChatUser protocol before it can be used by the Chat Components framework.

Managed user

The PubNubManagedUser entity is a CoreData managed User class used whenever a ChatUser needs to be stored locally. It is defined with the following attributes:

Name	Type	Description
id	String	Unique identifier for the object.
name	String?	Name of the channel.
type	String	Functional type of the user. The default value is set to "default".
status	String?	Status of the user.
externalId	String?	External identifier for the object.
avatarURL	URL?	URL to a user avatar that you can display in the UI.
email	String?	Email address for the user.
custom	Data	Custom key value pairs that can be stored with the user.
lastUpdated	Date?	Last time the remote object was changed. This field references the updated field from ChatUser.
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.

  1var pubnubUserID: String { get }

• convert()

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

  1func 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.

  1@discardableResult
  2static func insertOrUpdate<Custom: UserCustomData>(
  3  user: ChatUser<Custom>,
  4  into context: NSManagedObjectContext
  5) 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.

• patch(usingPatch:into:)

1@discardableResult
2static func patch<Custom: UserCustomData>(
3  usingPatch patcher: ChatUser<Custom>.Patcher,
4  into context: NSManagedObjectContext
5) throws -> Self

Parameters

Name	Type	Description
usingPatch	ChatUser<UserCustomData>.Patcher	ChatUser.Patcher changeset that is applied to an existing user if one exists.
into	NSManagedObjectContext	Core Data context where the object is inserted or updated.

Returns

The managed object that was updated.

Observing the NSManagedObjectContextDidSave notification will indicate whether an existing object was updated.

• remove(userId:from:)

  Removes a managed object matching the userId parameter.

  1@discardableResult
  2static func remove(
  3  userId: String,
  4  from context: NSManagedObjectContext
  5) -> 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.

  1static 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 contains the user payload fields and is 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.
type	String	Functional type of the user. The default value is set to "default".
status	String?	Status of the user.
externalId	String?	External identifier for the object.
avatarURL	URL?	URL to a user avatar that you can display in the UI. This field references the profileUrl field from the user payload specification.
email	String?	Email address for the user.
updated	Date?	Last time the remote object was changed.
eTag	String?	Caching value that changes whenever the remote object changes.
custom	UserCustomData	Custom key value pairs that can be stored with the user.

Custom user data

Implement the UserCustomData protocol to provide custom data to the generic ChatUser class.

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

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

1public typealias PubNubChatUser = ChatUser<VoidCustomData>

APIs

• patch(:)

Patches the properties of an existing ChatUser from a real-time changeset.

1  public func patch(
2    _ patcher: ChatUser<Customr>.Patcher
3  ) -> ChatUser<Custom>

Parameters

Name	Type	Description
user	ChatUser<Custom>.Patcher	User changeset that will be applied to an existing ChatUser.

Returns

An updated ChatUser if the Patcher was able to perform the update, otherwise the duplicate ChatUser.

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.

  1public func load(
  2  users: [ChatUser<ModelData.User>],
  3  batchSize: Int = 256,
  4  batchHandler: (([ChatUser<ModelData.User>], Error?) -> Void)? = nil,
  5  completion: (() -> Void)? = nil
  6)

Parameters

Name	Type	Description
users	[ChatUser<ModelData.User>]	Users to store.
batchSize	Int	Size of each chunk of users to store.
batchHandler	(([ChatUser<ModelData.User>], 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.

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

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.

1public func syncRemoteUser(
2  _ request: ChatUserRequest<ModelData.User>,
3  completion: ((Result<ChatUser<ModelData.User>, Error>) -> Void)? = nil
4)

Parameters

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

• syncRemoteUsers()

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

1public func syncRemoteUsers(
2  _ request: UsersFetchRequest,
3  completion: ((Result<(channels: [ChatUser<ModelData.User>], next: UsersFetchRequest?), Error>) -> Void)?
4)

Parameters

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

• syncRemoteUsersPaginated()

Calls the fetchPagesPublisher(users:) PubNub endpoint and stores the response inside the Core Data store.

1public func syncRemoteUsersPaginated(
2  _ request: UsersFetchRequest,
3  pageHandler: (([ChatUser<ModelData.User>], UsersFetchRequest?, Error?) -> Void)? = nil,
4  completion: ((PaginationError<UsersFetchRequest>?) -> Void)? = nil
5)

Parameters

Name	Type	Description
_ request	UsersFetchRequest	Request object that sets the PubNub API method parameters.
pageHandler	(([ChatUser<ModelData.User>], UsersFetchRequest?, Error?) -> Void)?	The latest batch of ChatUser that was fetched and stored.
completion	((PaginationError<UsersFetchRequest>?) -> Void)?	Result of either the fetched and stored users (with the next request for pagination) or an Error.

• createRemoteUser()

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

1public func createRemoteUser(
2  _ request: ChatUserRequest<ModelData.User>,
3  completion: ((Result<ChatUser<ModelData.User>, Error>) -> Void)? = nil
4)

Parameters

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

• updateRemoteUser()

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

1public func updateRemoteUser(
2  _ request: ChatUserRequest<ModelData.User>,
3  completion: ((Result<ChatUser<ModelData.User>, Error>) -> Void)? = nil
4)

Parameters

Name	Type	Description
_ request	ChatUserRequest<ModelData.User>	Request object that sets the PubNub API method parameters.
completion	((Result<ChatUser<ModelData.User>, 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.

1public func removeRemoteUser(
2  _ request: ChatUserRequest<ModelData.User>,
3  completion: ((Result<Void, Error>) -> Void)?
4)

Parameters

Name	Type	Description
_ request	ChatUserRequest<ModelData.User>	Request object that sets the PubNub API method parameters.
completion	((Result<Void, 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, an NSManagedObject entity must implement the ManagedChatMember protocol before it can be used by the Chat Components framework.

Managed member

The PubNubManagedMember entity is a CoreData managed Member class used whenever a ChatMember needs to be stored locally. It 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 member.
status	String?	Membership status.
lastUpdated	Date?	Last time the remote object was changed. This field references the updated field from ChatMember.
eTag	String?	Caching value that changes whenever the remote object changes.
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.

  1func 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.

1@discardableResult
2static func insertOrUpdate<Custom: ChatCustomData>(
3  member: ChatMember<Custom>,
4  forceWrite: Bool,
5  into context: NSManagedObjectContext
6) throws -> Self

Parameters

Name	Type	Description
member	ChatMember<ChatCustomData>	ChatMember to be updated or inserted.
forceWrite	Bool	Flag that defines if you want to override properties from PubNubManagedMember to those in ChatMember<ChatCustomData>. Set it to true if you want to insert a new membership that hasn't been synced with the PubNub server yet or if you want to override the channel and user properties for the already stored membership.
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.

• patch(usingPatch:into:)

1@discardableResult
2static func patch<Custom: ChatCustomData>(
3  usingPatch patcher: ChatMember<Custom>.Patcher,
4  into context: NSManagedObjectContext
5) throws -> Self

Parameters

Name	Type	Description
usingPatch	ChatMember<ChatCustomData>.Patcher	ChatUser.Patcher changeset that is applied to an existing member if one exists.
into	NSManagedObjectContext	Core Data context where the object is inserted or updated.

Returns

The managed object that was updated.

Observing the NSManagedObjectContextDidSave notification will indicate whether an existing object was updated.

• remove(channelId:userId:from:)

  Removes a managed object matching the channelId parameter.

  1@discardableResult
  2static func remove(
  3  channelId: String,
  4  userId: String,
  5  from context: NSManagedObjectContext
  6) -> 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.

  1static 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.

  1static 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.

  1static 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 is used whenever a Swift PubNub API requires a Membership object.

Name	Type	Description
chatChannel	ChatChannel<Custom.Channel>	Generic ChatChannel object linked to the user.
chatUser	ChatUser<Custom.User>	Generic ChatUser object linked to the channel.
status	String?	Membership status.
updated	Date?	Last time the remote object was changed.
eTag	String?	Caching value that changes whenever the remote object changes.
custom	Custom.Member	Custom key value pairs that can be stored with the user.
isPresent	Bool?	Presence status of the user on the channel.
presence	MembershipPresence?	Presence state of the user on the channel.

Custom chat data

Implement the ChatCustomData protocol to provide custom data to the generic Custom class. ChatCustomData.Member 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 can specify UserCustomData and ChannelCustomData implementations respectively.

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

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

1public 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.

  1public func load(
  2  members: [ChatMember<ModelData>],
  3  batchSize: Int = 256,
  4  forceWrite: Bool = true,
  5  batchHandler: (([ChatMember<ModelData>], Error?) -> Void)? = nil,
  6  completion: (() -> Void)? = nil
  7)

Parameters

Name	Type	Description
members	[ChatMember<ModelData>]	Members to store.
batchSize	Int	Size of each chunk of members to store.
forceWrite	Bool	Flag that defines if you want to override properties from PubNubManagedMember to those in ChatMember<ChatCustomData>. Set it to true if you want to insert a new membership that hasn't been synced with the PubNub server yet or if you want to override the channel and user properties for the already stored membership.
batchHandler	(([ChatMember<ModelData>], 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.

  1public func removeStoredMember(
  2  channelId: String,
  3  userId: String,
  4  completion: ((Error?) -> Void)? = nil
  5)

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.

• removeStoredMembers(members:batchSize:batchHandler:completion:)

Removes managed members matching the supplied members, batchSize, and batchHandler.

1public func removeStoredMembers(
2  members: [ChatMember<ModelData>],
3  userId: Int,
4  batchHandler: (([ChatMember<ModelData>], Error?) -> Void)? = nil,
5  completion: (() -> Void)? = nil
6)

Parameters

Name	Type	Description
members	[ChatMember<ModelData>]	Members to remove
batchSize	Int	Number of members to remove per batch.
batchHandler	(([ChatMember<ModelData>], Error?) -> Void)?	Closure called after storing each batch.
completion	(() -> Void)? = nil	Closure called after removing the members.

• syncRemoteUserMembers

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

1public func syncRemoteUserMembers(
2  _ request: UserMemberFetchRequest,
3  completion: ((Result<([ChatMember<ModelData>], next: UserMemberFetchRequest?), Error>) -> Void)?
4)

Parameters

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

• syncRemoteChannelMembers

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

1public func syncRemoteChannelMembers(
2  _ request: ChannelMemberFetchRequest,
3  completion: ((Result<([ChatMember<ModelData>], next: ChannelMemberFetchRequest?), Error>) -> Void)?
4)

Parameters

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

• syncRemoteUserMembersPagination

Calls the fetchPagesPublisher(userMembers:) PubNub endpoint and stores the response inside the Core Data store.

1public func syncRemoteUserMembersPagination(
2  _ request: UserMemberFetchRequest,
3  pageHandler: (([ChatMember<ModelData>], UserMemberFetchRequest?, Error?) -> Void)? = nil,
4  completion: ((PaginationError<UserMemberFetchRequest>?) -> Void)? = nil
5)

Parameters

Name	Type	Description
_ request	UserMemberFetchRequest	Request object that sets the PubNub API method parameters.
pageHandler	(([ChatMember<ModelData>], UserMemberFetchRequest?, Error?) -> Void)?	The latest batch of ChatMember that was fetched and stored.
completion	((PaginationError<UserMemberFetchRequest>?) -> Void)?	Result of either the existing members that are stored locally (with the next page of members) or an Error.

• syncRemoteChannelMembersPagination

Calls the fetchPagesPublisher(channelMembers:) PubNub endpoint and stores the response inside the Core Data store.

1public func syncRemoteChannelMembersPagination(
2  _ request: ChannelMemberFetchRequest,
3  pageHandler: (([ChatMember<ModelData>], ChannelMemberFetchRequest?, Error?) -> Void)? = nil,
4  completion: ((PaginationError<ChannelMemberFetchRequest>?) -> Void)? = nil
5)

Parameters

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

• createRemoteMembers

Calls the create(members:) PubNub endpoint and stores the response inside the Core Data store.

1public func createRemoteMembers(
2  _ request: MembersModifyRequest<ModelData>,
3  completion: ((Result<Void, Error>) -> Void)?
4)

Parameters

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

• updateRemoteMemberships

Calls the update(members:) PubNub endpoint and stores the response inside the Core Data store.

1public func updateRemoteMemberships(
2  _ request: MembersModifyRequest<ModelData>,
3  completion: ((Result<Void, Error>) -> Void)?
4)

Parameters

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

• removeRemoteMemberships

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

1public func removeRemoteMemberships(
2  _ request: MembersModifyRequest<ModelData>,
3  completion: ((Result<Void, Error>) -> Void)?
4)

Parameters

Name	Type	Description
_ request	MembersModifyRequest<ModelData>	Request object that sets the PubNub API method parameters.
completion	((Result<Void, 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, an NSManagedObject entity must implement the ManagedChatMessage protocol before it can be used by the Chat Components framework.

Managed message

The PubNubManagedMessage entity is a CoreData managed Message class used whenever a ChatMessage needs to be stored locally. It 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	ISO8601 date string of when the message was created. This attribute references the createdAt field from the message payload specification.
text	String	Text of the message.
contentType	String	Type identifier of the message payload. Currently, PubNub Chat Components support only text messages.
content	Data	Extra content for the message. Can contain any feature-specific data, like URLs to external images.
custom	Data	Custom key value pairs that can be stored with the message.
pubnubUserId	String	Denormalized user identifier that's derived from the user relationship entity.
pubnubChannelId	String	Denormalized channel identifier that's derived from the channel 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.

  1var pubnubMessageID: Timetoken { get }

• convert()

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

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

  1@discardableResult
  2static func insertOrUpdate<Custom: ChatCustomData>(
  3  message: ChatMessage<Custom>,
  4  processMessageActions: Bool,
  5  into context: NSManagedObjectContext
  6) throws -> Self

Parameters

Name	Type	Description
message	ChatMessage<ChatCustomData>	ChatMessage to be updated or inserted.
processMessageActions	Bool	Flag that defines if you want to insert or update message actions that belong to the given message.
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.

  1@discardableResult
  2static func remove(
  3  messageId: String,
  4  from context: NSManagedObjectContext
  5) ->

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.

  1static 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.

  1static 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.

• messageBy(messageId:)

  Creates NSFetchRequest that gets ManagedChatMessage matching the messageId parameter.

1static func messageBy(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. The ChatMessage class contains the message payload fields and is defined with the following attributes:

Name	Type	Description
id	String	Unique identifier for the object.
text	String	Text of the message.
contentType	String?	Type identifier of the message payload. Currently, PubNub Chat Components support only text messages.
content	JSONCodable?	Extra content for the message. Can contain any feature-specific data, like URLs to external images.
custom	Custom.Message	Custom key value pairs that can be stored with the message.
createdAt	Date	ISO8601 date string of when the message was created.
timetoken	Timetoken	Int64 timestamp for the message.
content	MessagePayload	Payload of the message.
pubnubUserId	String	Denormalized message sender identifier that's derived from the user relationship entity.
userModel	ChatUser<Custom.User>?	Optional ChatUser object that should match pubnubUserId.
pubnubChannelId	String	Denormalized channel identifier of the message sender that's derived from the channel relationship entity.
channelModel	ChatChannel<Custom.Channel>?	Optional ChatChannel object that should match pubnubChannelId.

Custom chat data

Implement the ChatCustomData protocol to provide custom data to the generic Custom class. ChatCustomData.Message 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 can specify UserCustomData and ChannelCustomData implementations respectively.

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

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

1public 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:processMessageActions:batchSize:batchHandler:completion)

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

  1public func load(
  2  messages: [ChatMessage<ModelData>],
  3  processMessageActions: Bool,
  4  batchSize: Int = 256,
  5  batchHandler: (([ChatMessage<ModelData>], Error?) -> Void)? = nil,
  6  completion: (() -> Void)? = nil
  7)

Parameters

Name	Type	Description
messages	[ChatMessage<ModelData>]	Messages to store.
processMessageActions	Bool	Message reactions to store.
batchSize	Int	Size of each chunk of messages to store.
batchHandler	(([ChatUser<ModelData>], 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.

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

Parameters

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

• sendRemoteMessage

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

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

Parameters

Name	Type	Description
_ request	SendMessageRequest<ModelData>	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

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

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

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.

Message Reactions

A message reaction is an emoji that a user adds to a message to react to it.

Managed data

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

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

Managed message reaction

The PubNubManagedMessageAction entity is defined with the following attributes:

Name	Type	Description
id	String	Unique identifier for the object.
published	Timetoken	Publish timetoken of the message action.
sourceType	String	Message action's type.
value	String	Message action's value.
pubnubParentTimetoken	Timetoken	Timetoken of the message that this action belongs to.
pubnubParentId	String	ID of the message that this action belongs to.
pubnubUserId	String	Publisher of the message action.

Relationships

The PubNubManagedMessageAction entity has relationships with the following entities:

Name	Type	Description
author	PubNubManagedUser	Entity that connects to the user.
parent	PubNubManagedMessage	Entity that connects to the message.

Managed message reaction protocol

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

The protocol requires the following properties and methods:

• pubnubActionTimetoken

  Identifier used when interacting with PubNub APIs.

  1var pubnubActionTimetoken: Timetoken { get }

• convert()

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

  1public func convert<Custom: ChatCustomData>() throws -> ChatMessageAction<Custom>

Returns

The base network object transformed to use the specified ChatCustomData.

• insertOrUpdate(messageAction:into:)

  Inserts or updates the managed object from a network object.

  1public static func insertOrUpdate<Custom: ChatCustomData>(
  2  messageAction: ChatMessageAction<Custom>,
  3  into context: NSManagedObjectContext
  4)

Parameters

Name	Type	Description
messageAction	ChatMessageAction<Custom>	ChatMessageAction 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.

• insertOrUpdate(messageAction:into:)

  Inserts the managed object from a network object.

  1public static func insert<Custom: ChatCustomData>(
  2  messageAction: ChatMessageAction<Custom>,
  3  into context: NSManagedObjectContext
  4)

Parameters

Name	Type	Description
messageAction	ChatMessageAction<Custom>	ChatMessageAction to be inserted.
into	NSManagedObjectContext	Core Data context where the object is insertedd.

Returns

The managed object that was inserted.

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

• remove(messageActionId:from:)

  Removes the managed object from a network object.

  1@discardableResult
  2public static func remove(
  3  messageActionId: String,
  4  from context: NSManagedObjectContext
  5) -> Self

Parameters

Name	Type	Description
messageActionId	String	messageActionId to be removed.
into	NSManagedObjectContext	Core Data context where the object is removed.

Returns

The managed object that was removed.

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

Network data

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

Name	Type	Description
actionTimetoken	Timetoken	Publish timetoken of the message action.
parentTimetoken	Timetoken	Timetoken of the message that this action belongs to.
sourceType	String	Message action's type.
value	String	Message action's value.
pubnubUserId	String	Publisher of the message action.
userModel	ChatUser<CustomData.User>?	Optional ChatUser object that should match pubnubUserId.
pubnubChannelId	String	ID of the channel that the message and its message action belongs to.
messageModel	ChatMessage<CustomData>?	Optional ChatMessage object that should match parentTimetoken.

Data provider actions

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

• sendRemoteMessageAction(_:completion:)

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

  1public func sendRemoteMessageAction(
  2  _ request: MessageActionSendRequest<ModelData>,
  3  completion: ((Result<ChatMessageAction<ModelData>, Error>) -> Void)?
  4)

Parameters

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

• removeRemoteMessageAction(_:completion:)

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

  1public func removeRemoteMessageAction(
  2  _ request: MessageActionRequest<ModelData>,
  3  completion: ((Result<Void, Error>) -> Void)?
  4)

Parameters

Name	Type	Description
_ request	MessageActionRequest<ModelData>	Request object that sets the PubNub API method parameters.
completion	((Result<Void, Error>) -> Void)?	Closure called after removing the message reaction.

• syncRemoteMessageActions(_:completion:)

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

  1public func removeRemoteMessageAction(
  2  _ request: MessageActionFetchRequest,
  3  completion: ((Result<(actions: [ChatMessageAction<ModelData>], next: MessageActionFetchRequest?), PaginationError<MessageActionFetchRequest>>) -> Void)?
  4)

Parameters

Name	Type	Description
_ request	MessageActionRequest<ModelData>	Request object that sets the PubNub API method parameters.
completion	((Result<(actions: [ChatMessageAction<ModelData>], next: MessageActionFetchRequest?), PaginationError<MessageActionFetchRequest>>) -> Void)?	Result of either the existing message reactions that are stored locally (with the next page of message reactions) or PaginationError that contains MessageActionFetchRequest that failed.

• syncAllRemoteMessageActions(pageHandler:completion:)

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

  1public func syncAllRemoteMessageActions(
  2  _ request: MessageActionFetchRequest,
  3  pageHandler: (([ChatMessageAction<ModelData>], MessageActionFetchRequest?, Error?) -> Void)? = nil,
  4  completion: ((PaginationError<MessageActionFetchRequest>?) -> Void)? = nil
  5)

Parameters

Name	Type	Description
_ request	MessageActionFetchRequest	Request object that sets the PubNub API method parameters.
pageHandler	(([ChatMessageAction<ModelData>], MessageActionFetchRequest?, Error?) -> Void)?	Closure called after storing each page.
completion	((PaginationError<MessageActionFetchRequest>?) -> Void)?	Closure called after storing all message reactions.

• load(messages:processMessageActions:batchSize:batchHandler:completion)

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

  1public func load(
  2  messages: [ChatMessage<ModelData>],
  3  processMessageActions: Bool,
  4  batchSize: Int = 256,
  5  batchHandler: (([ChatMessage<ModelData>], Error?) -> Void)? = nil,
  6  completion: (() -> Void)? = nil
  7)

Parameters

Name	Type	Description
messages	[ChatMessage<ModelData>]	Messages to store.
processMessageActions	Bool	Flag that defines if you want to insert or update message actions that belong to the given message.
batchSize	Int	Size of each chunk of messages with reactions to store.
batchHandler	(([ChatMessage<ModelData>], Error?) -> Void)?	Closure called after storing each batch.
completion	(() -> Void)?	Closure called after storing all message reactions.

• load(messageActions:batchSize:batchHandler:completion)

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

  1public func load(
  2  messageActions: [ChatMessageAction<ModelData>],
  3  batchSize: Int = 256,
  4  batchHandler: (([ChatMessageAction<ModelData>], Error?) -> Void)? = nil,
  5  completion: (() -> Void)? = nil
  6)

Parameters

Name	Type	Description
messageActions	[ChatMessageAction<ModelData>]	Message reactions ot store.
batchSize	Int	Size of each chunk of reactions to store.
batchHandler	(([ChatMessageAction<ModelData>], Error?) -> Void)?	Closure called after storing each batch.
completion	(() -> Void)?	Closure called after storing all message reactions.

• removeStoredMessageAction(messageActionId:completion)

Removes a list of messages reactions from the Core Data store batching.

1public func removeStoredMessageAction(
2  messageActionId: String,
3  completion: ((Error?) -> Void)? = nil
4)

Parameters

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