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(
  OpenChannelSetMetadataParams(
    metadata: {'seat_1': 'user-001', 'game_status': 'playing'},
    deleteWhenLeft: false,
    overwrite: true,
  ),
  (error) {
    if (error?.isSuccess == true) {
      print('KV entries set');
    }
  },
);

OpenChannelSetMetadataParams

Parameter	Type	Default	Description
metadata	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(
  OpenChannelDeleteMetadataParams(
    keys: ['seat_1'],
    isForce: false,
  ),
  (error) {
    if (error?.isSuccess == true) {
      print('KV entry removed');
    }
  },
);

OpenChannelDeleteMetadataParams

Parameter	Type	Default	Description
keys	List<String>	Required	Metadata keys to remove.
isForce	bool	false	Whether to force deletion when entries were created by another user.

Listen for metadata changes

Register an OpenChannelHandler to receive metadata change events:

Dart

NCEngine.addOpenChannelHandler('kv-handler', OpenChannelHandler(
  onMetadataChanged: (event) {
    for (final info in event.changeInfo) {
      print(
        'KV changed: ${info.operationType}, channel: ${info.channelId}, key: ${info.key}, value: ${info.value}',
      );
    }
  },
));

Remove the handler when it is no longer needed:

Dart

NCEngine.removeOpenChannelHandler('kv-handler');