Manage open channel metadata

Open channel metadata lets you store custom attributes in a channel. Common scenarios include voice chat seat management, game state tracking, and similar features.

tip

• Metadata is destroyed when the channel is destroyed.
• Each channel supports up to 100 key-value pairs.
• Keep KV operations under 100 per second per channel.

Set metadata entries

Dart

final channel = OpenChannel('<open-channel-id>');
await channel.setMetadata(
  {'seat_1': 'user-001', 'game_status': 'playing'},
  deleteWhenLeft: false,
  overwrite: true,
  handler: (error) {
    if (error == null) {
      print('KV entries set');
    }
  },
);

setMetadata parameters

Parameter	Type	Default	Description
entries	Map	Required	Key-value pairs to set
deleteWhenLeft	bool	false	Auto-delete when the user leaves or disconnects
overwrite	bool	true	Overwrite if the key exists

Get metadata entries

Dart

// Get a specific key
await channel.getMetadata(
  key: 'seat_1',
  handler: (entries, error) {
    print('Value: $entries');
  },
);

// Get all entries
await channel.getMetadata(
  handler: (entries, error) {
    print('All KV: $entries');
  },
);

Remove metadata entries

Dart

await channel.deleteMetadata(
  ['seat_1'],
  force: false,
  handler: (error) {
    if (error == null) {
      print('KV entry removed');
    }
  },
);

Listen for metadata changes

Register an OpenChannelHandler to receive metadata change events:

Dart

NCEngine.addOpenChannelHandler('kv-handler', OpenChannelHandler(
  onMetadataChanged: (event) {
    print(
      'KV changed: ${event.operationType}, channel: ${event.channelId}, entries: ${event.entries}',
    );
  },
));

Remove the handler when it is no longer needed:

Dart

NCEngine.removeOpenChannelHandler('kv-handler');