Data Sharing

The Channels API is accessible through the io.channels object.

See the JavaScript Channels example on GitHub.

The Channels API is disabled by default. To enable it, set the channels property of the configuration object to true when initializing the io.Connect library:

const config = { channels: true };

const io = await IODesktop(config);

For details on how to enable the Channel Selector for your apps, see the Channels > Overview > Channel Selector section.

To get the name of the Channel to which your app is currently joined, use the my() method:

const myChannel = io.channels.my();

To get a list of all Channel names, use the all() method:

const channelNames = await io.channels.all();

You can add or remove Channels at runtime. New dynamically added Channels won't be persisted after restart of io.Connect Desktop, unless they are recreated. A Channel that has been defined via configuration and is dynamically removed will be restored on restart of io.Connect Desktop.

To add a Channel dynamically, use the add() method and pass a ChannelContext object as an argument:

const channelContext = {
    name: "Black",
    meta: { color: "black" },
    data: { io: 42 }
};

// Adding a new Channel.
const newChannelContext = await io.channels.add(channelContext);

To remove a Channel dynamically, use the remove() method and pass the name of the Channel to remove:

// Removing a Channel.
await io.channels.remove("Black");

To make your app join a Channel programmatically, use the join() method and specify the name of the Channel to join:

await io.channels.join("Red");

To leave the Channel your app is currently on, use the leave() method:

await io.channels.leave();

To get the context of a Channel, use the get() method which accepts a Channel name as a required argument:

const data = await io.channels.get("Green");

To get a list of the contexts of all Channels, use the list() method:

const channelContexts = await io.channels.list();

To track the data in the current Channel, use the subscribe() method:

const handler = (data) => {
    // The callback will be invoked each time the data is updated.
    console.log(data);
};

// Subscribe for updates from the Channel your app is currently on.
io.channels.subscribe(handler);

The callback receives the data from the Channel and information about the current Channel.

The callback will be invoked in three cases:

• the data property of the Channel you are currently on is updated;
• the user has switched the Channel and you are receiving a snapshot of the new Channel data;
• your app isn't joined to a Channel anymore (e.g., the user has deselected the current Channel). In this case, both data and channelInfo will be undefined;

To subscribe for updates from a specific Channel, use the subscribeFor() method:

const channelName = "Green";
const handler = (data) => {
    // The callback will be invoked each time the data is updated.
    console.log(data);
};

await io.channels.subscribeFor(channelName, handler);

The subscribeFor() method accepts a Channel name as a first argument and a callback to handle Channel data updates.

Use the unsubscribe function returned by subscribe() and subscribeFor() to stop tracking updates of the Channel data:

const unsubscribe = await io.channels.subscribeFor(channelName, handler);

unsubscribe();

The handlers passed to the subscribe() and subscribeFor() methods also accept the Channel context and the updating Interop Instance peer ID as second and third arguments. The ChannelContext object contains the name of the Channel and the Channel meta data. The updating Interop instance peer ID can be used to identify the app updating the Channel:

const handler = (data, channelContext, updaterID) => {
    // Check the current Interop instance peer ID against the updating instance ID.
    const isUpdatedByMe = io.interop.instance.peerId === updaterID;

    if(!isUpdatedByMe) {
        // Another app has published in the Channel.
        console.log(`App "${updaterID}" has published "${JSON.stringify(data)}" in Channel "${channelContext.name}".`);
    };
};

io.channels.subscribe(handler);

To update the context of the Channel, use publish(). The publish() method accepts two arguments - data to publish (required) and an optional Channel ID specifying which Channel context to update. If you don't specify a Channel ID, the current Channel will be updated.

Updating the current Channel:

const data = { io: 42 };

await io.channels.publish(data);

Updating a specific Channel:

const data = { io: 42 };
const channelName = "Green";

await io.channels.publish(data, channelName);

Channels may contain multiple data structures. When updating the Channel context, only the specified fields will be updated, leaving all other fields of the context unchanged.

The publish() method will throw an exception if you aren't on a Channel and try to publish data.

Available since io.Connect Desktop 9.4

You can use the setPath() and setPaths() methods to update specific Channel context properties using a dot-separated string path (e.g., "prop1.prop2") to point to the location of the property within the Channel context. If the property (or the path) doesn't exist, it will be created. These methods are useful for updating or creating one or more nested properties within the Channel context.

To update or create a single property, use the setPath() method. It accepts a PathValue object as a first required argument, containing a path to the property to update and a value for it. As a second optional argument, you can pass the name of a Channel whose context to update. If a Channel name isn't specified, the context of the current Channel will be updated:

const update = {
    path: "text.color",
    value: "grey"
};

// The current Channel will be updated.
await io.channels.setPath(update);

// Assuming the Channel context data has this shape:
// { backgroundColor: "red" }, it will be updated as follows:
// { backgroundColor: "red", text: { color: "grey" } }

To update or create multiple properties, use the setPaths() method. It accepts a list of PathValue objects as a first required argument, each object containing a path to the property to update and a value for it:

const channelName = "Red";
const updates = [
    { path: "table.cells", value: { width: 50, height: 30 } },
    { path: "text.color", value: "white" }
];

await io.channels.setPaths(updates, channelName);

// Assuming the Channel context data has this shape:
// { backgroundColor: "red", text: { color: "grey" } }, it will be updated as follows:
//
// {
//     backgroundColor: "red",
//     text: {
//         color: "white"
//     },
//     table: {
//         cells: {
//             width: 50,
//             height: 30
//         }
//     }
// }

Available since io.Connect Desktop 9.3

To apply restrictions to windows for publishing or subscribing to Channels, use the restrict() method and provide a ChannelRestrictions object as a required argument. The following example demonstrates how to prevent the current window from publishing to the "Red" Channel:

// Restricting the current window from publishing to a Channel.
const restrictions = {
    name: "Red",
    read: true,
    write: false
};

await io.channels.restrict(restrictions);

To apply restrictions to another window for publishing or subscribing to a Channel, provide the window ID in the ChannelRestrictions object:

// Restricting a specific window from publishing to a Channel.
const restrictions = {
    name: "Red",
    read: true,
    write: false,
    // ID of the window you want to restrict.
    windowId: win.id
};

await io.channels.restrict(restrictions);

To apply restrictions to windows for publishing or subscribing to all Channels, use the restrictAll() method and provide a RestrictionsConfig object as a required argument. The following example demonstrates how to prevent the current window from publishing to all Channels:

// Restricting the current window from publishing to all Channels.
const restrictions = {
    read: true,
    write: false
};

await io.channels.restrictAll(restrictions);

To apply restrictions to another window for publishing or subscribing to all Channels, provide the window ID in the RestrictionsConfig object:

// Restricting a specific window from publishing to all Channels.
const restrictions = {
    read: true,
    write: false,
    // ID of the window you want to restrict.
    windowId: win.id
};

await io.channels.restrictAll(restrictions);

To retrieve the applied Channel restrictions for the current window, use the getRestrictions() method. If you want to get the applied Channel restrictions for a specific window, pass a window ID as an optional argument. The method resolves with a Restrictions object with a channels property holding a list of ChannelRestrictions objects:

// Retrieving the Channel restrictions for the current window.
const { channels } = await io.channels.getRestrictions();

channels.forEach(console.log);

The Channels API provides methods for reacting to various Channel events. Use the returned unsubscribe function to stop receiving notifications about the respective event.

Channel Changed

To get notified when the current Channel of your window is changed, use the onChanged() method:

const handler = (newChannel) => {
    if (newChannel) {
        // Handle the case where you have switched to another Channel.
        console.log(newChannel);
    } else {
        // Handle the case where your app isn't joined to any Channel
        // (e.g., the user has deselected the current Channel).
        console.log("No Channel selected.")
    };
};

io.channels.onChanged(handler);

Channel Restrictions Changed

Available since io.Connect Desktop 9.5

To get notified when the Channel restrictions for any window have changed, use the onChannelRestrictionsChanged() method and provide a handler for the event. The handler will receive as arguments a Restrictions object describing the current set of Channel restrictions and the ID of the window for which the Channel restrictions have changed:

const handler = (restrictions, windowID) => {
    console.log(`Channel restrictions changed for window with ID: "${windowID}"`);
    console.log(restrictions.channels);
};

io.channels.onChannelRestrictionsChanged(handler);

For a complete list of the available Channels API methods and properties, see the Channels API Reference Documentation.