Introduction

Using the Realtime API you can create channels and channel resources where messages can be published. Site visitors who subscribe to a channel receive the messages published to that channel. When a message is received you can handle the message any way you choose, such as displaying the contents of the message or changing the state of page elements depending on the contents of the message. You can also manage the permissions of who can read from specific channels.

The wix-realtime-frontend module is used in conjunction with the wix-realtime-backend module.

Get hands-on experience with the Realtime API on our Hello Realtime example page.

Typical uses of the Realtime API include implementing a messaging system or as an alternative to using a polling mechanism.

The Realtime API uses the following terminology:

Channel: A specific channel on which messages are published. Each channel has a unique name. Site visitors can subscribe to a channel to receive the messages that are published on it. When site visitors subscribe to a channel, they do not receive messages published to a resource on that same channel.
Channel resource: A subchannel on which messages are published. Subchannels can share a name with a channel and other subchannels, but they have a unique resource ID. When site visitors subscribe to a channel resource, they do not receive messages published to that same channel without a specified resource. Channel resources inherit their parent channel's permissions, unless specified otherwise.
Message: A message published on a channel or channel resource. A message can be of any type, such as a string, number, or object. Channel subscribers receive the messages published on the channel.
Publish: Sending a message over a channel or channel resource.
Subscribe: A site visitor subscribes to receive the messages published on a channel or channel resource.

For a tutorial on using the Realtime API, see Sending Messages with the Realtime API.

To use the Realtime API, import wixRealtimeFrontend from the wix-realtime-frontend module:

Copy


import wixRealtimeFrontend from "wix-realtime-frontend";

Did this help?

onConnected( )

Adds an event handler that runs when a connection or reconnection occurs.

A connection occurs on the first subscription to a channel or channel resource or when an existing connection is lost and then restored.

Method Declaration

Copy

function onConnected(handler: function): void;

Method Parameters

handlerfunctionRequired

handler(): void The name of the function or the function expression to run when a connection occurs.

Example shown:Add a connection handler

JavaScript


import wixRealtimeFrontend from "wix-realtime-frontend";

// ...

wixRealtimeFrontend.onConnected(() => {
  // handle connection
  $w("#disconnectedMessage").hide();
});

Did this help?

onDisconnected( )

Adds an event handler that runs when a disconnection occurs.

A disconnection can occur, for example, if there is a network issue.

Method Declaration

Copy

function onDisconnected(handler: function): void;

Method Parameters

handlerfunctionRequired

handler(): void The name of the function or the function expression to run when a disconnection occurs.

Example shown:Add a connection handler

JavaScript


import wixRealtimeFrontend from "wix-realtime-frontend";

// ...

wixRealtimeFrontend.onDisconnected(() => {
  // handle disconnection
  $w("#disconnectedMessage").show();
});

Did this help?

onError( )

Adds an event handler that runs when an error occurs.

An error can occur when attempting to resubscribe after a disconnection. Errors that occur during the initial subscription process cause the Promise returned by the subscribe() function to reject and do not trigger onError() event handlers.

Method Declaration

Copy

function onError(handler: function): void;

Method Parameters

handlerfunctionRequired

handler(error: Error): void The name of the function or the function expression to run when an error occurs.

Example shown:Add an error handler

JavaScript


import wixRealtimeFrontend from "wix-realtime-frontend";

// ...

wixRealtimeFrontend.onError((error) => {
  let code = error.errorCode;
  let message = error.message;
  if (error.channel) {
    let channelName = error.channel.name;
    let resourceId = error.channel.resourceId;
  }
});

Did this help?