App Context API for Swift Native SDK

This page describes App Context (formerly Objects v2). To upgrade from Objects v1, refer to the migration guide.

App Context provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use App Context to easily store metadata about your application users and channels, and their membership associations, without the need to stand up your own databases.

PubNub also triggers events when object data is set or removed from the database. Clients can receive these events in real-time and update their front-end application accordingly.

UUID and User ID

PubNubUUIDMetadataBase is deprecated but will continue to work as a typealias for PubNubUserMetadataBase.

User

Get Metadata for All Users

Returns a paginated list of User Metadata objects, optionally including the custom data object for each.

Method(s)

To Get All User Metadata you can use the following method(s) in the Swift SDK:

func allUserMetadata(
    include: PubNub.UserIncludeFields = PubNub.UserIncludeFields(),
    filter: String? = nil,
    sort: [PubNub.ObjectSortField] = [],
    limit: Int? = 100,
    page: PubNubHashedPage? = Page(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(users: [PubNubUserMetadata], next: PubNubHashedPage?), Error>) -> Void)?
)

* required

Parameter	Description
`include` Type: `PubNub.UserIncludeFields` Default: `PubNub.UserIncludeFields()`	Whether to include the custom field in the fetch response. For more information, refer to the UserIncludeFields section.
`filter` Type: String? Default: `nil`	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
`sort` Type: [PubNub.ObjectSortField] Default: `[]`	List of properties to sort response objects. The following properties are valid for sorting: `.id`, `.name`, `.type`, `.status`, and `.updated`.
`page` Type: `PubNubHashedPage?` Default: `PubNub.Page()`	The paging object used for pagination that allows for cursor-based pagination where the pages are navigated using a cursor, such as a `next` value.
`limit` Type: Int? Default: 100	The number of objects to retrieve at a time.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<(users: [PubNubUserMetadata], next: PubNubHashedPage?), Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

UserIncludeFields

PubNub.UserIncludeFields is a struct that defines which additional fields should be included in the response when fetching user metadata. It allows fine-grained control over what data is returned, helping optimize response payload size and network efficiency.

Property	Description
`custom` Type: `Bool` Default: `true`	Whether to include the custom dictionary for the user metadata object
`type` Type: `Bool` Default: `true`	Whether to include the type field for the user metadata object
`status` Type: `Bool` Default: `true`	Whether to include the status field for the user metadata object
`totalCount` Type: `Bool` Default: `true`	Whether to include the total count of how many user objects are available

Completion Handler Result

Success

A Tuple containing an Array of PubNubUserMetadata, and the next pagination PubNubHashedPage (if one exists).

public protocol PubNubUserMetadata {

  /// The unique identifier of the User
  var metadataId: String { get }

  /// The name of the User
  var name: String { get set }

  /// The classification of User
  var type: String? { get set }

  /// The current state of the User
  var status: String? { get set }

  /// The external identifier for the object
show all 32 lines

public protocol PubNubHashedPage {

  /// The hash value representing the next set of data
  var start: String? { get }

  /// The hash value representing the previous set of data
  var end: String? { get }

  /// The total count of all objects withing range
  var totalCount: Int? { get }
}

Failure

An Error describing the failure.

Basic Usage

Reference code

This example is a self-contained code snippet ready to be run. It includes necessary imports and executes methods with console logging. Use it as a reference when working with other examples in this document.

Get User Metadata

Returns metadata for the specified User, optionally including the custom data object for each.

Method(s)

To Get User Metadata you can use the following method(s) in the Swift SDK:

func fetchUserMetadata(
    _ metadataId: String?,
    include: PubNub.UserIncludeFields = PubNub.UserIncludeFields(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<PubNubUserMetadata, Error>) -> Void)?
)

* required

Parameter	Description
`metadataId` * Type: String Default: n/a	Unique User Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
`include` Type: `PubNub.UserIncludeFields` Default: `PubNub.UserIncludeFields()`	Whether to include the custom field in the fetch response. For more information, refer to the UserIncludeFields section.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<PubNubUserMetadata, Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

Completion Handler Result

Success

The PubNubUserMetadata object belonging to the identifier.

public protocol PubNubUserMetadata {

  /// The unique identifier of the User
  var metadataId: String { get }

  /// The name of the User
  var name: String { get set }

  /// The classification of User
  var type: String? { get set }

  /// The current state of the User
  var status: String? { get set }

  /// The external identifier for the object
show all 32 lines

Failure

An Error describing the failure.

Basic Usage

Set User Metadata

Unsupported partial updates of custom metadata

The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must:

Get the existing metadata and store it locally.
Append the new custom metadata to the existing one.
Set the entire updated custom object.

Set metadata for a User in the database, optionally including the custom data object for each.

Method(s)

To Set User Metadata you can use the following method(s) in the Swift SDK:

func setUserMetadata(
    _ metadata: PubNubUserMetadata,
    ifMatchesEtag: String? = nil,
    include: PubNub.UserIncludeFields = PubNub.UserIncludeFields(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<PubNubUserMetadata, Error>) -> Void)?
)

* required

Parameter	Description
`metadata` * Type: PubNubUserMetadata Default: n/a	User Metadata to set.
`ifMatchesEtag` Type: String Default: n/a	The entity tag to be used to ensure updates only happen if the object hasn't been modified since it was read. Use the eTag you received from an applicable get metadata method to check against the server entity tag. If the eTags don't match, an HTTP 412 error is thrown.
`include` Type: `PubNub.UserIncludeFields` Default: `PubNub.UserIncludeFields()`	Whether to include the custom field in the fetch response. For more information, refer to the UserIncludeFields section.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<PubNubUserMetadata, Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

API limits

To learn about the maximum length of parameters used to set user metadata, refer to REST API docs.

Completion Handler Result

Success

The PubNubUserMetadata object belonging to the identifier.

public protocol PubNubUserMetadata {

  /// The unique identifier of the User
  var metadataId: String { get }

  /// The name of the User
  var name: String { get set }

  /// The classification of User
  var type: String? { get set }

  /// The current state of the User
  var status: String? { get set }

  /// The external identifier for the object
show all 32 lines

Failure

An Error describing the failure.

Basic Usage

Remove User Metadata

Removes the metadata from a specified UUID.

Method(s)

To Remove User Metadata you can use the following method(s) in the Swift SDK:

func removeUserMetadata(
    _ metadataId: String?,
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<String, Error>) -> Void)?
)

* required

Parameter	Description
`metadataId` * Type: String Default: n/a	Unique User Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<String, Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

Completion Handler Result

Success

The User identifier of the removed object.

Failure

An Error describing the failure

Basic Usage

Channel

Get Metadata for All Channels

Returns a paginated list of Channel Metadata objects, optionally including the custom data object for each.

Method(s)

To Get All Channel Metadata you can use the following method(s) in the Swift SDK:

func allChannelMetadata(
    include: PubNub.IncludeFields = PubNub.IncludeFields(),
    filter: String? = nil,
    sort: [PubNub.ObjectSortField] = [],
    limit: Int? = 100,
    page: PubNubHashedPage? = Page(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(channels: [PubNubChannelMetadata], next: PubNubHashedPage?), Error>) -> Void)?
)

* required

Parameter	Description
`include` Type: PubNub.IncludeFields Default: `PubNub.IncludeFields()`	Whether to include the custom field in the fetch response.
`filter` Type: String? Default: `nil`	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
`sort` Type: [PubNub.ObjectSortField] Default: `[]`	List of properties to sort response objects. The following properties are valid for sorting: `.id`, `.name`, `.type`, `.status`, and `.updated`.
`limit` Type: Int? Default: 100	The number of objects to retrieve at a time.
`page` Type: PubNubHashedPage? Default: `PubNub.Page()`	The paging object used for pagination.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<(channels: [PubNubChannelMetadata], next: PubNubHashedPage?), Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

Completion Handler Result

Success

A Tuple containing an Array of PubNubChannelMetadata, and the next pagination PubNubHashedPage (if one exists).

public protocol PubNubChannelMetadata {

  /// The unique identifier of the Channel
  var metadataId: String { get }

  /// The name of the Channel
  var name: String { get set }

  /// The classification of ChannelMetadata
  var type: String? { get set }
  
  /// The current state of the ChannelMetadata
  var status: String? { get set }

  /// Text describing the purpose of the channel
show all 26 lines

public protocol PubNubHashedPage {

  /// The hash value representing the next set of data
  var start: String? { get }

  /// The hash value representing the previous set of data
  var end: String? { get }

  /// The total count of all objects withing range
  var totalCount: Int? { get }
}

Failure

An Error describing the failure.

Basic Usage

Get Channel Metadata

Returns metadata for the specified Channel, optionally including the custom data object for each.

Method(s)

To Get Channel Metadata you can use the following method(s) in the Swift SDK:

func fetchChannelMetadata(
    _ metadataId: String?,
    include: PubNub.ChannelIncludeFields = PubNub.ChannelIncludeFields(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<PubNubChannelMetadata, Error>) -> Void)?
)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Unique Channel Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
`include` Type: `PubNub.ChannelIncludeFields` Default: `PubNub.ChannelIncludeFields()`	Whether to include the custom field in the fetch response. For more information, refer to the ChannelIncludeFields section.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<PubNubChannelMetadata, Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

ChannelIncludeFields

PubNub.ChannelIncludeFields is a struct that defines which additional fields should be included in the response when fetching channel metadata. It provides the same control options as PubNub.UserIncludeFields but for channel-specific operations.

Property	Description
`custom` Type: `Bool` Default: `true`	Whether to include the custom dictionary for the channel metadata object
`type` Type: `Bool` Default: `true`	Whether to include the type field for the channel metadata object
`status` Type: `Bool` Default: `true`	Whether to include the status field for the channel metadata object
`totalCount` Type: `Bool` Default: `true`	Whether to include the total count of how many channel objects are available

Completion Handler Result

Success

The PubNubChannelMetadata object belonging to the identifier.

public protocol PubNubChannelMetadata {

  /// The unique identifier of the Channel
  var metadataId: String { get }

  /// The name of the Channel
  var name: String { get set }

  /// The classification of ChannelMetadata
  var type: String? { get set }
  
  /// The current state of the ChannelMetadata
  var status: String? { get set }

  /// Text describing the purpose of the channel
show all 26 lines

Failure

An Error describing the failure.

Basic Usage

Set Channel Metadata

Unsupported partial updates of custom metadata

The value of the custom metadata parameter sent in this method always overwrites the value stored on PubNub servers. If you want to add new custom data to an existing one, you must:

Get the existing metadata and store it locally.
Append the new custom metadata to the existing one.
Set the entire updated custom object.

Set metadata for a Channel in the database, optionally including the custom data object for each.

Method(s)

To Set Channel Metadata you can use the following method(s) in the Swift SDK:

func setChannelMetadata(
    _ metadata: PubNubChannelMetadata,
    ifMatchesEtag: String? = nil
    include: PubNub.ChannelIncludeFields = PubNub.ChannelIncludeFields(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<PubNubChannelMetadata, Error>) -> Void)?
)

* required

Parameter	Description
`metadata` * Type: PubNubChannelMetadata Default: n/a	Channel Metadata to set.
`ifMatchesEtag` Type: String Default: n/a	The entity tag to be used to ensure updates only happen if the object hasn't been modified since it was read. Use the eTag you received from an applicable get metadata method to check against the server entity tag. If the eTags don't match, an HTTP 412 error is thrown.
`include` Type: `PubNub.ChannelIncludeFields` Default: `PubNub.ChannelIncludeFields()`	Whether to include the custom field in the fetch response. For more information, refer to the ChannelIncludeFields section.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<PubNubChannelMetadata, Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

API limits

To learn about the maximum length of parameters used to set channel metadata, refer to REST API docs.

Completion Handler Result

Success

The PubNubChannelMetadata object belonging to the identifier.

public protocol PubNubChannelMetadata {

  /// The unique identifier of the Channel
  var metadataId: String { get }

  /// The name of the Channel
  var name: String { get set }

  /// The classification of ChannelMetadata
  var type: String? { get set }
  
  /// The current state of the ChannelMetadata
  var status: String? { get set }

  /// Text describing the purpose of the channel
show all 26 lines

Failure

An Error describing the failure.

Basic Usage

Other Examples

Iteratively update existing metadata

Remove Channel Metadata

Removes the metadata from a specified channel.

Method(s)

To Remove Channel Metadata you can use the following method(s) in the Swift SDK:

func removeChannelMetadata(
    _ metadataId: String?,
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<String, Error>) -> Void)?
)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Unique Channel Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<PubNubChannelMetadata, Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

Completion Handler Result

Success

The Channel identifier of the removed object.

Failure

An Error describing the failure.

Basic Usage

Channel Memberships

Get Channel Memberships

The method returns a list of channel memberships for a user. This method doesn't return a user's subscriptions.

Method(s)

To Get Memberships you can use the following method(s) in the Swift SDK:

To Get Channel Memberships you can use the following method(s) in the Swift SDK:

func fetchMemberships(
    userId: String?,
    include: PubNub.MembershipInclude = PubNub.MembershipInclude(),
    filter: String? = nil,
    sort: [PubNub.MembershipSortField] = [],
    limit: Int? = 100,
    page: PubNubHashedPage? = Page(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?
)

* required

Parameter	Description
`userId` * Type: String Default: n/a	Unique User Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
`include` Type: `PubNub.MembershipInclude` Default: `PubNub.MembershipInclude()`	Whether to include the custom field in the fetch response. For more information, refer to the MembershipInclude section.
`filter` Type: String? Default: `nil`	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
`sort` Type: [MembershipSortField] Default: `[]`	List of properties to sort response objects. The following properties are valid for sorting: `.object(.id)`, `.object(.name)`, `.object(.type)`, `.object(.status)`, `.object(.updated)`, `.type`, `.status`, `.updated`.
`limit` Type: Int? Default: 100	The number of objects to retrieve at a time.
`page` Type: PubNubHashedPage? Default: `PubNub.Page()`	The paging object used for pagination.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

MembershipInclude

PubNub.MembershipInclude is a struct that defines which additional fields should be included in the response when fetching user membership data (channels a user belongs to). It provides granular control over both membership fields and associated channel metadata fields.

Property	Description
`customFields` Type: `Bool` Default: `true`	Whether to include the custom dictionary for the membership object
`channelFields` Type: `Bool` Default: `false`	Whether to include the full PubNubChannelMetadata instance in the membership
`typeField` Type: `Bool` Default: `true`	Whether to include the type field of the membership object
`statusField` Type: `Bool` Default: `true`	Whether to include the status field of the membership object
`channelTypeField` Type: `Bool` Default: `false`	Whether to include the type field of the associated channel metadata
`channelStatusField` Type: `Bool` Default: `false`	Whether to include the status field of the associated channel metadata
`channelCustomFields` Type: `Bool` Default: `false`	Whether to include the custom dictionary of the associated channel metadata
`totalCount` Type: `Bool` Default: `false`	Whether to include the total count of how many membership objects are available

Completion Handler Result

Success

A Tuple containing an Array of PubNubMembershipMetadata, and the next pagination PubNubHashedPage (if one exists).

public protocol PubNubMembershipMetadata {

  /// The unique identifier of the associated User
  var userMetadataId: String { get }

  /// The unique identifier of the associated Channel
  var channelMetadataId: String { get }

  /// The current status of the MembershipMetadata
  var status: String? { get set }
  
  /// The current type of the MembershipMetadata
  var type: String? { get set }

  /// The associated User metadata
show all 29 lines

public protocol PubNubHashedPage {

  /// The hash value representing the next set of data
  var start: String? { get }

  /// The hash value representing the previous set of data
  var end: String? { get }

  /// The total count of all objects withing range
  var totalCount: Int? { get }
}

Failure

An Error describing the failure.

Basic Usage

Fetch and handle user channel memberships.

Return sorted channel memberships for the given user ID.

Set Channel Memberships

Set channel memberships for a User.

Method(s)

To Set Channel Memberships you can use the following method(s) in the Swift SDK:

func setMemberships(
    userId metadataId: String?,
    channels memberships: [PubNubMembershipMetadata],
    include: PubNub.MembershipInclude = PubNub.MembershipInclude(),
    filter: String? = nil,
    sort: [PubNub.MembershipSortField] = [],
    limit: Int? = 100,
    page: PubNubHashedPage? = Page(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?
)

* required

Parameter	Description
`userId` * Type: String Default: n/a	Unique User Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
`channels` * Type: [PubNubMembershipMetadata] Default: n/a	Array of `PubNubMembershipMetadata` with the `PubNubChannelMetadata` or `channelMetadataId` provided.
`include` Type: `PubNub.MembershipInclude` Default: `PubNub.MembershipInclude()`	Whether to include the custom field in the fetch response. For more information, refer to the MembershipInclude section.
`filter` Type: String? Default: `nil`	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
`sort` Type: [PubNub.MembershipSortField] Default: `[]`	List of properties to sort response objects. The following properties are valid for sorting: `.object(.id)`, `.object(.name)`, `.object(.type)`, `.object(.status)`, `.object(.updated)`, `.type`, `.status`, and `.updated`.
`limit` Type: Int? Default: 100	The number of objects to retrieve at a time.
`page` Type: PubNubHashedPage? Default: `PubNub.Page()`	The paging object used for pagination.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

API limits

To learn about the maximum length of parameters used to set channel membership metadata, refer to REST API docs.

Completion Handler Result

Success

A Tuple containing an Array of PubNubMembershipMetadata, and the next pagination PubNubHashedPage (if one exists).

public protocol PubNubMembershipMetadata {

  /// The unique identifier of the associated User
  var userMetadataId: String { get }

  /// The unique identifier of the associated Channel
  var channelMetadataId: String { get }

  /// The current status of the MembershipMetadata
  var status: String? { get set }
  
  /// The current type of the MembershipMetadata
  var type: String? { get set }

  /// The associated User metadata
show all 29 lines

public protocol PubNubHashedPage {

  /// The hash value representing the next set of data
  var start: String? { get }

  /// The hash value representing the previous set of data
  var end: String? { get }

  /// The total count of all objects withing range
  var totalCount: Int? { get }
}

Failure

An Error describing the failure.

Basic Usage

Remove Channel Memberships

Remove channel memberships for a User.

Method(s)

To Remove Channel Memberships you can use the following method(s) in the Swift SDK:

func removeMemberships(
    userId metadataId: String?,
    channels memberships: [PubNubMembershipMetadata],
    include: PubNub.MembershipInclude = PubNub.MembershipInclude(),
    filter: String? = nil,
    sort: [PubNub.MembershipSortField] = [],
    limit: Int? = 100,
    page: PubNubHashedPage? = Page(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?
)

* required

Parameter	Description
`userId` * Type: String Default: n/a	Unique User Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration.
`channels` * Type: [PubNubMembershipMetadata] Default: n/a	Array of `PubNubMembershipMetadata` with the `PubNubChannelMetadata` or `channelMetadataId` provided.
`include` Type: `PubNub.MembershipInclude` Default: `PubNub.MembershipInclude()`	Whether to include the custom field in the fetch response. For more information, refer to the MembershipInclude section.
`filter` Type: String? Default: `nil`	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
`sort` Type: [PubNub.MembershipSortField] Default: `[]`	List of properties to sort response objects. The following properties are valid for sorting: `.object(.id)`, `.object(.name)`, `.object(.type)`, `.object(.status)`, `.object(.updated)`, `.type`, `.status`, and `.updated`.
`limit` Type: Int? Default: 100	The number of objects to retrieve at a time.
`page` Type: PubNubHashedPage? Default: `PubNub.Page()`	The paging object used for pagination.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

Completion Handler Result

Success

A Tuple containing an Array of PubNubMembershipMetadata, and the next pagination PubNubHashedPage (if one exists).

public protocol PubNubMembershipMetadata {

  /// The unique identifier of the associated User
  var userMetadataId: String { get }

  /// The unique identifier of the associated Channel
  var channelMetadataId: String { get }

  /// The current status of the MembershipMetadata
  var status: String? { get set }
  
  /// The current type of the MembershipMetadata
  var type: String? { get set }

  /// The associated User metadata
show all 29 lines

public protocol PubNubHashedPage {

  /// The hash value representing the next set of data
  var start: String? { get }

  /// The hash value representing the previous set of data
  var end: String? { get }

  /// The total count of all objects withing range
  var totalCount: Int? { get }
}

Failure

An Error describing the failure.

Basic Usage

Channel Members

Get Channel Members

The method returns a list of members in a channel. The list will include user metadata for members that have additional metadata stored in the database.

Method(s)

To Get Channel Members you can use the following method(s) in the Swift SDK:

func fetchMembers(
    channel: String?,
    include: PubNub.MemberInclude = PubNub.MemberInclude(),
    filter: String? = nil,
    sort: [PubNub.MembershipSortField] = [],
    limit: Int? = 100,
    page: PubNubHashedPage? = Page(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?
)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Unique Channel Metadata identifier.
`include` Type: `PubNub.MemberInclude` Default: `PubNub.MemberInclude()`	Whether to include the custom field in the fetch response. For more information, refer to the MemberInclude section.
`filter` Type: String? Default: `nil`	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
`sort` Type: [PubNub.MembershipSortField] Default: `[]`	List of properties to sort response objects. The following properties are valid for sorting: `.object(.id)`, `.object(.name)`, `.object(.type)`, `.object(.status)`, `.object(.updated)`, `.type`, `.status`, and `.updated`.
`limit` Type: Int? Default: 100	The number of objects to retrieve at a time.
`page` Type: PubNubHashedPage? Default: `PubNub.Page()`	The paging object used for pagination.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

MemberInclude

PubNub.MemberInclude is a struct that defines which additional fields should be included in the response when fetching channel member data (users that belong to a channel). It provides granular control over both membership fields and associated user metadata fields.

Property	Description
`customFields` Type: `Bool` Default: `true`	Whether to include the custom dictionary for the membership object
`uuidFields` Type: `Bool` Default: `false`	Whether to include the full PubNubUserMetadata instance in the membership
`statusField` Type: `Bool` Default: `true`	Whether to include the status field of the membership object
`typeField` Type: `Bool` Default: `true`	Whether to include the type field of the membership object
`uuidTypeField` Type: `Bool` Default: `false`	Whether to include the type field of the associated user metadata
`uuidStatusField` Type: `Bool` Default: `false`	Whether to include the status field of the associated user metadata
`uuidCustomFields` Type: `Bool` Default: `false`	Whether to include the custom dictionary of the associated user metadata
`totalCount` Type: `Bool` Default: `false`	Whether to include the total count of how many member objects are available

Completion Handler Result

Success

A Tuple containing an Array of PubNubMembershipMetadata, and the next pagination PubNubHashedPage (if one exists).

public protocol PubNubMembershipMetadata {

  /// The unique identifier of the associated User
  var userMetadataId: String { get }

  /// The unique identifier of the associated Channel
  var channelMetadataId: String { get }

  /// The current status of the MembershipMetadata
  var status: String? { get set }
  
  /// The current type of the MembershipMetadata
  var type: String? { get set }

  /// The associated User metadata
show all 29 lines

public protocol PubNubHashedPage {

  /// The hash value representing the next set of data
  var start: String? { get }

  /// The hash value representing the previous set of data
  var end: String? { get }

  /// The total count of all objects withing range
  var totalCount: Int? { get }
}

Failure

An Error describing the failure.

Basic Usage

Set Channel Members

This method sets members in a channel.

Method(s)

To Set Channel Members you can use the following method(s) in the Swift SDK:

func setMembers(
    channel metadataId: String,
    users members: [PubNubMembershipMetadata],
    include: PubNub.MemberInclude = PubNub.MemberInclude(),
    filter: String? = nil,
    sort: [PubNub.MembershipSortField] = [],
    limit: Int? = 100,
    page: PubNubHashedPage? = Page(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?
)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Unique Channel identifier.
`users` * Type: [PubNubMembershipMetadata] Default: n/a	Array of `PubNubMembershipMetadata` with the `PubNubUserMetadata` or `userMetadataId` provided.
`include` Type: `PubNub.MemberInclude` Default: `PubNub.MemberInclude()`	Whether to include the custom field in the fetch response. For more information, refer to the MemberInclude section.
`filter` Type: String? Default: `nil`	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
`sort` Type: [PubNub.MembershipSortField] Default: `[]`	List of properties to sort response objects. The following properties are valid for sorting: `.object(.id)`, `.object(.name)`, `.object(.type)`, `.object(.status)`, `.object(.updated)`, `.type`, `.status`, and `.updated`.
`limit` Type: Int? Default: 100	The number of objects to retrieve at a time.
`page` Type: PubNubHashedPage? Default: `PubNub.Page()`	The paging object used for pagination.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

API limits

To learn about the maximum length of parameters used to set channel members metadata, refer to REST API docs.

Completion Handler Result

Success

A Tuple containing an Array of PubNubMembershipMetadata, and the next pagination PubNubHashedPage (if one exists).

public protocol PubNubMembershipMetadata {

  /// The unique identifier of the associated User
  var userdMetadataId: String { get }

  /// The unique identifier of the associated Channel
  var channelMetadataId: String { get }

  /// The current status of the MembershipMetadata
  var status: String? { get set }
  
  /// The current type of the MembershipMetadata
  var type: String? { get set }

  /// The associated User metadata
show all 29 lines

public protocol PubNubHashedPage {

  /// The hash value representing the next set of data
  var start: String? { get }

  /// The hash value representing the previous set of data
  var end: String? { get }

  /// The total count of all objects withing range
  var totalCount: Int? { get }
}

Failure

An Error describing the failure.

Basic Usage

Remove Channel Members

Remove members from a Channel.

Method(s)

To Remove Channel Members you can use the following method(s) in the Swift SDK:

func removeMembers(
    channel metadataId: String,
    users members: [PubNubMembershipMetadata],
    include: PubNub.MemberInclude = PubNub.MemberInclude(),
    filter: String? = nil,
    sort: [PubNub.MembershipSortField] = [],
    limit: Int? = 100,
    page: PubNubHashedPage? = Page(),
    custom requestConfig: PubNub.RequestConfiguration = PubNub.RequestConfiguration(),
    completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?
)

* required

Parameter	Description
`channel` * Type: String Default: n/a	Unique Channel identifier.
`uuids` * Type: [PubNubMembershipMetadata] Default: n/a	Array of `PubNubMembershipMetadata` with the `PubNubUserMetadata` or `userMetadataId` provided.
`include` Type: `PubNub.MemberInclude` Default: `PubNub.MemberInclude()`	Whether to include the custom field in the fetch response. For more information, refer to the MemberInclude section.
`filter` Type: String? Default: `nil`	Expression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here.
`sort` Type: [PubNub.MembershipSortField] Default: `[]`	List of properties to sort response objects. The following properties are valid for sorting: `.object(.id)`, `.object(.name)`, `.object(.type)`, `.object(.status)`, `.object(.updated)`, `.type`, `.status`, and `.updated`.
`limit` Type: Int? Default: 100	The number of objects to retrieve at a time.
`page` Type: PubNubHashedPage? Default: `PubNub.Page()`	The paging object used for pagination.
`custom` Type: `PubNub.RequestConfiguration` Default: `PubNub.RequestConfiguration()`	An object that allows for per-request customization of PubNub configuration or network session. For more information, refer to the Request Configuration section.
`completion` Type: `((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?` Default: `nil`	The async `Result` of the method call.

Completion Handler Result

Success

A Tuple containing an Array of PubNubMembershipMetadata, and the next pagination PubNubHashedPage (if one exists).

public protocol PubNubMembershipMetadata {

  /// The unique identifier of the associated User
  var userdMetadataId: String { get }

  /// The unique identifier of the associated Channel
  var channelMetadataId: String { get }

  /// The current status of the MembershipMetadata
  var status: String? { get set }
  
  /// The current type of the MembershipMetadata
  var type: String? { get set }

  /// The associated User metadata
show all 29 lines

public protocol PubNubHashedPage {

  /// The hash value representing the next set of data
  var start: String? { get }

  /// The hash value representing the previous set of data
  var end: String? { get }

  /// The total count of all objects withing range
  var totalCount: Int? { get }
}

Failure

An Error describing the failure.

UUID and User ID

User​

Get Metadata for All Users​

Method(s)​

UserIncludeFields​

Completion Handler Result​

Success​

Failure​

Basic Usage​

Reference code

Get User Metadata​

Method(s)​

Completion Handler Result​

Success​

Failure​

Basic Usage​

Set User Metadata​

Unsupported partial updates of custom metadata

Method(s)​

API limits

Completion Handler Result​

Success​

Failure​

Basic Usage​

Remove User Metadata​

Method(s)​

Completion Handler Result​

Success​

Failure​

Basic Usage​

Channel​

Get Metadata for All Channels​

Method(s)​

Completion Handler Result​

Success​

Failure​

Basic Usage​

Get Channel Metadata​

Method(s)​

ChannelIncludeFields​

Completion Handler Result​

Success​

Failure​

Basic Usage​

Set Channel Metadata​

Unsupported partial updates of custom metadata

Method(s)​

API limits

Completion Handler Result​

Success​

Failure​

Basic Usage​

Other Examples​

Iteratively update existing metadata​

Remove Channel Metadata​

Method(s)​

Completion Handler Result​

Success​

Failure​

Basic Usage​

Channel Memberships​

Get Channel Memberships​

Method(s)​

MembershipInclude​

Completion Handler Result​

Success​

Failure​

Basic Usage​

Set Channel Memberships​

Method(s)​

API limits

Completion Handler Result​

Success​

Failure​

Basic Usage​

Remove Channel Memberships​

Method(s)​

Completion Handler Result​

Success​

Failure​

User

Get Metadata for All Users

Method(s)

UserIncludeFields

Completion Handler Result

Success

Failure

Basic Usage

Get User Metadata

Method(s)

Completion Handler Result

Success

Failure

Basic Usage

Set User Metadata

Method(s)

Completion Handler Result

Success

Failure

Basic Usage

Remove User Metadata

Method(s)

Completion Handler Result

Success

Failure

Basic Usage

Channel

Get Metadata for All Channels

Method(s)

Completion Handler Result

Success

Failure

Basic Usage

Get Channel Metadata

Method(s)

ChannelIncludeFields

Completion Handler Result

Success

Failure

Basic Usage

Set Channel Metadata

Method(s)

Completion Handler Result

Success

Failure

Basic Usage

Other Examples

Iteratively update existing metadata

Remove Channel Metadata

Method(s)

Completion Handler Result

Success

Failure

Basic Usage

Channel Memberships

Get Channel Memberships

Method(s)

MembershipInclude

Completion Handler Result

Success

Failure

Basic Usage

Set Channel Memberships

Method(s)

Completion Handler Result

Success

Failure

Basic Usage

Remove Channel Memberships

Method(s)

Completion Handler Result

Success

Failure

Basic Usage

Channel Members

Get Channel Members

Method(s)

MemberInclude

Completion Handler Result

Success