Channels
3.2.0Channels are globally accessed named contexts that allow users to dynamically group apps, instructing them to work over the same shared data object. The Channels API enables you to:
- discover Channels - get the names and contexts of all Channels;
- navigate through Channels - get the current Channel, join and leave Channels, subscribe for the event which fires when the current Channel has changed;
- publish and subscribe - publish data to other apps on the same Channel and subscribe for Channel updates to react to data published by other apps;
The Channels API is accessible through the io.channels
object.
APIobject
Description
Channels API.
Methods
allmethod
Signature
() => Promise<string[]>
Description
Returns a list of all channel names.
getmethod
Signature
(name: string) => Promise<ChannelContext>
Description
Returns the context of a given channel.
Parameters
Name | Type | Required | Description |
---|---|---|---|
name | string | The name of the channel whose context to return. |
getMymethod
getWindowsOnChannelmethod
Signature
(channel: string) => Promise<WebWindow[]>
Description
Retrieves all windows on a specified Channel.
Parameters
Name | Type | Required | Description |
---|---|---|---|
channel | string | The name of the Channel for which windows should be returned. |
getWindowsWithChannelsmethod
Signature
(filter?: WindowWithChannelFilter) => Promise<WindowOnChannelInfo[]>
Description
Retrieves all windows that can use Channels together with their current Channel.
Parameters
Name | Type | Required | Description |
---|---|---|---|
filter | WindowWithChannelFilter | Filter describing which windows to retrieve. If no filter is supplied, will return all windows that can use Channels. |
joinmethod
Signature
(name: string, windowId?: string) => Promise<void>
Description
Joins a new channel by name. Leaves the current channel.
Parameters
Name | Type | Required | Description |
---|---|---|---|
name | string | The name of the channel to join. |
|
windowId | string | ID of a window which to join to a Channel. If not provided, will join the current window to the specified Channel. |
leavemethod
Signature
() => Promise<void>
Description
Leaves the current channel.
listmethod
mymethod
Signature
() => string
Description
Returns the name of the current channel.
onChangedmethod
Signature
(callback: (channel: string) => void) => UnsubscribeFunction
Description
Subscribes for the event which fires when a channel is changed.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (channel: string) => void | Callback function to handle channel changes. |
publishmethod
Signature
(data: any, name?: string) => Promise<void>
Description
Updates the context of the current or a given channel.
Parameters
Name | Type | Required | Description |
---|---|---|---|
data | any | Data object with which to update the channel context. |
|
name | string | The name of the channel to be updated. If not provided will update the current channel. |
subscribemethod
Signature
(callback: (data: any, context: ChannelContext, updaterId: string) => void) => UnsubscribeFunction
Description
Tracks the data in the current channel. Persisted after a channel change. The callback isn't called when you publish the data.
Parameters
Name | Type | Required | Description |
---|---|---|---|
callback | (data: any, context: ChannelContext, updaterId: string) => void | Callback function to handle the received data. |
subscribeFormethod
Signature
(name: string, callback: (data: any, context: ChannelContext, updaterId: string) => void) => Promise<UnsubscribeFunction>
Description
Tracks the data in a given channel.
Parameters
Name | Type | Required | Description |
---|---|---|---|
name | string | The channel to track. |
|
callback | (data: any, context: ChannelContext, updaterId: string) => void | Callback function to handle the received data. |
ChannelContextobject
Description
Channel context object.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
data | any | Channel data. |
||
meta | any | Channel meta data (display name, color, image, etc.) |
||
name | string | Unique name of the context. |
WindowOnChannelInfoobject
Description
Describes a window that can use Channels.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
application | string | Name of the app to which the window instance belongs. |
||
channel | string | Name of the Channel to which the window is joined. |
||
window | WebWindow | Describes the window instance. |
WindowWithChannelFilterobject
Description
Filter for retrieving windows that can use Channels.
Properties
Property | Type | Default | Required | Description |
---|---|---|---|---|
application | string | Name of the app whose window instances to retrieve. |
||
channels | string[] | List of Channel names. Only the windows that are joined to one of the specified Channels will be retrieved. |
||
windowIds | string[] | IDs of windows to retrieve. |