Skip to main content

Manage open channel metadata

Use this page when you need to store lightweight key-value state on an open channel, such as seat assignment, game state, or room attributes. The iOS Chat SDK exposes this through OpenChannel instance methods.

Prerequisites​

  • Enable Open channel custom attributes in the Console under Chat > Chat settings > Open Channels.
  • Join or enter the target open channel before relying on metadata sync callbacks.

Limits and behavior​

  • Metadata is destroyed when the open channel is destroyed.
  • Each open channel can store up to 100 key-value pairs.
  • Set and delete APIs support up to 10 keys per call.
  • Recommended operation frequency is up to 100 metadata operations per second per channel.

Listen for metadata changes​

Register an OpenChannelHandler to receive the initial metadata sync and later metadata changes. See Open channel events for registration details.

swift
import NexconnChatSDK

final class OpenChannelMetadataObserver: NSObject, OpenChannelHandler {
    func onMetadataSynced(_ event: OpenChannelMetadataSyncedEvent) {
        print("Metadata synced for channel: \(event.channelId)")
    }

    func onMetadataChanged(_ event: OpenChannelMetadataChangedEvent) {
        for change in event.changeInfo {
            switch change.operationType {
            case .update:
                print("Key updated: \(change.key) = \(change.value ?? "") in channel \(change.channelId)")
            case .remove:
                print("Key deleted: \(change.key) in channel \(change.channelId)")
            }
        }
    }
}

Metadata callback objects​

Callback / objectKey fieldsDescription
onMetadataSynced(_:)event.channelIdFired after the SDK finishes the initial metadata sync for an entered open channel.
onMetadataChanged(_:)event.changeInfoFired when metadata is updated or removed in the current channel.
OpenChannelMetadataChangeInfochannelId, key, value, operationTypeOne metadata change item. value is meaningful for updates, and operationType is .update or .remove.

Get a metadata value​

Call getMetadata(key:completion:) on an OpenChannel instance to retrieve the value for one metadata key.

swift
import NexconnChatSDK

guard let channel = OpenChannel(channelId: "channelId") else {
    return
}

channel.getMetadata(key: "seatStatus") { metadata, error in
    guard let metadata, error == nil else {
        print("Failed to get metadata: \(error?.localizedDescription ?? "unknown error")")
        return
    }

    print("seatStatus = \(metadata["seatStatus"] ?? "")")
}

getMetadata(key:completion:)​

ParameterTypeDescription
keyString / NSString *The metadata key to query. Use the exact key name stored on the channel.
completion([String: String]?, NCError?) -> VoidReturns a dictionary containing the matched key-value pair on success, or NCError on failure.

Set metadata​

Use OpenChannelSetMetadataParams to write one or more metadata entries. Set overwrite to true if you want to overwrite values written by other users. Set deleteWhenLeft to true if the metadata should be removed automatically when the current user exits the channel.

swift
import NexconnChatSDK

guard let channel = OpenChannel(channelId: "channelId") else {
    return
}

let params = OpenChannelSetMetadataParams(
    metadata: ["seat1": "occupied"],
    overwrite: false,
    deleteWhenLeft: true
)

channel.setMetadata(params: params) { failureKeys, error in
    if let error {
        print("Failed keys: \(failureKeys ?? []), error: \(error.localizedDescription)")
        return
    }

    print("Metadata set successfully.")
}

OpenChannelSetMetadataParams​

PropertyTypeDescription
metadata[String: String] / NSDictionary<NSString *, NSString *> *Key-value pairs to set. Up to 10 keys per call.
overwriteBool / BOOLtrue to overwrite values created by other users. false preserves existing values from other users.
deleteWhenLeftBool / BOOLtrue to remove these keys automatically when the current user leaves or disconnects from the open channel.

setMetadata(params:completion:)​

Callback valueDescription
failureKeysKeys that failed in the current operation. nil on full success.
errornil on success, or NCError when the metadata write fails.

Key names can contain alphanumeric characters plus +, =, -, and _, with a maximum length of 128 characters. Each value can be up to 4096 characters.

Delete metadata​

Use OpenChannelDeleteMetadataParams to remove one or more keys from the open channel.

swift
import NexconnChatSDK

guard let channel = OpenChannel(channelId: "channelId") else {
    return
}

let params = OpenChannelDeleteMetadataParams(keys: ["seat1", "seat2"], isForce: false)

channel.deleteMetadata(params: params) { failureKeys, error in
    if let error {
        print("Failed keys: \(failureKeys ?? []), error: \(error.localizedDescription)")
        return
    }

    print("Keys deleted.")
}

OpenChannelDeleteMetadataParams​

PropertyTypeDescription
keys[String] / NSArray<NSString *> *Metadata keys to delete. Up to 10 keys per call.
isForceBool / BOOLtrue to delete keys created by other users. false only removes keys the current user can delete normally.

deleteMetadata(params:completion:)​

Callback valueDescription
failureKeysKeys that failed to delete in the current operation. nil on full success.
errornil on success, or NCError when the delete request fails.
Last updated on