Skip to content
Documentation
Getting Started

Installation

To install the Presence library, we need to run the command "pnpm add @yomo/presence" inside our React project directory. Alternatively, we can use npm or yarn to install the library. Once installed, we can import the library into our project and start using its powerful features.

pnpm add @yomo/presence

Quick Start

Create Presence instance:

After installing the library, we need to import Presence into our project and create a Presence instance. To do this, we need to provide some parameters such as the server address, publicKey, client ID, and debug. PublicKey can be obtained from allegrocloud.io by creating an account and a new project. Once the project is created, the publicKey can be found in the dashboard.

import Presence from '@yomo/presence';
 
// create an instance.
const presencePromise = new Presence('https://lo.yomo.dev:8443/v1', {
  publicKey: <PUBLIC_KEY>,
  id: 'user-client-id',
  debug: true,
});
💡

lo.yomo.dev always points to 127.0.0.1, developers can use it for local development. Check out here for more.

Join a Channel:

Next, we need to call the joinChannel method of the Presence instance, passing in the channel ID and initial state, to join the desired channel. This is the key step that establishes real-time online status in the project. With this step completed, developewert building interactive multiplayer experiences in our project.

(async (){
  const presence = await presencePromise;
  const c = presence.joinChannel('channel-id', myInitialState);
})()

Subscribe peers online/offline events

To further customize our implementation of real-time online status, we can use the subscribePeers method of the Channel instance to subscribe to changes in the online/offline status of members in the channel. This allows us in real-time to update the online status of members and adjust the application accordingly.

c.subscribePeers((peers) => {
    peers.forEach((peer) => {
      console.log(peer + " is online")
    }
});

Broadcast

Another useful feature of the Presence library is the ability to broadcast messages to specific members or all members in the channel. This is achieved using the broadcastToPeers API, and it allows we to create more targeted and personalized interactions in our applications.

const cb = () => {
  const state = document.hidden ? 'away' : 'online';
  c.broadcast('hidden-state', { state });
};
document.addEventListener('visibilitychange', cb)

Subscribe

Moreover, the Presence library provides a rich set of APIs for us to interact with, such as getPeers, setPeers, and broadcastToPeers. These APIs allow development of the online status of members in the channel and broadcast messages to specific members or all members in the channel.

channel.subscribe(
  'hidden-state-change',
  ({ payload, peerState }) => {
    console.log(`${peerState.id} change visibility to: ${payload}`)
  }
)

At this point, we have established a real-time online state in the react project. With the help of the Presence library, we can easily add real-time online status to our React projects and create engaging multiplayer experiences for users. By customizing our implementation and utilizing the various APIs provided by the library, develop unique and dynamic online environments for us to explore and interact with. With this tutorial as a starting point, we can bear the full potential of the Presence library and building exciting new applications.

IntroductionPresence