subscribe( )

Subscribes to a channel or channel resource.

Description

The subscribe() function subscribes to receive messages published on the specified channel or channel resource and sets a function that handles incoming messages when they are published to the channel.

When you subscribe to a channel you do not receive messages published to a resource on that same channel. To receive those messages, you must explicitly subscribe to the specific resource.

The specified message handler is run each time a message is published on the given channel or channel resource. Use it to define what happens when messages are received.

You can subscribe to a channel or channel resource more than once to add multiple message handlers. Each subscription returns a unique subscription ID which can be used later to unsubscribe from the specific subscription with that ID, without affecting the other subscriptions on the same channel or channel resource.

Syntax

function subscribe(channel: Channel, handler: MessageHandler): Promise<string>
handler: function MessageHandler(message: Message, channel: Channel): void

subscribe Parameters

NAME

TYPE

DESCRIPTION

channel

Channel

The channel, and optionally the resource, to subscribe to.

handler

MessageHandler

The name of the function or the function expression to run when something is published to the subscription's channel or channel resource.

Returns

Fulfilled - An ID representing the subscription, used for unsubscribing. Rejected - Error that caused the rejection, such as insufficient permissions.

Return Type:

Promise<string>

MessageHandler Parameters

NAME

TYPE

DESCRIPTION

message

Message

The message that was published.

channel

Channel

The channel the message was published on.

Returns

This function does not return anything.

Return Type:

void

Was this helpful?

Subscribe to a channel

Copy Code

1import wixRealtimeFrontend from 'wix-realtime-frontend';
2
3// ...
4
5const channel = {"name": "someChannel"};
6let subscriptionId;
7
8wixRealtimeFrontend.subscribe(channel, (message, channel) => {
9  let payload = message.payload;
10  let channelName = channel.name;
11  if(message.publisher) {
12    let publisherId = message.publisher.id;
13  }
14})
15.then((id) => {
16  subscriptionId = id;
17});

Subscribe to a resource on a channel

Copy Code

1import wixRealtimeFrontend from 'wix-realtime-frontend';
2
3// ...
4
5const channel = {
6  "name": "someChannel",
7  "resourceId": "someId"
8};
9let subscriptionId;
10
11wixRealtimeFrontend.subscribe(channel, (message, channel) => {
12  let payload = message.payload;
13  let channelName = channel.name;
14  let resourceId = channel.resourceId;
15  if(message.publisher) {
16    let publisherId = message.publisher.id;
17  }
18})
19.then((id) => {
20  subscriptionId = id;
21});

Send and receive messages across a single channel

This example demonstrates how to send and receive messages across a single channel. You can test out the code in our example template.

Copy Code

1import { subscribe } from 'wix-realtime-frontend';
2import { publishMessage } from 'backend/realtime';
3
4const channel = { name: 'hello-world' };
5
6$w.onReady(function () {
7  subscribe(channel, (message) => {
8    $w('#receivedMessages').value += (message.payload + '\n');
9  });
10    
11  $w('#publishMessageButton').onClick(async () => {
12    if($w('#message').value) {
13      $w('#publishMessageButton').disable();
14      $w('#message').disable();
15
16      await publishMessage(channel, $w('#message').value);
17            
18      $w('#message').value = undefined;
19      $w('#message').enable();
20      $w('#publishMessageButton').enable();
21    }
22  });
23});
24

Display a popup notification when a message is received

This example demonstrates how to display a popup notification when a message is received on a channel that a visitor is subscribed to. The notification displays the contents of the message that was received.

The example assumes the page contains a box that contains a text element and a button. The box is set to be hidden when the page loads.

When a message is received, the text element's text value is set to the contents of the message and the box is shown to display the message to the site visitor. When the button is clicked, the box is hidden again.

Copy Code

1import wixRealtimeFrontend from 'wix-realtime-frontend';
2
3// ...
4
5$w.onReady(function() {
6  const channel = {"name": "updates"};
7
8  wixRealtimeFrontend.subscribe( channel, (message, channel) => {
9    $w("#updateMessage").text = message.payload;
10    $w("#updateBox").show();
11  });
12
13  $w("#hideUpdateButton").onClick( () => {
14    $w("#updateBox").hide();
15  });
16});
17
18