Manage open channel metadata

Use the open channel metadata APIs to store custom key-value attributes. Common use cases include tracking seat status in live audio and storing user roles or game state in card games.

Prerequisites

Enable open channel metadata in the Console before using these APIs. For related webhook options, see Open channel service configuration.

Nexconn supports server callbacks for metadata changes (set, delete, clear). See Metadata Sync (KV).

Limitations

tip

• Metadata is destroyed when the open channel is destroyed.
• Maximum 100 key-value pairs per channel.
• Recommended operation frequency: 100 operations per second per channel (a single batch of 100 KVs counts as 100 operations).

Listen for metadata changes

Use NCEngine.addOpenChannelHandler() with an OpenChannelHandler to listen for metadata changes.

Callback	Description
onMetadataSynced(event: OpenChannelMetadataSyncedEvent)	Triggered when metadata sync completes after joining. Use event.channelId.
onMetadataChanged(event: OpenChannelMetadataChangedEvent)	Triggered on metadata updates or deletes. Use event.info to access the list of OpenChannelMetadataChangeInfo items, each with channelId, key, value (null when deleted), and isDelete. Returns all KVs on first sync, then only changed entries.

Add a listener

Kotlin

kotlin

NCEngine.addOpenChannelHandler("KV_LISTENER", object : OpenChannelHandler {
    override fun onMetadataSynced(event: OpenChannelMetadataSyncedEvent) {
        // Sync complete for channel: event.channelId
    }

    override fun onMetadataChanged(event: OpenChannelMetadataChangedEvent) {
        for (item in event.info) {
            if (item.isDelete) {
                // Key deleted: item.key
            } else {
                // Key updated: item.key = item.value
            }
        }
    }
})

Java

Java

NCEngine.addOpenChannelHandler("KV_LISTENER", new OpenChannelHandler() {
    @Override
    public void onMetadataSynced(@NonNull OpenChannelMetadataSyncedEvent event) {
        // Sync complete for channel: event.getChannelId()
    }

    @Override
    public void onMetadataChanged(@NonNull OpenChannelMetadataChangedEvent event) {
        for (OpenChannelMetadataChangeInfo item : event.getInfo()) {
            if (item.isDelete()) {
                // Key deleted: item.getKey()
            } else {
                // Key updated: item.getKey() = item.getValue()
            }
        }
    }
});

Remove the listener

Kotlin

kotlin

NCEngine.removeOpenChannelHandler("KV_LISTENER")

Java

Java

NCEngine.removeOpenChannelHandler("KV_LISTENER");

Get metadata

Call openChannel.getMetadata() to get metadata by key. Returns all entries when key is empty.

Parameter	Type	Description
key	String	Key name. Alphanumeric and + = - _, max 128 characters. Pass empty string to get all.
handler	OperationHandler<Map<String, String>>	Callback

Kotlin

kotlin

val openChannel = OpenChannel("open_123")
openChannel.getMetadata("name") { entries, error ->
    if (error == null && entries != null) {
        // entries is a Map<String, String>
    }
}

Java

Java

OpenChannel openChannel = new OpenChannel("open_123");
openChannel.getMetadata("name", (entries, error) -> {
    if (error == null && entries != null) {
        // entries is a Map<String, String>
    }
});

Set multiple entries

Call openChannel.setMetadata() to set multiple metadata entries at once.

Parameter	Type	Description
metadata	Map<String, String>	Key-value pairs to set. Max 10 per call.
deleteWhenLeft	Boolean	Whether to auto-delete on user exit. Default false.
overwrite	Boolean	Whether to force-overwrite others' entries. Default false.

Kotlin

kotlin

val openChannel = OpenChannel("open_123")
val params = OpenChannelSetMetadataParams(
    metadata = mapOf("name" to "Alice", "age" to "18"),
    deleteWhenLeft = true,
    overwrite = false
)

openChannel.setMetadata(params) { error ->
    if (error == null) {
        // All entries set successfully
    } else {
        // Failed
    }
}

Java

Java

OpenChannel openChannel = new OpenChannel("open_123");
Map<String, String> entries = new HashMap<>();
entries.put("name", "Alice");
entries.put("age", "18");

OpenChannelSetMetadataParams params = new OpenChannelSetMetadataParams(entries, true, false);

openChannel.setMetadata(params, error -> {
    if (error == null) {
        // All entries set successfully
    } else {
        // Failed
    }
});

Delete multiple entries

Call openChannel.deleteMetadata() to delete multiple entries at once. Max 10 entries per call.

Parameter	Type	Description
keys	List<String>	Keys to delete. Max 10 per call.
isForce	Boolean	Whether to force-delete entries set by other users. Default false.

Kotlin

kotlin

val openChannel = OpenChannel("open_123")

openChannel.deleteMetadata(OpenChannelDeleteMetadataParams(keys = listOf("key1", "key2"), isForce = false)) { error ->
    if (error == null) {
        // All deleted
    } else {
        // Failed
    }
}

Java

Java

OpenChannel openChannel = new OpenChannel("open_123");

openChannel.deleteMetadata(new OpenChannelDeleteMetadataParams(Arrays.asList("key1", "key2"), false), error -> {
    if (error == null) {
        // All deleted
    } else {
        // Failed
    }
});