App Context API for Cocoa Objective-C 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 changed: set, updated, or removed from the database. At the same time, making a request to set the same data that already exist, doesn't trigger any event. Clients can receive these events in real time and update their front-end application accordingly.

User​

Get Metadata for All Users​

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 Cocoa SDK:

- (void)allUUIDMetadataWithRequest:(PNFetchAllUUIDMetadataRequest *)request
                        completion:(PNFetchAllUUIDMetadataCompletionBlock)block;
* required
ParameterDescription
request *
Fetch all UUID metadata request object with all information which should be used to fetch existing UUID metadata.
block *
Type: PNFetchAllUUIDMetadataCompletionBlock
Fetch all UUID metadata request completion block.

PNFetchAllUUIDMetadataRequest​

* required
ParameterDescription
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, Use asc or desc to specify sort direction
includeFields
Type: PNUUIDFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNUUIDTotalCountField - include how many UUID has been associated with metadata.
  • PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests.
Default value (PNUUIDTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified.

Basic Usage​

PNFetchAllUUIDMetadataRequest *request = [PNFetchAllUUIDMetadataRequest new];
request.start = @"<next from previous request>";
// Add this request option, if returned metadata models should have value which has been set to
// 'custom' property.
request.includeFields = PNUUIDCustomField | PNUUIDTotalCountField;
request.limit = 40;

[self.client allUUIDMetadataWithRequest:request
                             completion:^(PNFetchAllUUIDMetadataResult *result, PNErrorStatus *status) {

    if (!status.isError) {
        /**
         * UUID metadata successfully fetched.
         * Result object has following information:
         *   result.data.metadata - List of fetched UUID metadata.
show all 28 lines

Response​

Response objects which is returned by client when fetch all UUID metadata Object API is used:

@interface PNFetchAllUUIDMetadataData : PNServiceData

// List of UUID metadata objects created for current subscribe key.
@property (nonatomic, readonly, strong) NSArray<PNUUIDMetadata *> *metadata;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of objects created for current subscribe key.
 *
 * Value will be 0 in case if PNUUIDTotalCountField not added to 'includeFields'
show all 27 lines

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Get Metadata for All Users (Builder Pattern)​

Method(s)​

objects()
    .allUUIDMetadata()
    .includeFields(PNUUIDFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(PNFetchAllUUIDMetadataCompletionBlock);
* required
ParameterDescription
includeFields
Type: PNUUIDFields
PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests.
includeCount
Type: BOOL
Whether total count of objects should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block *
Type: PNFetchAllUUIDMetadataCompletionBlock
Associated metadata fetch completion handler block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().allUUIDMetadata()
    .start(@"<next from previous request>")
    .includeFields(PNUUIDCustomField)
    .includeCount(YES)
    .limit(40)
    .performWithCompletion(^(PNFetchAllUUIDMetadataResult *result, PNErrorStatus *status) {
        if (!status.isError) {
            /**
             * UUID metadata successfully fetched.
             * Result object has following information:
             *   result.data.metadata - List of fetched UUID metadata.
             *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
             *   result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
             *   result.data.totalCount - Total number of created UUID metadata.
             */
show all 24 lines

Response​

Response objects which is returned by client when fetch all UUID metadata Object API is used:

@interface PNFetchAllUUIDMetadataData : PNServiceData

// List of UUID metadata objects created for current subscribe key.
@property (nonatomic, readonly, strong) NSArray<PNUUIDMetadata *> *metadata;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of objects created for current subscribe key.
 *
 * Value will be 0 in case if PNUUIDTotalCountField not added to 'includeFields'
show all 27 lines

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Get User Metadata​

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 Cocoa SDK:

- (void)uuidMetadataWithRequest:(PNFetchUUIDMetadataRequest *)request
                     completion:(PNFetchUUIDMetadataCompletionBlock)block;
* required
ParameterDescription
request *
Fetch UUID metadata request with all information which should be used to fetch existing UUID metadata.
block *
Type: PNFetchUUIDMetadataCompletionBlock
Fetch UUID metadata request completion block.

PNFetchUUIDMetadataRequest​

* required
ParameterDescription
includeFields
Type: PNUUIDFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests.
Default value (PNUUIDCustomField) can be reset by setting 0.
uuid
Type: NSString
Create and configure fetch UUID metadata request. uuid - Identifier for metadata should be fetched. Will be set to current PubNub configuration uuid if nil is set.

Basic Usage​

PNFetchUUIDMetadataRequest *request = [PNFetchUUIDMetadataRequest requestWithUUID:@"uuid"];
// Add this request option, if returned metadata model should have value which has been set to
// 'custom' property.
request.includeFields = PNUUIDCustomField;

[self.client uuidMetadataWithRequest:request
                          completion:^(PNFetchUUIDMetadataResult *result, PNErrorStatus *status) {

    if (!status.isError) {
        /**
         * UUID metadata successfully fetched.
         * Fetched UUID metadata information available here: result.data.metadata
         */
    } else {
        /**
show all 22 lines

Response​

Response objects which is returned by client when fetch UUID metadata Object API is used:

@interface PNFetchUUIDMetadataData : PNServiceData

// Requested UUID metadata object.
@property (nonatomic, nullable, readonly, strong) PNUUIDMetadata *metadata;

@end

@interface PNFetchUUIDMetadataResult : PNResult

// Fetch UUID metadata request processed information.
@property (nonatomic, readonly, strong) PNFetchUUIDMetadataData *data;

@end

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Get User Metadata (Builder Pattern)​

Method(s)​

objects()
    .uuidMetadata()
    .uuid(NSString *)
    .includeFields(PNUUIDFields)
    .performWithCompletion(PNFetchUUIDMetadataCompletionBlock);
* required
ParameterDescription
uuid
Type: NSString
Identifier for which associated metadata should be fetched. Default: configured PubNub client uuid
includeFields
Type: PNUUIDMFields
PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests. Default: PNUUIDCustomField Default value can be reset by setting 0
block *
Type: PNFetchUUIDMetadataCompletionBlock
Fetch UUID metadata request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().uuidMetadata()
    .uuid(@"uuid")
    .includeFields(PNUUIDCustomField)
    .performWithCompletion(^(PNFetchUUIDMetadataResult *result, PNErrorStatus *status) {
      if (!status.isError) {
          /**
           * UUID metadata successfully fetched.
           * Fetched UUID metadata information available here: result.data.metadata
           */
      } else {
          /**
           * Handle UUID metadata fetch error. Check 'category' property to find out possible issue
           * because of which request did fail.
           *
           * Request can be resent using: [status retry]
show all 18 lines

Response​

Response objects which is returned by client when fetch UUID metadata Object API is used:

@interface PNFetchUUIDMetadataData : PNServiceData

// Requested UUID metadata object.
@property (nonatomic, nullable, readonly, strong) PNUUIDMetadata *metadata;

@end

@interface PNFetchUUIDMetadataResult : PNResult

// Fetch UUID metadata request processed information.
@property (nonatomic, readonly, strong) PNFetchUUIDMetadataData *data;

@end

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

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:

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

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 Cocoa SDK:

- (void)setUUIDMetadataWithRequest:(PNSetUUIDMetadataRequest *)request
                        completion:(nullable PNSetUUIDMetadataCompletionBlock)block;
* required
ParameterDescription
request *
Set UUID metadata request with all information which should be associated with UUID.
block
Type: PNSetUUIDMetadataCompletionBlock
Set UUID metadata request completion block.

PNSetUUIDMetadataRequest​

* required
ParameterDescription
custom
Type: NSDictionary
Additional / complex attributes which should be associated with metadata.
externalId
Type: NSString
Identifier from external service (database, auth service).
profileUrl
Type: NSString
URL at which profile available.
includeFields
Type: PNUUIDFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests.
Default value (PNUUIDCustomField) can be reset by setting 0.
email
Type: NSString
Email address.
name
Type: NSString
Name which should be stored in metadata associated with specified identifier.
uuid
Type: NSString
Create and configure set UUID metadata request. uuid - Identifier with which metadata is linked. Will be set to current PubNub configuration uuid if nil is set.
API limits

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

Basic Usage​

PNSetUUIDMetadataRequest *request = [PNSetUUIDMetadataRequest requestWithUUID:@"uuid"];
// With this option on, returned metadata model will have value which has been set to 'custom'
// property.
request.includeFields = PNUUIDCustomField;
request.custom = @{ @"age": @(39), @"status": @"Checking some stuff..." };
request.email = @"support@pubnub.com";
request.name = @"David";

[self.client setUUIDMetadataWithRequest:request completion:^(PNSetUUIDMetadataStatus *status) {
    if (!status.isError) {
        /**
         * UUID metadata successfully has been set.
         * UUID metadata information available here: status.data.metadata
         */
    } else {
show all 23 lines

Response​

Response objects which is returned by client when set UUID metadata Object API is used:

@interface PNSetUUIDMetadataData : PNServiceData

// Updated UUID metadata object.
@property (nonatomic, nullable, readonly, strong) PNUUIDMetadata *metadata;

@end

@interface PNSetUUIDMetadataStatus : PNAcknowledgmentStatus

// Set UUID metadata request processed information.
@property (nonatomic, readonly, strong) PNSetUUIDMetadataData *data;

@end

Set User Metadata (Builder Pattern)​

Method(s)​

objects()
    .setUUIDMetadata()
    .uuid(NSString *)
    .name(NSString *)
    .externalId(NSString *)
    .profileUrl(NSString *)
    .custom(NSDictionary *)
    .email(NSString *)
    .includeFields(PNUUIDFields)
    .performWithCompletion(nullable PNSetUUIDMetadataCompletionBlock);
API limits

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

* required
ParameterDescription
uuid
Type: NSString
Identifier with which new metadata should be associated. Default: configured PubNub client uuid
name
Type: NSString
Name which should stored in metadata associated with specified UUID.
externalId
Type: NSString
External identifier (database, auth service) associated with specified UUID.
profileUrl
Type: NSString
External URL with information for specified UUID representation.
custom
Type: NSDictionary
Additional information which should be stored in metadata associated with specified UUID.
email
Type: NSString
Email address which should be stored in metadata associated with specified UUID.
includeFields
Type: PNUUIDFields
PNUUIDCustomField - include field with additional information from metadata which has been used during UUID metadata set requests. Default: PNUUIDCustomField Default value can be reset by setting 0.
block
Type: PNSetUUIDMetadataCompletionBlock
Set UUID metadata request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().setUUIDMetadata()
    .uuid(@"uuid")
    .name(@"Serhii")
    .externalId(@"93FVfHUAf4RLu79J7Q3ejLVu")
    .profileUrl(@"https://pubnub.com")
    .custom(@{ @"age": @(36) })
    .email(@"support@pubnub.com")
    .includeFields(PNUUIDCustomField)
    .performWithCompletion(^(PNSetUUIDMetadataStatus *status) {
        if (!status.isError) {
            /**
             * UUID metadata successfully has been set.
             * UUID metadata information available here: status.data.metadata
             */
        } else {
show all 23 lines

Response​

Response objects which is returned by client when set UUID metadata Object API is used:

@interface PNSetUUIDMetadataData : PNServiceData

// Updated UUID metadata object.
@property (nonatomic, nullable, readonly, strong) PNUUIDMetadata *metadata;

@end

@interface PNSetUUIDMetadataStatus : PNAcknowledgmentStatus

// Set UUID metadata request processed information.
@property (nonatomic, readonly, strong) PNSetUUIDMetadataData *data;

@end

Remove User Metadata​

Removes the metadata from a specified UUID.

Method(s)​

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

- (void)removeUUIDMetadataWithRequest:(PNRemoveUUIDMetadataRequest *)request
                           completion:(nullable PNRemoveUUIDMetadataCompletionBlock)block;
* required
ParameterDescription
request *
Remove UUID metadata request with information about existing metadata.
block
Type: PNRemoveUUIDMetadataCompletionBlock
Remove UUID metadata request completion block.

PNRemoveUUIDMetadataRequest​

* required
ParameterDescription
uuid
Type: NSString
Create and configure delete user request. identifier - Create and configure remove UUID metadata request. Will be set to current PubNub configuration uuid if nil is set.

Basic Usage​

PNRemoveUUIDMetadataRequest *request = [PNRemoveUUIDMetadataRequest requestWithUUID:@"uuid"];

[self.client removeUUIDMetadataWithRequest:request completion:^(PNAcknowledgmentStatus *status) {
    if (!status.isError) {
        // UUID metadata successfully removed.
    } else {
        /**
         * Handle UUID metadata remove error. Check 'category' property to find out possible
         * issue because of which request did fail.
         *
         * Request can be resent using: [status retry]
         */
    }
}];

Response​

Response objects which is returned by client when remove UUID metadata Object API is used:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNAcknowledgmentStatus : PNErrorStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Remove User Metadata (Builder Pattern)​

Method(s)​

objects()
    .removeUUIDMetadata()
    .uuid(NSString *)
    .performWithCompletion(nullable PNFetchUUIDMetadataCompletionBlock);
* required
ParameterDescription
uuid
Type: NSString
Identifier for which associated metadata should be removed. Default: configured PubNub client uuid
block
Type: PNRemoveUUIDMetadataCompletionBlock
Remove UUID metadata request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().removeUUIDMetadata()
    .uuid(@"uuid")
    .performWithCompletion(^(PNAcknowledgmentStatus *status) {
        if (!status.isError) {
             // User successfully deleted.
        } else {
            /**
             * Handle user delete error. Check 'category' property to find out possible issue
             * because of which request did fail.
             *
             * Request can be resent using: [status retry]
             */
        }
    });

Response​

Response objects which is returned by client when remove UUID metadata Object API is used:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNAcknowledgmentStatus : PNErrorStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

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 Cocoa SDK:

- (void)allChannelsMetadataWithRequest:(PNFetchAllChannelsMetadataRequest *)request
                            completion:(PNFetchAllChannelsMetadataCompletionBlock)block;
* required
ParameterDescription
request *
Fetch all UUID metadata request object with all information which should be used to fetch existing UUID metadata.
block *
Type: PNFetchAllChannelsMetadataCompletionBlock
Fetch all UUID metadata request completion block.

PNFetchAllChannelsMetadataRequest​

* required
ParameterDescription
includeFields
Type: PNChannelFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNChannelTotalCountField - include how many channels has been associated with metadata.
  • PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests.
Default value (PNChannelTotalCountField) can be reset by setting 0.
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. Use asc or desc to specify sort direction
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified.

Basic Usage​

PNFetchAllChannelsMetadataRequest *request = [PNFetchAllChannelsMetadataRequest new];
request.start = @"<next from previous request>";
// Add this request option, if returned metadata models should have value which has been set to
// 'custom' property.
request.includeFields = PNUUIDCustomField | PNUUIDTotalCountField;
request.limit = 40;

[self.client allChannelsMetadataWithRequest:request
                                 completion:^(PNFetchAllChannelsMetadataResult *result, PNErrorStatus *status) {
    if (!status.isError) {
        /**
         * Channels metadata successfully fetched.
         * Result object has following information:
         *   result.data.metadata - List of fetched channels metadata.
         *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
show all 26 lines

Response​

Response objects which is returned by client when fetch all UUID metadata Object API is used:

@interface PNFetchAllChannelsMetadataData : PNServiceData

// List of channels metadata objects created for current subscribe key.
@property (nonatomic, readonly, strong) NSArray<PNChannelMetadata *> *metadata;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of objects created for current subscribe key.
 *
 * Value will be 0 in case if PNChannelTotalCountField not added to 'includeFields'
show all 27 lines

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Get Metadata for All Channels (Builder Pattern)​

Method(s)​

objects()
    .allChannelsMetadata()
    .includeFields(PNChannelFields)
    .includeCount(BOOL)
    .filter(NSString)
    .sort(NSArray)
    .limit(NSUInteger)
    .start(NSString)
    .end(NSString)
    .performWithCompletion(PNFetchChannelMetadataCompletionBlock);
* required
ParameterDescription
includeFields
Type: PNChannelFields
PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests.
includeCount
Type: BOOL
Whether total count of objects should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block *
Type: PNFetchAllChannelsMetadataCompletionBlock
Fetch all UUID metadata request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().allChannelsMetadata()
    .start(@"<next from previous request>")
    .includeFields(PNChannelCustomField)
    .includeCount(YES)
    .limit(40)
    .performWithCompletion(^(PNFetchAllChannelsMetadataResult *result, PNErrorStatus *status) {
        if (!status.isError) {
            /**
             * Channels metadata successfully fetched.
             * Result object has following information:
             *   result.data.metadata - List of fetched channels metadata.
             *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
             *   result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
             *   result.data.totalCount - Total number of associated channel metadata.
        } else {
show all 23 lines

Response​

Response objects which is returned by client when fetch all UUID metadata Object API is used:

@interface PNFetchAllChannelsMetadataData : PNServiceData

// List of channels metadata objects created for current subscribe key.
@property (nonatomic, readonly, strong) NSArray<PNChannelMetadata *> *metadata;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of objects created for current subscribe key.
 *
 * Value will be 0 in case if PNChannelTotalCountField not added to 'includeFields'
show all 27 lines

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

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 Cocoa SDK:

- (void)channelMetadataWithRequest:(PNFetchChannelMetadataRequest *)request
                        completion:(PNFetchChannelMetadataCompletionBlock)block;
* required
ParameterDescription
request *
Fetch channel metadata request with all information which should be used to fetch existing channel metadata.
block *
Type: PNFetchChannelMetadataCompletionBlock
Fetch channel metadata request completion block.

PNFetchChannelMetadataRequest​

* required
ParameterDescription
includeFields
Type: PNChannelFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests.
Default value (PNChannelCustomField) can be reset by setting 0.
channel
Type: NSString
Create and configure fetch channel metadata request. channel - Name of channel for which metadata should be fetched.

Basic Usage​

PNFetchChannelMetadataRequest *request = [PNFetchChannelMetadataRequest requestWithChannel:@"channel"];
// Add this request option, if returned metadata model should have value which has been set to
// 'custom' property.
request.includeFields = PNChannelCustomField;

[self.client channelMetadataWithRequest:request
                             completion:^(PNFetchChannelsMetadataResult *result, PNErrorStatus *status) {

    if (!status.isError) {
        /**
         * Channel metadata successfully fetched.
         * Channel metadata information available here: result.data.metadata
         */
    } else {
        /**
show all 22 lines

Response​

Response objects which is returned by client when fetch channel metadata Object API is used:

@interface PNFetchChannelMetadataData : PNServiceData

// Requested channel metadata object.
@property (nonatomic, nullable, readonly, strong) PNChannelMetadata *metadata;

@end

@interface PNFetchChannelsMetadataResult : PNResult

// Fetch channel metadata request processed information.
@property (nonatomic, readonly, strong) PNFetchChannelMetadataData *data;

@end

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Get Channel Metadata (Builder Pattern)​

Method(s)​

objects()
    .channelMetadata(NSString *)
    .includeFields(PNChannelFields)
    .performWithCompletion(PNFetchChannelMetadataCompletionBlock);
* required
ParameterDescription
channel *
Type: NSString
Name of channel for which associated metadata should be fetched.
includeFields
Type: NSString
PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests. Default: PNChannelCustomField Default value can be reset by setting 0
block *
Type: PNFetchChannelMetadataCompletionBlock
Fetch channel metadata request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().channelMetadata(@"channel")
    .includeFields(PNChannelCustomField)
    .performWithCompletion(^(PNFetchChannelsMetadataResult *result, PNErrorStatus *status) {
        if (!status.isError) {
            /**
             * Channel metadata successfully fetched.
             * Channel metadata information available here: result.data.metadata
             */
        } else {
            /**
             * Handle channel metadata fetch error. Check 'category' property to find out possible
             * issue because of which request did fail.
             *
             * Request can be resent using: [status retry]
             */
show all 17 lines

Response​

Response objects which is returned by client when fetch channel metadata Object API is used:

@interface PNFetchChannelMetadataData : PNServiceData

// Requested channel metadata object.
@property (nonatomic, nullable, readonly, strong) PNChannelMetadata *metadata;

@end

@interface PNFetchChannelsMetadataResult : PNResult

// Fetch channel metadata request processed information.
@property (nonatomic, readonly, strong) PNFetchChannelMetadataData *data;

@end

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

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:

  1. Get the existing metadata and store it locally.
  2. Append the new custom metadata to the existing one.
  3. 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 Cocoa SDK:

- (void)setChannelMetadataWithRequest:(PNSetChannelMetadataRequest *)request
                           completion:(nullable PNSetChannelMetadataCompletionBlock)block;
* required
ParameterDescription
request *
Set channel metadata request with all information which should be associated with channel.
block
Type: PNSetChannelMetadataCompletionBlock
Set channel metadata request completion block.

PNSetChannelMetadataRequest​

* required
ParameterDescription
custom
Type: NSDictionary
Additional / complex attributes which should be stored in metadata associated with specified channel. App Context filtering language doesn’t support filtering by custom properties.
information
Type: NSString
Description which should be stored in metadata associated with specified channel.
includeFields
Type: PNChannelFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests.
Default value (PNChannelCustomField) can be reset by setting 0.
name
Type: NSString
Name which should be stored in metadata associated with specified channel.
channel
Type: NSString
Create and configure set channel metadata request. channel - Name of channel for which metadata should be set.
API limits

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

Basic Usage​

PNSetChannelMetadataRequest *request = [PNSetChannelMetadataRequest requestWithChannel:@"channel"];
// Add this request option, if returned metadata model should have value which has been set to
// 'custom' property.
request.includeFields = PNChannelCustomField;
request.custom = @{ @"responsibilities": @"Manage tests", @"status": @"offline" };
request.name = @"Updated channel name";

[self.client setChannelMetadataWithRequest:request completion:^(PNSetChannelMetadataStatus *status) {
    if (!status.isError) {
        /**
         * Channel metadata successfully has been set.
         * Channel metadata information available here: status.data.metadata
         */
    } else {
        /**
show all 22 lines

Response​

Response objects which is returned by client when set channel metadata Object API is used:

@interface PNSetChannelMetadataData : PNServiceData

// Associated channel's metadata object.
@property (nonatomic, nullable, readonly, strong) PNChannelMetadata *metadata;

@end

@interface PNSetChannelMetadataStatus : PNAcknowledgmentStatus

// Set channel metadata request processed information.
@property (nonatomic, readonly, strong) PNSetChannelMetadataData *data;

@end

Other Examples​

Iteratively update existing metadata​
#import <Foundation/Foundation.h>
#import <PubNub/PubNub.h>

void showHelp() {
    printf("\tTo exit type '/exit'\n\tTo show the current object type '/show'\n\tTo show this help type '/help'\n\n");
}

int main(int argc, const char *argv[]) {
    @autoreleasepool {
        PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@"demo"
                                                                         subscribeKey:@"demo"];
        configuration.uuid = @"example";

        PubNub *pubnub = [PubNub clientWithConfiguration:configuration];
        NSString *channel = @"demo_example";
show all 110 lines

Set Channel Metadata (Builder Pattern)​

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:

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

Method(s)​

objects()
    .setChannelMetadata(NSString *)
    .includeFields(PNChannelFields)
    .channel(NSString)
    .name(NSString)
    .information(NSString)
    .custom(NSDictionary)
    .performWithCompletion(nullable PNFetchChannelMetadataCompletionBlock);
API limits

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

* required
ParameterDescription
channel *
Type: NSString
Name of channel with which new metadata should be associated.
name
Type: NSString
Name which should stored in metadata associated with specified channel.
information
Type: NSString
Description which should be stored in metadata associated with specified channel.
custom
Type: NSDictionary
Additional information which should be stored in metadata associated with specified channel. App Context filtering language doesn’t support filtering by custom properties.
includeFields
Type: PNChannelFields
PNChannelCustomField - include field with additional information from metadata which has been used during channel metadata set requests. Default: PNChannelCustomField Default value can be reset by setting 0.
block
Type: PNSetChannelMetadataCompletionBlock
Set channel metadata request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().setChannelMetadata(@"channel")
    .name(@"Admin")
    .information(@"Administrative channel")
    .custom(@{ @"responsibilities": @"Manage access to protected resources" })
    .includeFields(PNChannelCustomField)
    .performWithCompletion(^(PNSetChannelMetadataStatus *status) {
      if (!status.isError) {
          /**
           * Channel metadata successfully has been set.
           * Channel metadata information available here: status.data.metadata
           */
      } else {
          /**
           * Handle channel metadata update error. Check 'category' property to find out possible
           * issue because of which request did fail.
show all 20 lines

Response​

Response objects which is returned by client when set channel metadata Object API is used:

@interface PNSetChannelMetadataData : PNServiceData

// Associated channel's metadata object.
@property (nonatomic, nullable, readonly, strong) PNChannelMetadata *metadata;

@end

@interface PNSetChannelMetadataStatus : PNAcknowledgmentStatus

// Set channel metadata request processed information.
@property (nonatomic, readonly, strong) PNSetChannelMetadataData *data;

@end

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 Cocoa SDK:

- (void)removeChannelMetadataWithRequest:(PNRemoveChannelMetadataRequest *)request
                              completion:(nullable PNRemoveChannelMetadataCompletionBlock)block;
* required
ParameterDescription
request *
Remove channel metadata request with information about existing metadata.
block
Type: PNRemoveChannelMetadataCompletionBlock
Remove channel metadata request completion block.

PNRemoveChannelMetadataRequest​

* required
ParameterDescription
channel
Type: NSString
Create and configure remove channel metadata request. channel - Name of channel for which metadata should be removed.

Basic Usage​

PNRemoveChannelMetadataRequest *request = [PNRemoveChannelMetadataRequest requestWithChannel:@"channel"];

[self.client removeChannelMetadataWithRequest:request completion:^(PNAcknowledgmentStatus *status) {
    if (!status.isError) {
        // Channel metadata successfully removed.
    } else {
        /**
         * Handle channel metadata remove error. Check 'category' property to find out possible
         * issue because of which request did fail.
         *
         * Request can be resent using: [status retry]
         */
    }
}];

Response​

Response objects which is returned by client when remove channel metadata Object API is used:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNAcknowledgmentStatus : PNErrorStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Remove Channel Metadata (Builder Pattern)​

Method(s)​

objects()
    .removeChannelMetadata(NSString *)
    .performWithCompletion(nullable PNRemoveChannelMetadataCompletionBlock);
* required
ParameterDescription
channel *
Type: NSString
Name of channel for which associated metadata should be removed.
block
Type: PNRemoveChannelMetadataCompletionBlock
Remove channel metadata request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().removeChannelMetadata(@"channel")
    .performWithCompletion(^(PNAcknowledgmentStatus *status) {
        if (!status.isError) {
            // Channel metadata successfully removed.
        } else {
            /**
             * Handle channel metadata remove error. Check 'category' property to find out possible
             * issue because of which request did fail.
             *
             * Request can be resent using: [status retry]
             */
        }
    });

Response​

Response objects which is returned by client when remove channel metadata Object API is used:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNAcknowledgmentStatus : PNErrorStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

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 Cocoa SDK:

- (void)membershipsWithRequest:(PNFetchMembershipsRequest *)request
                    completion:(PNFetchMembershipsCompletionBlock)block;
* required
ParameterDescription
request *
Fetch UUID's memberships request with all information which should be used to fetch existing UUID's memberships.
block *
Type: PNFetchMembershipsCompletionBlock
Fetch UUID's memberships request completion block.

PNFetchMembershipsRequest​

* required
ParameterDescription
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. Use asc or desc to specify sort direction.
includeFields
Type: NSArray<NSString *>
Bitfield set to fields which should be returned with response. Supported fields:
  • PNMembershipsTotalCountField - include how many memberships UUID has.
  • PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership add requests.
  • PNMembershipChannelField - include channel's metadata into response (not only name).
  • PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests.
Default value (PNMembershipsTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of members to return in response. Will be set to 100 (which is also maximum value) if not specified.

Basic Usage​

PNFetchMembershipsRequest *request = [PNFetchMembershipsRequest requestWithUUID:@"uuid"];
request.start = @"<next from previous request>";
// Add this request option, if returned membership models should have value which has been set to
// 'custom' and 'channel' properties.
request.includeFields = PNMembershipCustomField | PNMembershipChannelField | PNMembershipsTotalCountField;
request.limit = 40;

[self.client membershipsWithRequest:request
                         completion:^(PNFetchMembershipsResult *result, PNErrorStatus *status) {

    if (!status.isError) {
        /**
         * UUID's memberships successfully fetched.
         * Result object has following information:
         *   result.data.memberships - List of UUID's memberships.
show all 28 lines

Response​

Response objects which is returned by client when fetch memberships Object API is used:

@interface PNFetchMembershipsData : PNServiceData

// List of fetched memberships.
@property (nonatomic, readonly, strong) NSArray<PNMembership *> *memberships;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of members created for current subscribe key.
 *
 * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields'
show all 28 lines

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Get Channel Memberships (Builder Pattern)​

Method(s)​

objects()
    .memberships()
    .uuid(NSString *)
    .includeFields(PNMembershipFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(PNFetchMembershipsCompletionBlock);
* required
ParameterDescription
uuid
Type: NSString
Name of channel from which members should be fetched.
includeFields
Type: PNMembershipFields
  • PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership set requests.
  • PNMembershipChannelField - include channel's metadata into response (not only name).
  • PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests.
includeCount
Type: BOOL
Whether total count of objects should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block *
Type: PNFetchMembershipsCompletionBlock
Fetch UUID's memberships request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().memberships()
    .uuid(@"uuid")
    .includeCount(YES)
    .limit(40)
    .includeFields(PNMembershipCustomField | PNMembershipChannelField)
    .performWithCompletion(^(PNFetchMembershipsResult *result, PNErrorStatus *status) {
        if (!status.isError) {
            /**
             * UUID's memberships successfully fetched.
             * Result object has following information:
             *   result.data.memberships - List of UUID's memberships.
             *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
             *   result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
             *   result.data.totalCount - Total number of UUID's memberships.
             */
show all 24 lines

Response​

Response objects which is returned by client when fetch memberships Object API is used:

@interface PNFetchMembershipsData : PNServiceData

// List of fetched memberships.
@property (nonatomic, readonly, strong) NSArray<PNMembership *> *memberships;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of members created for current subscribe key.
 *
 * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields'
show all 28 lines

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Set Channel Memberships​

Set channel memberships for a UUID.

Method(s)​

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

- (void)setMembershipsWithRequest:(PNSetMembershipsRequest *)request
                       completion:(nullable PNManageMembershipsCompletionBlock)block;
* required
ParameterDescription
request *
Set UUID's memberships request with information which should be used to set channels membership.
block
Type: PNManageMembershipsCompletionBlock
Set UUID's memberships request completion block.

PNSetMembershipsRequest​

* required
ParameterDescription
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. Use asc or desc to specify sort direction.
includeFields
Type: PNMembershipFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNMembershipsTotalCountField - include how many memberships UUID has.
  • PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership add requests.
  • PNMembershipChannelField - include channel's metadata into response (not only name).
  • PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests.
Default value (PNMembershipsTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified.
API limits

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

Basic Usage​

NSArray<NSDictionary *> *channels = @[
  @{ @"channel": @"channel1", @"custom": @{ @"role": @"moderator" } }
];

PNSetMembershipsRequest *request = [PNSetMembershipsRequest requestWithUUID:@"uuid"
                                                                   channels:channels];
// Add this request option, if returned membership models should have value which has been set to
// 'custom' and 'channel' properties.
request.includeFields = PNMembershipCustomField | PNMembershipChannelField | PNMembershipsTotalCountField;
request.limit = 40;

[self.client setMembershipsWithRequest:request completion:^(PNManageMembershipsStatus *status) {
    if (!status.isError) {
        /**
         * UUID's memberships successfully set.
show all 30 lines

Response​

Response objects which is returned by client when set memberships Object API is used:

@interface PNManageMembershipsData : PNServiceData

// List of existing memberships.
@property (nonatomic, readonly, strong) NSArray<PNMembership *> *memberships;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields'
show all 28 lines

Set Channel Memberships (Builder Pattern)​

Method(s)​

objects()
    .setMemberships()
    .uuid(NSString *)
    .channels(NSArray<NSDictionary *> *)
    .includeFields(PNMembershipFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(nullable PNManageMembershipsCompletionBlock);
API limits

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

* required
ParameterDescription
uuid
Type: NSString
Identifier for which memberships should be set. Default: configured PubNub client uuid
channels
Type: NSArray
List of channels for which metadata associated with each of them in context of UUID should be set. Each entry is dictionary with channel and optional custom fields. custom should be dictionary with simple objects: NSString and NSNumber.
includeFields
Type: PNMembershipFields
  • PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership set requests.
  • PNMembershipChannelField - include channel's metadata into response (not only name).
  • PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests.
includeCount
Type: BOOL
Whether total count of objects should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block
Type: PNManageMembershipsCompletionBlock
Set UUID's memberships request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

NSArray<NSDictionary *> *channels = @[
  @{ @"channel": @"channel1", @"custom": @{ @"role": @"moderator" } }
];

self.client.objects().setMemberships()
    .uuid(@"uuid")
    .channels(channels)
    .includeCount(YES)
    .limit(40)
    .includeFields(NMembershipCustomField | PNMembershipChannelField)
    .performWithCompletion(^(PNManageMembershipsStatus *status) {
        if (!status.isError) {
            /**
             * UUID's memberships successfully set.
             * Result object has following information:
show all 29 lines

Response​

Response objects which is returned by client when set memberships Object API is used:

@interface PNManageMembershipsData : PNServiceData

// List of existing memberships.
@property (nonatomic, readonly, strong) NSArray<PNMembership *> *memberships;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields'
show all 28 lines

Remove Channel Memberships​

Remove channel memberships for a UUID.

Method(s)​

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

- (void)removeMembershipsWithRequest:(PNRemoveMembershipsRequest *)request
                          completion:(nullable PNManageMembershipsCompletionBlock)block;
* required
ParameterDescription
request *
Remove UUID's memberships request with information which should be used to remove channels membership.
block
Type: PNManageMembershipsCompletionBlock
Remove UUID's memberships request completion block.

PNRemoveMembershipsRequest​

* required
ParameterDescription
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. Use asc or desc to specify sort direction.
includeFields
Type: PNMembershipFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNMembershipsTotalCountField - include how many memberships UUID has.
  • PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership add requests.
  • PNMembershipChannelField - include channel's metadata into response (not only name).
  • PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests.
Default value (PNMembershipsTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified.

Basic Usage​

NSArray<NSString *> *channels = @[@"channel1", @"channel2"];
PNRemoveMembershipsRequest *request = [PNRemoveMembershipsRequest requestWithUUID:@"uuid"
                                                                         channels:channels];
// Add this request option, if returned membership models should have value which has been set to
// 'custom' and 'channel' properties.
request.includeFields = PNMembershipCustomField | PNMembershipChannelField | PNMembershipsTotalCountField;
request.limit = 40;

[self.client removeMembershipsWithRequest:request
                               completion:^(PNManageMembershipsStatus *status) {

    if (!status.isError) {
        /**
         * UUID's memberships successfully removed.
         * Result object has following information:
show all 29 lines

Response​

Response objects which is returned by client when remove memberships Object API is used:

@interface PNManageMembershipsData : PNServiceData

// List of existing memberships.
@property (nonatomic, readonly, strong) NSArray<PNMembership *> *memberships;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields'
show all 28 lines

Remove Channel Memberships (Builder Pattern)​

Method(s)​

objects()
    .removeMemberships()
    .uuid(NSString *)
    .channels(NSArray<NSString *> *)
    .includeFields(PNMemberFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(nullable PNManageMembershipsCompletionBlock);
* required
ParameterDescription
uuid
Type: NSString
Identifier for which memberships should be removed. Default: configured PubNub client uuid
channels
Type: NSArray
List of channels from which UUID should be removed as member.
includeFields
Type: PNMembershipFields
  • PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership set requests.
  • PNMembershipChannelField - include channel's metadata into response (not only name).
  • PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests.
includeCount
Type: BOOL
Whether total count of members should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block
Type: PNManageMembershipsCompletionBlock
Remove UUID's memberships request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().removeMemberships()
    .uuid(@"uuid")
    .channels(@[@"channel1", @"channel2"])
    .includeCount(YES)
    .limit(40)
    .includeFields(PNMembershipCustomField | PNMembershipChannelField)
    .performWithCompletion(^(PNManageMembershipsStatus *status) {
        if (!status.isError) {
            /**
             * UUID's memberships successfully removed.
             * Result object has following information:
             *   status.data.memberships - List of UUID's existing memberships.
             *   status.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
             *   status.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
             *   status.data.totalCount - Total number of UUID's memberships.
show all 25 lines

Response​

Response objects which is returned by client when remove memberships Object API is used:

@interface PNManageMembershipsData : PNServiceData

// List of existing memberships.
@property (nonatomic, readonly, strong) NSArray<PNMembership *> *memberships;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields'
show all 28 lines

Manage Channel Memberships​

The method Set and Remove channel memberships for a user.

Method(s)​

To Manage Memberships you can use the following method(s) in the Cocoa SDK:

- (void)manageMembershipsWithRequest:(PNManageMembershipsRequest *)request
                          completion:(nullable PNManageMembershipsCompletionBlock)block;
* required
ParameterDescription
request *
Manage UUID's memberships request with information what modifications to UUID's memberships should be done (set / remove channels).
block
Type: PNManageMembershipsCompletionBlock
Manage UUID's memberships request completion block.

PNManageMembershipsRequest​

* required
ParameterDescription
setChannels
Type: NSArray<NSDictionary *>
List of channels within which UUID should be set as member. Each entry is dictionary with channel and optional custom fields. custom should be dictionary with simple objects: NSString and NSNumber.
removeChannels
Type: NSArray<NSString *>
List of channels from which UUID should be removed as member.
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
includeFields
Type: PNMembershipFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNMembershipsTotalCountField - include how many memberships UUID has.
  • PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership add requests.
  • PNMembershipChannelField - include channel's metadata into response (not only name).
  • PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests.
Default value (PNMembershipsTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified.

Basic Usage​

PNManageMembershipsRequest *request = [PNManageMembershipsRequest requestWithUUID:@"uuid"];
request.setChannels = @[
    @{ @"channel": @"channel1", @"custom": @{ @"role": @"moderator" } }
];
request.removeChannels = @[@"channel3", @"channel4"];
// Add this request option, if returned membership models should have value which has been set to
// 'custom' and 'channel' properties.
request.includeFields = PNMembershipCustomField | PNMembershipChannelField | PNMembershipsTotalCountField;
request.limit = 40;

[self.client manageMembershipsWithRequest:request
                               completion:^(PNManageMembershipsStatus *status) {

    if (!status.isError) {
        /**
show all 31 lines

Response​

Response objects which is returned by client when manage memberships Object API is used:

@interface PNManageMembershipsData : PNServiceData

// List of existing memberships.
@property (nonatomic, readonly, strong) NSArray<PNMembership *> *memberships;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields'
show all 28 lines

Manage Channel Memberships (Builder Pattern)​

Method(s)​

objects()
    .manageMemberships()
    .uuid(NSString *)
    .set(NSArray<NSDictionary *> *)
    .remove(NSArray<NSString *> *)
    .includeFields(PNMemberFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(nullable PNManageMembershipsCompletionBlock);
* required
ParameterDescription
uuid
Type: NSString
Identifier for which memberships should be set. Default: configured PubNub client uuid
set
Type: NSArray
List of channels for which metadata associated with each of them in context of UUID should be set. Each entry is dictionary with channel and optional custom fields. custom should be dictionary with simple objects: NSString and NSNumber.
remove
Type: NSArray
List of channels from which UUID should be removed as member.
includeFields
Type: PNMembershipFields
  • PNMembershipCustomField - include field with additional information from metadata which has been associated with UUID during membership set requests.
  • PNMembershipChannelField - include channel's metadata into response (not only name).
  • PNMembershipChannelCustomField - include channel's additional information which has been used during channel metadata set requests.
includeCount
Type: BOOL
Whether total count of objects should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block
Type: PNManageMembershipsCompletionBlock
Manage UUID's memberships request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

NSArray<NSDictionary *> *setChannels = @[
    @{ @"channel": @"channel1", @"custom": @{ @"role": @"moderator" } }
];
NSArray<NSString *> *removeChannels = @[@"channel3", @"channel4"];

self.client.objects().manageMemberships()
    .uuid(@"uuid")
    .set(setChannels)
    .remove(removeChannels)
    .includeCount(YES)
    .limit(40)
    .includeFields(PNMembershipCustomField | PNMembershipChannelField)
    .performWithCompletion(^(PNManageMembershipsStatus *status) {
        if (!status.isError) {
            /**
show all 31 lines

Response​

Response objects which is returned by client when manage memberships Object API is used:

@interface PNManageMembershipsData : PNServiceData

// List of existing memberships.
@property (nonatomic, readonly, strong) NSArray<PNMembership *> *memberships;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNMembershipsTotalCountField not added to 'includeFields'
show all 28 lines

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 Cocoa SDK:

- (void)channelMembersWithRequest:(PNFetchChannelMembersRequest *)request
                       completion:(PNFetchChannelMembersCompletionBlock)block;
* required
ParameterDescription
request *
Fetch channel's members request with all information which should be used to fetch existing channel's members.
block *
Type: PNFetchChannelMembersCompletionBlock
Fetch channel's members request completion block.

PNFetchChannelMembersRequest​

* required
ParameterDescription
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. Use asc or desc to specify sort direction.
includeFields
Type: PNChannelMemberFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNChannelMembersTotalCountField - include how many members channel has.
  • PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests.
  • PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier).
  • PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests.
Default value (PNChannelMembersTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of members to return in response. Will be set to 100 (which is also maximum value) if not specified.

Basic Usage​

PNFetchChannelMembersRequest *request = [PNFetchChannelMembersRequest requestWithChannel:@"channel"];
request.start = @"<next from previous request>";
// Add this request option, if returned member models should have value which has been set to
// 'custom' and 'uuid' properties.
request.includeFields = PNChannelMemberCustomField | PNChannelMemberUUIDField | PNChannelMembersTotalCountField;
request.limit = 40;

[self.client channelMembersWithRequest:request
                            completion:^(PNFetchChannelMembersResult *result, PNErrorStatus *status) {

    if (!status.isError) {
        /**
         * Channel's members successfully fetched.
         * Result object has following information:
         *   result.data.members - List of channel's members.
show all 28 lines

Response​

Response objects which is returned by client when fetch members Object API is used:

@interface PNFetchChannelMembersData : PNServiceData

// List of fetched members.
@property (nonatomic, readonly, strong) NSArray<PNChannelMember *> *members;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of members created for current subscribe key.
 *
 * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields'
show all 28 lines

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

Get Channel Members (Builder Pattern)​

Method(s)​

objects()
    .channelMembers(NSString *)
    .includeFields(PNChannelMemberFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(PNFetchChannelMembersCompletionBlock);
* required
ParameterDescription
channel *
Type: NSString
Name of channel from which members should be fetched.
includeFields
Type: PNChannelMemberFields
  • PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests.
  • PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier).
  • PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests.
includeCount
Type: BOOL
Whether total count of objects should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block *
Type: PNFetchChannelMembersCompletionBlock
Fetch channel's members request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().channelMembers(@"channel")
    .includeCount(YES)
    .limit(40)
    .includeFields(PNChannelMemberCustomField | PNChannelMemberUUIDField)
    .performWithCompletion(^(PNFetchChannelMembersResult *result, PNErrorStatus *status) {
        if (!status.isError) {
            /**
             * Channel's members successfully fetched.
             * Result object has following information:
             *   result.data.members - List of channel's members.
             *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
             *   result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
             *   result.data.totalCount - Total number of channel's members.
             */
        } else {
show all 23 lines

Response​

Response objects which is returned by client when fetch members Object API is used:

@interface PNFetchChannelMembersData : PNServiceData

// List of fetched members.
@property (nonatomic, readonly, strong) NSArray<PNChannelMember *> *members;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of members created for current subscribe key.
 *
 * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields'
show all 28 lines

Error response which is used in case of App Context API call failure:

@interface PNErrorData : PNServiceData

// Stringified error information.
@property (nonatomic, readonly, strong) NSString *information;

@end

@interface PNErrorStatus : PNStatus

// Whether status object represent error or not.
@property (nonatomic, readonly, assign, getter = isError) BOOL error;

// Additional information related to error status object.
@property (nonatomic, readonly, strong) PNErrorData *errorData;

show all 16 lines

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 Cocoa SDK:

- (void)setChannelMembersWithRequest:(PNSetChannelMembersRequest *)request
                          completion:(nullable PNManageChannelMembersCompletionBlock)block;
* required
ParameterDescription
request *
Set channel's members list request with information which should be used to set UUID member.
block
Type: PNManageChannelMembersCompletionBlock
Set channel's members list request completion block.

PNSetMembersRequest​

* required
ParameterDescription
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. Use asc or desc to specify sort direction.
includeFields
Type: PNChannelMemberFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNChannelMembersTotalCountField - include how many members channel has.
  • PNChannelMemberCustomField - field with additional information from metadata which has been associated with UUID during channel member set requests.
  • PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier).
  • PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests.
Default value (PNChannelMembersTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified.
API limits

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

Basic Usage​

NSArray>NSDictionary *> *uuids = @[
  @{ @"uuid": @"uuid2", @"custom": @{ @"role": @"moderator" } }
];

PNSetChannelMembersRequest *request = [PNSetChannelMembersRequest requestWithChannel:@"channel" uuids:uuids];
// Add this request option, if returned member models should have value which has been set to
// 'custom' and 'uuid' properties.
request.includeFields = PNChannelMemberCustomField | PNChannelMemberUUIDField | PNChannelMembersTotalCountField;
request.limit = 40;

[self.client setChannelMembersWithRequest:request completion:^(PNManageChannelMembersStatus *status) {
    if (!status.isError) {
        /**
         * Channel's members successfully set.
         * Result object has following information:
show all 29 lines

Response​

Response objects which is returned by client when set members Object API is used:

@interface PNManageChannelMembersData : PNServiceData

// List of existing members.
@property (nonatomic, readonly, strong) NSArray<PNChannelMember *> *members;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields'
show all 28 lines

Set Channel Members (Builder Pattern)​

Method(s)​

objects()
    .setChannelMembers(NSString *)
    .uuids(NSArray<NSDictionary *> *)
    .includeFields(PNChannelMemberFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(nullable PNManageChannelMembersCompletionBlock);
API limits

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

* required
ParameterDescription
channel *
Type: NSString
Name of channel from which members should be set.
uuids
Type: NSArray
List of UUIDs for which metadata associated with each of them in context of channel should be set. Each entry is dictionary with UUID and optional custom fields. custom should be dictionary with simple objects: NSString and NSNumber.
includeFields
Type: PNChannelMemberFields
  • PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member set requests.
  • PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier).
  • PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests.
includeCount
Type: BOOL
Whether total count of objects should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. Only objects whose properties satisfy the given expression are returned. For more details on the supported grammar, check this
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block
Type: PNManageChannelMembersCompletionBlock
Set channel's members list request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

NSArray<NSDictionary *> *uuids = @[
  @{ @"uuid": @"uuid2", @"custom": @{ @"role": @"moderator" } }
];

self.client.objects().setChannelMembers(@"channel")
    .uuids(uuids)
    .includeCount(YES)
    .limit(40)
    .includeFields(PNChannelMemberCustomField | PNChannelMemberUserField)
    .performWithCompletion(^(PNManageChannelMembersStatus *status) {
        if (!status.isError) {
            /**
             * Channel's members successfully set.
             * Result object has following information:
             *   result.data.members - List of existing channel's members.
show all 28 lines

Response​

Response objects which is returned by client when set members Object API is used:

@interface PNManageChannelMembersData : PNServiceData

// List of existing members.
@property (nonatomic, readonly, strong) NSArray<PNChannelMember *> *members;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields'
show all 28 lines

Remove Channel Members​

Remove members from a Channel.

Method(s)​

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

- (void)removeChannelMembersWithRequest:(PNRemoveChannelMembersRequest *)request
                             completion:(nullable PNManageChannelMembersCompletionBlock)
* required
ParameterDescription
request *
Remove channel's members request with information which should be used to remove UUID members.
block
Type: PNManageChannelMembersCompletionBlock
Remove channel's members request completion block.

PNRemoveChannelMembersRequest​

* required
ParameterDescription
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. Use asc or desc to specify sort direction.
includeFields
Type: PNChannelMemberFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNChannelMembersTotalCountField - include how many members channel has.
  • PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests.
  • PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier).
  • PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests.
Default value (PNChannelMembersTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified.

Basic Usage​

NSArray<NSString *> *uuids = @[@"uuid3", @"uuid4"];
PNRemoveChannelMembersRequest *request = [PNRemoveChannelMembersRequest requestWithChannel:@"channel"
                                                                                     uuids:uuids];
// Add this request option, if returned member models should have value which has been set to
// 'custom' and 'uuid' properties.
request.includeFields = PNChannelMemberCustomField | PNChannelMemberUUIDField | PNChannelMembersTotalCountField;
request.limit = 40;

[self.client removeChannelMembersWithRequest:request completion:^(PNManageChannelMembersStatus *status) {
    if (!status.isError) {
        /**
         * Channel's members successfully removed.
         * Result object has following information:
         *   result.data.members - List of channel's existing members.
         *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
show all 27 lines

Response​

Response objects which is returned by client when remove members Object API is used:

@interface PNManageChannelMembersData : PNServiceData

// List of existing members.
@property (nonatomic, readonly, strong) NSArray<PNChannelMember *> *members;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields'
show all 28 lines

Remove Channel Members (Builder Pattern)​

Method(s)​

objects()
    .removeChannelMembers(NSString *)
    .uuids(NSArray<NSString *> *)
    .includeFields(PNChannelMemberFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(nullable PNManageChannelMembersCompletionBlock);
* required
ParameterDescription
channel *
Type: NSString
Name of channel from which members should be removed.
uuids
Type: NSArray
List of UUIDs which should be removed from channel's list.
includeFields
Type: PNChannelMemberFields
  • PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests.
  • PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier).
  • PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests.
includeCount
Type: BOOL
Whether total count of members should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block
Type: PNManageChannelMembersCompletionBlock
Remove channel's members request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

self.client.objects().removeChannelMembers(@"channel")
    .uuids(@[@"uuid3", @"uuid4"])
    .includeCount(YES)
    .limit(40)
    .includeFields(PNChannelMemberCustomField | PNChannelMemberUserField)
    .performWithCompletion(^(PNManageChannelMembersStatus *status) {
        if (!status.isError) {
            /**
             * Channel's members successfully removed.
             * Result object has following information:
             *   result.data.members - List of channel's existing members.
             *   result.data.next - Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
             *   result.data.prev - Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
             *   result.data.totalCount - Total number of channel's members.
             */
show all 24 lines

Response​

Response objects which is returned by client when remove members Object API is used:

@interface PNManageChannelMembersData : PNServiceData

// List of existing members.
@property (nonatomic, readonly, strong) NSArray<PNChannelMember *> *members;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields'
show all 28 lines

Manage Channel Members​

The method Set and Remove channel memberships for a user.

Method(s)​

To Manage Channel Members you can use the following method(s) in the Cocoa SDK:

- (void)manageChannelMembersWithRequest:(PNManageChannelMembersRequest *)request
                             completion:(nullable PNManageChannelMembersCompletionBlock)block;
* required
ParameterDescription
request *
Manage channel's members list request with information what modifications to channel's members list should be done (set / remove UUID).
block
Type: PNManageChannelMembersCompletionBlock
Manage channel's members list request completion block.

PNManageChannelMembersRequest​

* required
ParameterDescription
setMembers
Type: NSArray<NSDictionary *>
List of UUIDs which should be added to channel's members list. Each entry is dictionary with uuid and optional custom fields. custom should be dictionary with simple objects: NSString and NSNumber.
removeMembers
Type: NSArray<NSString *>
BList of UUIDs which should be removed from channel's list.
sort
Type: NSArray<NSString *>
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
includeFields
Type: PNChannelMemberFields
Bitfield set to fields which should be returned with response. Supported fields:
  • PNChannelMembersTotalCountField - include how many members channel has.
  • PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests.
  • PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier).
  • PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests.
Default value (PNChannelMembersTotalCountField) can be reset by setting 0.
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
limit
Type: NSUInteger
Number of objects to return in response. Will be set to 100 (which is also maximum value) if not specified.

Basic Usage​

PNManageChannelMembersRequest *request = [PNManageChannelMembersRequest requestWithChannel:@"channel"];
request.setMembers = @[
    @{ @"uuid": @"uuid2", @"custom": @{ @"role": @"moderator" } }
];
request.removeMembers = @[@"uuid3", @"uuid4"];
// Add this request option, if returned member models should have value which has been set to
// 'custom' and 'uuid' properties.
request.includeFields = PNChannelMemberCustomField | PNChannelMemberUUIDField | PNChannelMembersTotalCountField;
request.limit = 40;

[self.client manageChannelMembersWithRequest:request completion:^(PNManageChannelMembersStatus *status) {
    if (!status.isError) {
        /**
         * Channel's members successfully changed.
         * Result object has following information:
show all 29 lines

Response​

Response objects which is returned by client when manage members Object API is used:

@interface PNManageChannelMembersData : PNServiceData

// List of existing members.
@property (nonatomic, readonly, strong) NSArray<PNChannelMember *> *members;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields'
show all 28 lines

Manage Channel Members (Builder Pattern)​

Method(s)​

objects()
    .manageChannelMembers(NSString *)
    .set(NSArray<NSDictionary *> *)
    .remove(NSArray<NSString *> *)
    .includeFields(PNChannelMemberFields)
    .includeCount(BOOL)
    .filter(NSString *)
    .sort(NSArray<NSString *> *)
    .limit(NSUInteger)
    .start(NSString *)
    .end(NSString *)
    .performWithCompletion(nullable PNManageChannelMembersCompletionBlock);
* required
ParameterDescription
channel *
Type: NSString
Name of channel from which members should be managed.
set
Type: NSArray
List of UUIDs which should be added to channel's members list. Each entry is dictionary with UUID and optional custom fields. custom should be dictionary with simple objects: NSString and NSNumber.
remove
Type: NSArray
List of UUIDs which should be removed from channel's list.
includeFields
Type: PNChannelMemberFields
  • PNChannelMemberCustomField - include field with additional information from metadata which has been associated with UUID during channel member add requests.
  • PNChannelMemberUUIDField - include UUID's metadata into response (not only identifier).
  • PNChannelMemberUUIDCustomField - include UUID's additional information which has been used during UUID metadata set requests.
includeCount
Type: BOOL
Whether total count of objects should be included in response or not. Default: YES
filter
Type: NSString
Expression to filter out results basing on specified criteria. For more details on the supported grammar, check App Context Filtering Language Definition.
sort
Type: NSArray
List of criteria (name of field) which should be used for sorting in ascending order. To change sorting order, append :asc (ascending used by default) or :desc (descending) to field name.
limit
Type: NSUInteger
Maximum number of objects per fetched page. Default: 100 (which is also maximum value)
start
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
end
Type: NSString
Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data. Ignored if the start parameter is supplied.
block
Type: PNManageChannelMembersCompletionBlock
Set channel's members list request completion block.
Optional arguments

This method uses the builder pattern, you can remove the arguments which are optional.

Basic Usage​

NSArray<NSDictionary *> *setMembers = @[
    @{ @"uuid": @"uuid2", @"custom": @{ @"role": @"moderator" } }
];
NSArray<NSDictionary *> *removeMembers = @[@"uuid3", @"uuid4"];

self.client.objects().manageChannelMembers(@"channel")
    .set(setMembers)
    .remove(removeMembers)
    .includeCount(YES)
    .limit(40)
    .includeFields(PNChannelMemberCustomField | PNChannelMemberUUIDField)
    .performWithCompletion(^(PNManageChannelMembersStatus *status) {
        if (!status.isError) {
            /**
             * Channel's members successfully changed.
show all 30 lines

Response​

Response objects which is returned by client when manage members Object API is used:

@interface PNManageChannelMembersData : PNServiceData

// List of existing members.
@property (nonatomic, readonly, strong) NSArray<PNChannelMember *> *members;

// Random string returned from the server, indicating a specific position in a data set. Used for forward pagination, it fetches the next page, allowing you to continue from where you left off.
@property (nonatomic, nullable, readonly, strong) NSString *next;

// Random string returned from the server, indicating a specific position in a data set. Used for backward pagination, it fetches the previous page, enabling access to earlier data.
@property (nonatomic, nullable, readonly, strong) NSString *prev;

/**
 * Total number of existing objects.
 *
 * Value will be 0 in case if PNChannelMembersTotalCountField not added to 'includeFields'
show all 28 lines
Last updated on
On this page