Metadata API for PubNub Swift Native SDK

This page describes the new Objects v2. To upgrade from Objects v1, refer to the migration guide.

Note

The PubNub Swift 3.0 SDK contains many significant changes from the 2.x SDK, including breaking changes. Please refer to the PubNub Swift 3.0 Migration Guide for more details.

Objects provides easy-to-use, serverless storage for user and channel data you need to build innovative, reliable, scalable applications. Use Objects 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.

User

Get Metadata for All Users

Description

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

Method(s)

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

  1. allUUIDMetadata(  include: IncludeFields = IncludeFields(),  filter: String? = nil,  sort: [ObjectSortField] = [],  limit: Int? = 100,  page: PubNubHashedPage? = Page(),  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<(uuids: [PubNubUUIDMetadata], next: PubNubHashedPage?), Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    includeIncludeFieldsOptionalIncludeFields()Whether to include the custom field in the fetch response
    filterString?OptionalnilExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
    sort[ObjectSortField]Optional[]List of properties to sort response objects. The following properties are valid for sorting: .id, .name, and .updated.
    pagePubNubHashedPage?OptionalPubNub.Page()The paging object used for pagination
    limitInt?Optional100The number of objects to retrieve at a time
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<(uuids: [PubNubUUIDMetadata], next: PubNubHashedPage?), Error>) -> Void)?OptionalnilThe async Result of the method call

Completion Handler Result

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

    public protocol PubNubUUIDMetadata {
  /// The unique identifier of the UUID
  var metadataId: String { get }

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

  /// The external identifier for the object
  var externalId: String? { get set }

  /// The profile URL for the object
  var profileURL: String? { get set }

  /// The email address of the object
  var email: String? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

    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

pubnub.allUUIDMetadata() { result in
  switch result {
  case let .success(response):
    print("The uuid metadata objects \(response.uuids)")
    if let nextPage = response.next {
      print("The next page used for pagination: \(nextPage)")
    }
  case let .failure(error):
    print("Fetch All request failed with error: \(error.localized### Description)")
  }
}

Get User Metadata

Description

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

Method(s)

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

  1. fetch(  uuid metadata: String?,  include customFields: Bool = true,  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<PubNubUUIDMetadata, Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    uuidStringYesUnique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration
    includeIncludeFieldsOptionalIncludeFields()Whether to include the custom field in the fetch response
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<PubNubUUIDMetadata, Error>) -> Void)?OptionalnilThe async Result of the method call

Completion Handler Result

  • Success The PubNubUUIDMetadata object belonging to the identifier.

    public protocol PubNubUUIDMetadata {
  /// The unique identifier of the UUID
  var metadataId: String { get }

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

  /// The external identifier for the object
  var externalId: String? { get set }

  /// The profile URL for the object
  var profileURL: String? { get set }

  /// The email address of the object
  var email: String? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

  • Failure An Error describing the failure.

Basic Usage

pubnub.fetch(uuid: "TestUser") { result in
  switch result {
  case let .success(uuidMetadata):
    print("The metadata for `\(uuidMetadata.metadataId)`: \(uuidMetadata)")
  case let .failure(error):
    print("Fetch request failed with error: \(error.localized### Description)")
  }
}

Set User Metadata

Description

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

Method(s)

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

  1. set(  uuid metadata: PubNubUUIDMetadata,  include customFields: Bool = true,  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<PubNubUUIDMetadata, Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    uuidPubNubUUIDMetadataYesUUID Metadata to set
    includeIncludeFieldsOptionalIncludeFields()Whether to include the custom field in the fetch response
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<PubNubUUIDMetadata, Error>) -> Void)?OptionalnilThe async Result of the method call

Completion Handler Result

  • Success The PubNubUUIDMetadata object belonging to the identifier.

    public protocol PubNubUUIDMetadata {
  /// The unique identifier of the UUID
  var metadataId: String { get }

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

  /// The external identifier for the object
  var externalId: String? { get set }

  /// The profile URL for the object
  var profileURL: String? { get set }

  /// The email address of the object
  var email: String? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

  • Failure An Error describing the failure.

Basic Usage

let johnDoe = PubNubUUIDMetadataBase(
  id: "john-doe", name: "John Doe",
  custom: ["title": "Mr. Manager"]
)

pubnub.set(user: johnDoe) { result in
  switch result {
  case let .success(uuidMetadata):
    print("The metadata for `\(uuidMetadata.metadataId)`: \(uuidMetadata)")
  case let .failure(error):
    print("Create request failed with error: \(error.localized### Description)")
  }
}

Remove User Metadata

Description

Removes the metadata from a specified UUID.

Method(s)

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

  1. remove(  uuid metadataId: String?,  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<String, Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    uuidStringYesUnique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<PubNubUUIDMetadata, Error>) -> Void)?OptionalnilThe async Result of the method call

Basic Usage

pubnub.remove(uuid: "john-doe") { result in
  switch result {
  case let .success(metadataId):
    print("The metadata has been removed for the uuid `\(metadataId)`")
  case let .failure(error):
    print("Delete request failed with error: \(error.localized### Description)")
  }
}

Channel

Get Metadata for All Channels

Description

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:

  1. allChannelMetadata(  include: IncludeFields = IncludeFields(),  filter: String? = nil,  sort: [ObjectSortField] = [],  limit: Int? = 100,  page: PubNubHashedPage? = Page(),  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<(uuids: [PubNubChannelMetadata], next: PubNubHashedPage?), Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    includeIncludeFieldsOptionalIncludeFields()Whether to include the custom field in the fetch response
    filterString?OptionalnilExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
    sort[ObjectSortField]Optional[]List of properties to sort response objects. The following properties are valid for sorting: .id, .name, and .updated.
    limitInt?Optional100The number of objects to retrieve at a time
    pagePubNubHashedPage?OptionalPubNub.Page()The paging object used for pagination
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<(channels: [PubNubChannelMetadata], next: PubNubHashedPage?), Error>) -> Void)?OptionalnilThe 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 }

  /// Text describing the purpose of the channel
  var channelDescription: String? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

    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

pubnub.allChannelMetadata() { result in
  switch result {
  case let .success(response):
    print("The channel metadata objects \(response.channels)")
    if let nextPage = response.next {
      print("The next page used for pagination: \(nextPage)")
    }
  case let .failure(error):
    print("Fetch All request failed with error: \(error.localized### Description)")
  }
}

Get Channel Metadata

Description

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:

  1. fetch(  channel metadata: String?,  include customFields: Bool = true,  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<PubNubChannelMetadata, Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    channelStringYesUnique Channel Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration
    includeIncludeFieldsOptionalIncludeFields()Whether to include the custom field in the fetch response
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<PubNubChannelMetadata, Error>) -> Void)?OptionalnilThe async Result of the method call

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 }

  /// Text describing the purpose of the channel
  var channelDescription: String? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

  • Failure An Error describing the failure.

Basic Usage

pubnub.fetch(channel: "TestUser") { result in
  switch result {
  case let .success(channelMetadata):
    print("The metadata for `\(channelMetadata.metadataId)`: \(channelMetadata)")
  case let .failure(error):
    print("Fetch request failed with error: \(error.localized### Description)")
  }
}

Set Channel Metadata

Description

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:

  1. set(  channel metadata: PubNubChannelMetadata,  include customFields: Bool = true,  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<PubNubChannelMetadata, Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    channelPubNubChannelMetadataYesChannel Metadata to set
    includeIncludeFieldsOptionalIncludeFields()Whether to include the custom field in the fetch response
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<PubNubChannelMetadata, Error>) -> Void)?OptionalnilThe async Result of the method call

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 }

  /// Text describing the purpose of the channel
  var channelDescription: String? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

  • Failure An Error describing the failure.

Basic Usage

let johnDoe = PubNubChannelMetadataBase(
  id: "john-doe", name: "John Doe",
  custom: ["title": "Mr. Manager"]
)

pubnub.set(user: johnDoe) { result in
  switch result {
  case let .success(channelMetadata):
    print("The metadata for `\(channelMetadata.metadataId)`: \(channelMetadata)")
  case let .failure(error):
    print("Create request failed with error: \(error.localized### Description)")
  }
}

Remove Channel Metadata

Description

Removes the metadata from a specified channel.

Method(s)

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

  1. remove(  channel metadataId: String?,  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<String, Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    channelStringYesUnique Channel Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<PubNubChannelMetadata, Error>) -> Void)?OptionalnilThe async Result of the method call

Basic Usage

pubnub.remove(channel: "john-doe") { result in
  switch result {
  case let .success(metadataId):
    print("The metadata has been removed for the channel `\(metadataId)`")
  case let .failure(error):
    print("Delete request failed with error: \(error.localized### Description)")
  }
}

Channel Memberships

Get Channel Memberships

Description

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:

  1. fetchMemberships(  uuid: String?,  include: MembershipInclude = MembershipInclude(),  filter: String? = nil,  sort: [MembershipSortField] = [],  limit: Int? = 100,  page: PubNubHashedPage? = Page(),  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    uuidStringYesUnique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration
    includeMembershipIncludeOptionalMembershipInclude()Whether to include the custom field in the fetch response
    filterString?OptionalnilExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
    sort[MembershipSortField]Optional[]List of properties to sort response objects. The following properties are valid for sorting: .object(.id), .object(.name), .object(.updated), and .updated.
    limitInt?Optional100The number of objects to retrieve at a time
    pagePubNubHashedPage?OptionalPubNub.Page()The paging object used for pagination
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?OptionalnilThe 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 UUID
  var uuidMetadataId: String { get }

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

  /// The associated UUID metadata
  var uuid: PubNubUUIDMetadata? { get set }

  /// The associated Channel metadata
  var channel: PubNubChannelMetadata? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

    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

pubnub.fetchMemberships(uuid: "my_user") { result in
  switch result {
  case let .success(response):
    print("The channel memberships for the uuid \(response.memberships)")
    if let nextPage = response.next {
      print("The next page used for pagination: \(nextPage)")
    }
  case let .failure(error):
    print("Fetch Memberships request failed with error: \(error.localized### Description)")
  }
}

Set Channel Memberships

Description

Set channel memberships for a UUID.

Method(s)

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

  1. setMemberships(  uuid metadataId: String?,  channels memberships: [PubNubMembershipMetadata],  include: MembershipInclude = MembershipInclude(),  filter: String? = nil,  sort: [MembershipSortField] = [],  limit: Int? = 100,  page: PubNubHashedPage? = Page(),  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    uuidStringYesUnique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration
    channels[PubNubMembershipMetadata]YesArray of PubNubMembershipMetadata with the PubNubChannelMetadata or channelMetadataId provided
    includeMembershipIncludeOptionalMembershipInclude()Whether to include the custom field in the fetch response
    filterString?OptionalnilExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
    sort[MembershipSortField]Optional[]List of properties to sort response objects. The following properties are valid for sorting: .object(.id), .object(.name), .object(.updated), and .updated.
    limitInt?Optional100The number of objects to retrieve at a time
    pagePubNubHashedPage?OptionalPubNub.Page()The paging object used for pagination
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?OptionalnilThe 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 UUID
  var uuidMetadataId: String { get }

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

  /// The associated UUID metadata
  var uuid: PubNubUUIDMetadata? { get set }

  /// The associated Channel metadata
  var channel: PubNubChannelMetadata? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

    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

let newMembership = PubNubMembershipMetadataBase(
  uuidMetadataId: "my_user", channelMetadataId: "my_channel"
)

pubnub.setMemberships(
  uuid: newMembership.uuidMetadataId,
  channels: [newMembership]
) { result in
  switch result {
  case let .success(response):
    print("The channel memberships for the uuid \(response.memberships)")
    if let nextPage = response.next {
      print("The next page used for pagination: \(nextPage)")
    }
  case let .failure(error):
    print("Update Memberships request failed with error: \(error.localized### Description)")
  }
}

Remove Channel Memberships

Description

Remove channel memberships for a UUID.

Method(s)

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

  1. removeMemberships(  uuid metadataId: String?,  channels memberships: [PubNubMembershipMetadata],  include: MembershipInclude = MembershipInclude(),  filter: String? = nil,  sort: [MembershipSortField] = [],  limit: Int? = 100,  page: PubNubHashedPage? = Page(),  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    uuidStringYesUnique UUID Metadata identifier. If not supplied, then it will use the request configuration and then the default configuration
    channels[PubNubMembershipMetadata]YesArray of PubNubMembershipMetadata with the PubNubChannelMetadata or channelMetadataId provided
    includeMembershipIncludeOptionalMembershipInclude()Whether to include the custom field in the fetch response
    filterString?OptionalnilExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
    sort[MembershipSortField]Optional[]List of properties to sort response objects. The following properties are valid for sorting: .object(.id), .object(.name), .object(.updated), and .updated.
    limitInt?Optional100The number of objects to retrieve at a time
    pagePubNubHashedPage?OptionalPubNub.Page()The paging object used for pagination
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?OptionalnilThe 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 UUID
  var uuidMetadataId: String { get }

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

  /// The associated UUID metadata
  var uuid: PubNubUUIDMetadata? { get set }

  /// The associated Channel metadata
  var channel: PubNubChannelMetadata? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

    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

let oldMembership = PubNubMembershipMetadataBase(
  uuidMetadataId: "my_user", channelMetadataId: "my_channel"
)

pubnub.removeMemberships(
  uuid: oldMembership.uuidMetadataId,
  channels: [oldMembership]
) { result in
  switch result {
  case let .success(response):
    print("The channel memberships for the uuid \(response.memberships)")
    if let nextPage = response.next {
      print("The next page used for pagination: \(nextPage)")
    }
  case let .failure(error):
    print("Update Memberships request failed with error: \(error.localized### Description)")
  }
}

Channel Members

Get Channel Members

Description

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:

  1. fetchMembers(  channel: String?,  include: MemberInclude = MemberInclude(),  filter: String? = nil,  sort: [MembershipSortField] = [],  limit: Int? = 100,  page: PubNubHashedPage? = Page(),  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    channelStringYesUnique Channel Metadata identifier
    includeMemberIncludeOptionalMemberInclude()Whether to include the custom field in the fetch response
    filterString?OptionalnilExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
    sort[MembershipSortField]Optional[]List of properties to sort response objects. The following properties are valid for sorting: .object(.id), .object(.name), .object(.updated), and .updated.
    limitInt?Optional100The number of objects to retrieve at a time
    pagePubNubHashedPage?OptionalPubNub.Page()The paging object used for pagination
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?OptionalnilThe 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 UUID
  var uuidMetadataId: String { get }

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

  /// The associated UUID metadata
  var uuid: PubNubUUIDMetadata? { get set }

  /// The associated Channel metadata
  var channel: PubNubChannelMetadata? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

    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

pubnub.fetchMembers(channel: "my_channel") { result in
  switch result {
  case let .success(response):
    print("The uuid members for the channel \(response.memberships)")
    if let nextPage = response.next {
      print("The next page used for pagination: \(nextPage)")
    }
  case let .failure(error):
    print("Fetch Memberships request failed with error: \(error.localized### Description)")
  }
}

Set Channel Members

Description

This method sets members in a channel.

Method(s)

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

  1. setMembers(  channel metadataId: String,  uuids members: [PubNubMembershipMetadata],  include: MemberInclude = MemberInclude(),  filter: String? = nil,  sort: [MembershipSortField] = [],  limit: Int? = 100,  page: PubNubHashedPage? = Page(),  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    channelStringYesUnique Channel identifier.
    uuids[PubNubMembershipMetadata]YesArray of PubNubMembershipMetadata with the PubNubUUIDMetadata or uuidMetadataId provided
    includeMemberIncludeOptionalMemberInclude()Whether to include the custom field in the fetch response
    filterString?OptionalnilExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
    sort[MembershipSortField]Optional[]List of properties to sort response objects. The following properties are valid for sorting: .object(.id), .object(.name), .object(.updated), and .updated.
    limitInt?Optional100The number of objects to retrieve at a time
    pagePubNubHashedPage?OptionalPubNub.Page()The paging object used for pagination
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?OptionalnilThe 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 UUID
  var uuidMetadataId: String { get }

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

  /// The associated UUID metadata
  var uuid: PubNubUUIDMetadata? { get set }

  /// The associated Channel metadata
  var channel: PubNubChannelMetadata? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

    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

let newMembership = PubNubMembershipMetadataBase(
  uuidMetadataId: "my_user", channelMetadataId: "my_channel"
)

pubnub.setMemberships(
  channel: newMembership.channelMetadataId,
  uuids: [newMembership]
) { result in
  switch result {
  case let .success(response):
    print("The channel memberships for the uuid \(response.memberships)")
    if let nextPage = response.next {
      print("The next page used for pagination: \(nextPage)")
    }
  case let .failure(error):
    print("Update Memberships request failed with error: \(error.localized### Description)")
  }
}

Remove Channel Members

Description

Remove members from a Channel.

Method(s)

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

  1. removeMembers(  channel metadataId: String,  uuids members: [PubNubMembershipMetadata],  include: MemberInclude = MemberInclude(),  filter: String? = nil,  sort: [MembershipSortField] = [],  limit: Int? = 100,  page: PubNubHashedPage? = Page(),  custom requestConfig: RequestConfiguration = RequestConfiguration(),  completion: ((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?)
    ParameterTypeRequiredDefaultsDescription
    channelStringYesUnique Channel identifier.
    uuids[PubNubMembershipMetadata]YesArray of PubNubMembershipMetadata with the PubNubUUIDMetadata or uuidMetadataId provided
    includeMemberIncludeOptionalMemberInclude()Whether to include the custom field in the fetch response
    filterString?OptionalnilExpression used to filter the results. Only objects whose properties satisfy the given expression are returned. The filter language is defined here
    sort[MembershipSortField]Optional[]List of properties to sort response objects. The following properties are valid for sorting: .object(.id), .object(.name), .object(.updated), and .updated.
    limitInt?Optional100The number of objects to retrieve at a time
    pagePubNubHashedPage?OptionalPubNub.Page()The paging object used for pagination
    customRequestConfigurationOptionalRequestConfiguration()An object that allows for per-request customization of PubNub Configuration or Network Session
    completion((Result<(memberships: [PubNubMembershipMetadata], next: PubNubHashedPageBase?), Error>) -> Void)?OptionalnilThe 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 UUID
  var uuidMetadataId: String { get }

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

  /// The associated UUID metadata
  var uuid: PubNubUUIDMetadata? { get set }

  /// The associated Channel metadata
  var channel: PubNubChannelMetadata? { get set }

  /// The last updated timestamp for the object
  var updated: Date? { get set }

  /// The caching identifier for the object
  var eTag: String? { get set }

  /// All custom fields set on the object
  var custom: [String: JSONCodableScalar]? { get set }
}

    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

let oldMembership = PubNubMembershipMetadataBase(
  uuidMetadataId: "my_user", channelMetadataId: "my_channel"
)

pubnub.removeMembers(
  channel: oldMembership.channelMetadataId,
  uuids: [oldMembership]
) { result in
  switch result {
  case let .success(response):
    print("The channel memberships for the uuid \(response.memberships)")
    if let nextPage = response.next {
      print("The next page used for pagination: \(nextPage)")
    }
  case let .failure(error):
    print("Update Memberships request failed with error: \(error.localized### Description)")
  }
}

Objects Filtering Language Definition

The filtering language for Objects is similar to the stream filtering language.

Note the following:

  • Date/time properties, such as updated, must be compared to valid date/time strings formatted according to ISO 8601.
  • Custom properties must have the same type as the value used in the expression; it is an error to compare a custom property of one type to a value of another type.
  • Objects that do not have the referenced custom property at all are excluded regardless of the operator or value used in the expression. The null value can be used to filter out objects that do or do not have the referenced custom property.
  • The LIKE operator supports wildcards denoted by the * character. A wildcard matches any sequence of arbitrary Unicode characters, including the empty sequence. The literal asterisk is matched when escaped using the backslash (\) character.
  • Values used with LIKE must be properly encoded just like any other string value. Thus, in order to escape an asterisk, the raw value must contain \\*.
  • The entire expression must be properly URL-encoded when used in the query string.
<expression>           ::= <and_expression> ( "||" <and_expression> )*
<and_expression>       ::= <binary_condition> ( "&&" <binary_condition> )*
<binary_condition>     ::= "!" <binary_condition> | "(" <expression> ")" | <relational_condition>
<relational_condition> ::= <property_path> <relational_operator> <value>
<property_path>        ::= <property_name> ( "." <property_name> )*
<property_name>        ::= <identifier> | "[" <string> "]"
<value>                ::= <string> | <number> | "true" | "false" | "null"

Tokens

<identifier>           ::=  <letter> | "$" | "_" ( <letter> | "$" | "_" | <digit> )*
<relational_operator>  ::= "==" | "!=" | "<=" | ">=" | "<" | ">" | "LIKE"
<string>               ::= <double_quote> ( "\" <double_quote> | "\" <special_char>
                            | "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
                            | <unicode_char> - <double_quote> - "\" )* <double_quote>
                            | "'" ( "\" "'" | "\" <special_char>
                            | "\" "u" <hex_digit> <hex_digit> <hex_digit> <hex_digit>
                            | <unicode_char> - "'" - "\" )* "'"
<number>               ::= ( "+" | "-" )? ( <digit> )* ( "." )? <digit> ( <digit> )*
                            ( "e" | "E" ( "+" | "-" )? <digit> ( <digit> )* )?
<letter>               ::= Unicode Letter (category; any kind of letter from any language)
<digit>                ::= "0" .. "9"
<hex_digit>            ::= <digit> | "A" .. "F"
<double_quote>         ::= the " character
<unicode_char>         ::= any character in the Unicode range from U+0020 to U+10FFFF inclusive
<special_char>         ::= "\" | "/" | "b" | "f" | "n" | "r" | "t"

Sample object filtering operations

The following simple expression returns results whose custom property named public is equal to Boolean true.

custom.public == true

The following date/time comparison returns results that were modified on or after August 31st, 2019 (UTC):

updated >= "2019-08-31T00:00:00Z"

The following compound expression returns results that don't have a description, but do have a non-empty custom label or description property:

description == null && (custom.label != "" || custom.description != "")

The following wildcard expression returns results whose name starts with the letter X:

name LIKE 'X*'

The following escaped wildcard expression returns results whose name contains an asterisk:

name LIKE '*\\**'
← Mobile PushFiles →