Skip to main content

Publish and Subscribe

The ART ADK provides a robust publish-subscribe system for real-time communication. This guide covers the core messaging patterns and channel management features.

Subscribe to channel​

Channel subscription is the foundation of real-time communication in ART. When you subscribe to a channel, you establish a persistent connection that enables bidirectional messaging with automatic connection management, fallback protocols, and message buffering.

The subscription process in ART is asynchronous and involves several behind-the-scenes operations to ensure reliable connectivity:

// Basic subscription
const subscription = await adk.subscribe('my-channel');

// Listen to channel events
subscription.listen('message', handleChatMessage);
subscription.bind('alert', handleAlert);

Channel namespaces​

Channel namespaces provide a powerful way to organize and isolate communication streams within your application. Think of namespaces as folders that help you categorize channels logically, enabling better organization and access control.

Namespaces use the colon (:) separator to create hierarchical channel names:

// Basic format is channelName:namespace
const subscription = await adk.subscribe('chat:general');

Push message into channel​

Once subscribed to a channel, you can send messages to other subscribers using the push() method. Messages are delivered based on the channel type and targeting options you specify.

Send to all users​

Broadcast messages to all subscribers of a channel:

// Define the message payload
const payload = { content: "Hello from ART ADK!" };

subscription
  .push("message", payload)
  .then((response) => {
    console.log("Message acknowledged by ART:", response);
    // The 'response' indicates successful queuing or delivery acknowledgment
  })
  .catch((error) => {
    console.error("Failed to push message:", error);
  });
  • First parameter is the event name that subscribers will listen for
  • Second parameter is the message data (any JSON-serializable object).

Send to list of users or to particular user​

Target specific users for private messaging or selective broadcasting:

// Define the message payload
const payload = { content: "Hello from ART ADK!" };

// Optionally define specific target users within the channel
const targetUsers = ["username1", "username2"];

// Push a "message" event with the payload and targeting options
subscription
  .push("message", payload, {
    to: targetUsers, // Target specific recipients within the channel
  })
  .then((response) => {
    console.log("Message acknowledged by ART:", response);
    // The 'response' indicates successful queuing or delivery acknowledgment
  })
  .catch((error) => {
    console.error("Failed to push message:", error);
  });
  • Here, third parameter is the options object containing the to array with target usernames.
important

Targeted channels require exactly one recipient in the to array.

Listen to events​

After subscribing to a channel, you need to set up event listeners to handle incoming messages. ART provides flexible options for listening to messages based on your application needs.

Listen to all events​

Receive all messages regardless of event type using the listen() method:

subscription.listen((data) => {
  console.log("Received message:", data);
  // Your logic to handle events
})

This is useful in logging all channel activity, generic message processing, debugging and monitoring.

Listen to particular event​

The bind() method lets you listen for a specific event within the subscribed channel. Unlike listen(), which captures everything, bind() filters messages and triggers the callback only when the defined event occurs.

subscription.bind("event", (data) => {
  console.log("Received event data:", data);
  // Your logic to handle the event
});

Unsubscribe from channel​

Clean up subscriptions to free resources and stop receiving messages when they're no longer needed. Proper unsubscription ensures your application remains performant and doesn't waste resources on unused connections.

// Unsubscribe from channel
await subscription.unsubscribe();

console.log('Successfully unsubscribed from channel');