Forem: SuperViz

Realtime meets AI: How we used gaming to showcase our new library, now open source!

Vitor Norton — Mon, 11 Nov 2024 14:09:31 +0000

We're excited to announce that we're open sourcing the code we used to create an interactive experience that synchronized data for over 3,000 users at major tech events, demonstrating the power and scalability of our newly released Realtime library.

Multiplayer Infinite Craft

One key part of this was making the Super, which was based on Infinite Craft, multiplayer. The game consists of combining different elements to create new ones, fostering creativity.

Users would start with the essential elements: "Fire", "Water", "Earth", "Wind", "Coffee", "JavaScript", and "Developer". After combining "Fire" and "JavaScript", an AI would analyze the combination and create "Firebase".

Because these events would gather a huge number of people (sometimes 3.5k people), we couldn't synchronize every new element among everyone. This was mainly because the gameplay would not be fun; instead, it would be confusing and stressful. By the end of these events, that would add up to 16k elements. Can you imagine how to display 16k non-structured elements on a mobile screen?

We took a different approach by making it a bit of a race. Everyone would play with a single instance, but in case they found a first discovery (meaning no one before had tried this combination), new points were added to the user, and everyone at the event would get a push notification. With more points, there was a greater chance to win a big prize at the end of the day.

Adding Real-time

We had build with a Next.js project, using our @superviz/realtime package, which offers a WebSocket infrastructure, that is based on a Publisher/Subscriber (PubSub) design pattern. This allowed for efficient event-driven communication between different instances of the application.

For this, we had created two different channels, the default and the game. The default channel was the communication of the whole experience, it would tell if an activation has awarded points to the user, and would sync across other parts of the system (mostly syncing user dada). We had a dedicated channel for the game, that would notify every one that was listening to the new.element event.

When someone combined two elements, it would send a request to our API. The API would analyze if the user was valid and if the element combination already existed in our database. If neither of these conditions were met, it would send a prompt to OpenAI to create the element. Before returning the result, we would update the database and publish several events.

await Promise.all([
  defaultChannel.publish("activation.game.update", {
    userId: user.id,
    points: quantity,
  }),

  gameChannel.publish("new.element", {
    element,
    user,
    points: quantity,
  }),
]);

On the frontend of the game, we would listen to the new.event and add a push notification using toast. Like so:

const handleGameUpdate = (message) => {
  const userFromMessage = message.data.user;
  const element = message.data.element;

  if (userFromMessage.email ===
    JSON.parse(localStorage.getItem(USERDATA_KEY) as string))
    return;

  toast(`${userFromMessage?.name} just discovered ${element.name.toUpperCase()} and has more chance of winnin!`);
};

useEffect(() => {
  gameChannel.subscribe("new.element", handleGameUpdate);
}, []);

But the application magic happened on the dashboard and with the other event being dispatched.

A playful dashboard

On our stand, we had a giant TV to display the dashboard. It was designed to be both informative and mesmerizing , displaying real-time updates of player activities and discoveries. It was a visual representation of every single participant activity. Not only kept participants informed of their scores but also fueled friendly competition and excitement throughout the event.

The dashboard was inspired by the popular multiplayer game Agar.io. Much like how players in Agar.io grow by consuming smaller cells, our dashboard represented each participant as a dynamic entity that expanded as they gained points.

The design concept revolved around creating a visually engaging and intuitive representation of real-time data. Each participant was depicted as a circular entity, with concentric rings expanding outward to indicate their score and level of engagement. This organic, cell-like visualization not only made the data easy to interpret at a glance but also added an element of gamification to the event experience. We also would add transparency to those users that was offline to showcase our recent released presence feature.

Behind the scene

To make this happen, this page would listen to every single event, and that was plenty! This is the list of the listening events the page was subscribed:

defaultChannel.subscribe("activation.start", handleActivationStart);
defaultChannel.subscribe("activation.complete", handleActivationComplete);
defaultChannel.subscribe("activation.game.update", handleGameUpdate);
gameChannel.subscribe("new.element", handleGameUpdate);

defaultChannel.presence.subscribe("presence.leave", (message) =>
  handleParticipantStatusChange(message.id, false)
);
defaultChannel.presence.subscribe("presence.joined-room", (message) =>
  handleParticipantStatusChange(message.id, true)
);
defaultChannel.presence.subscribe("presence.update", (message) =>
  handleParticipantUpdate(message)
);

Let's break down those events our dashboard listens to and explore how each contributes to creating a dynamic, real-time experience:

Activation events: The dashboard listens for activation.start and activation.complete events, which add a progress ring when an activation starts and add a complete ring when it finishes. The rings were added based on the order that the person would participate in the activations, providing a real-time visual story of their journey through the event.

The activation.game.update event was responsable to showcase real-time progress in the game. It updates the player's score, which is visually represented by expanding the ring around their entity on the dashboard.

Game updates: It subscribes to new.element events from the game channel, which would display a toast notification with the new element created. This feature gathered people around the screen to see what others were creating in real-time, creating a sense of community and shared excitement.

We had seen the creation of beautiful elements, like “Real-time communication”, “Web sockets”, “Collaboration environment”, “Remote work” and funny ones like “Intergalactic coffee”!

Presence events: The code subscribes to various presence-related events, which play a crucial role in maintaining an up-to-date representation of participant activity. These events include:

presence.leave: Triggered when a participant goes offline, causing their representation to become semi-transparent on the dashboard.
presence.joined-room: presence.joined-room: Fired when a participant comes online. For new participants, a new cell would enter the screen. For returning participants, it would restore the brightness of their existing cell. This effect allows participants and organizers to easily spot who is currently active in the event.

This real-time updating creates a dynamic, engaging experience for all participants, showcasing the power and versatility of the Realtime library in handling multiple simultaneous events and updates.

Hackathon AI meets Realtime

We recently hosted an Super Hackathon 2.0, with the challenge: AI meets Realtime challenge, pushing the boundaries of innovation by combining artificial intelligence with real-time communication technologies.

Participants were given the freedom to create anything they could imagine, much like our Super! (But we couldn’t participate of our own hackathon with this project 😢)

The hackathon saw an impressive projects that leveraged our Realtime library alongside various AI technologies. The creativity and innovation displayed by the participants were truly remarkable. If you're curious about the winning projects and want to explore how they combined AI with real-time capabilities, we invite you to read our detailed blog post about the hackathon winners. It's a great source of inspiration and showcases the potential of our Realtime library when paired with AI.

After many request, it’s open source

The overwhelming enthusiasm for our game didn't end with the events. Participants were eager to continue playing, explore without limitations, people were legitimately addicted to the gameplay. We heard your requests loud and clear!

Now that our new Realtime library is officially released, we're excited to announce that we're making the code for this project open source! This allows you to not only continue playing but also gain a better understanding of how everything works behind the scenes.

You can find the repository on our GitHub page. We encourage you to clone it, experiment with it, and maybe even contribute your own improvements or variations.

Happy coding and crafting!

How to build a collaborative drawing App

Pachi 🥑 — Thu, 17 Oct 2024 14:30:00 +0000

Hello Devs 👋🏼

This tutorial will guide you through creating a collaborative drawing application using SuperViz. This type of application allows multiple users to draw, annotate, and interact with a shared canvas in real-time. It's perfect for brainstorming sessions, collaborative design work, and interactive presentations.

We'll demonstrate how to set up a React application that leverages SuperViz to synchronize drawing activities between participants. By the end of this tutorial, you'll have a fully functional collaborative drawing app that you can extend and customize to suit your needs.

Let's get started!

Prerequisite

To follow this tutorial, you will need a SuperViz account and a developer token. If you already have an account and a developer token, you can move on to the next step.

Create an account

To create an account, go to https://dashboard.superviz.com/register and create an account using either Google or an email/password. It's important to note that when using an email/password, you will receive a confirmation link that you'll need to click to verify your account.

Retrieving a Developer Token

To use the SDK, you’ll need to provide a developer token, as this token is essential for associating SDK requests with your account. You can retrieve both development and production SuperViz tokens from the dashboard..

Copy and save the developer token, as you will need it in the next steps of this tutorial.

Step 1: Set Up Your React Application

In this tutorial, we will guide you through creating a collaborative drawing application using SuperViz. This type of application allows multiple users to draw, annotate, and interact with a shared canvas in real-time. It's perfect for brainstorming sessions, collaborative design work, and interactive presentations.

Let's get started!

1. Create a New React Project

First, create a new React application using Vite with TypeScript.


npm create vite@latest drawing-app -- --template react-ts
cd drawing-app

Vite is a modern build tool that provides a faster and more efficient development experience compared to Create React App. It also supports TypeScript out of the box.

2. Install Required Libraries

Next, install the necessary libraries for our project:


npm install @superviz/sdk @superviz/realtime konva react-konva uuid

@superviz/sdk: For integrating real-time collaboration features.
@superviz/realtime: SuperViz Real-Time library for integrating real-time.
konva & react-konva: Libraries for creating and managing a canvas-based drawing interface in React.
uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.


npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.


/** @type  {import('tailwindcss').Config} */
export  default  {
content:  [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme:  {
extend:  {},
},
plugins:  [],

}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)


@tailwind base;
@tailwind components;
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.


VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and manage the collaborative drawing board.

1. Implement the App Component

Open src/App.tsx and set up the main application component using SuperViz to manage the collaborative drawing experience.


import  { v4 as generateId }  from  "uuid";
import  { useCallback, useEffect, useRef, useState }  from  "react";
import  SuperVizRoom,  {
  LauncherFacade,
  MousePointers,
  Participant,
  ParticipantEvent,
  WhoIsOnline,
}  from  "@superviz/sdk";
import  {
  Realtime,
  type  Channel,
  type  RealtimeMessage,
}  from  "@superviz/realtime";
import  {  Board  }  from  "./components/board";
import  {  BoardState  }  from  "./types/global.types";

Explanation:

Imports: Import necessary components from React, SuperViz, UUID, and the Konva-based Board component for managing the drawing interface and real-time collaboration.

2. Define Constants

Define constants for the API key, room ID, and participant ID.


const apiKey =  import.meta.env.VITE_SUPERVIZ_API_KEY  as  string;
const  ROOM_ID  =  'drawing-app';
const  PLAYER_ID  =  generateId();

Explanation:

apiKey: Retrieves the SuperViz API key from environment variables.
ROOM_ID & PLAYER_ID: Defines the room ID for the SuperViz session and generates a unique player ID for each participant.

3. Create the App Component

Set up the main App component and initialize the drawing board and SuperViz.


export  default  function  App()  {
  const initialized =  useRef(false);
  const ready =  useRef(false);
  const  [fillColor, setFillColor]  =  useState("#000");
  const  [state, setState]  =  useState<BoardState>({
 rectangles:  [],
 circles:  [],
 arrows:  [],
 scribbles:  [],
  });

  const contentRef =  useRef<HTMLDivElement |  null>(null);
  const channel =  useRef<Channel |  null>(null);
  const superviz =  useRef<LauncherFacade |  null>(null);

Explanation:

useState & useRef: Manages the initialization state, drawing color, readiness of the board, and the SuperViz instance.
state: Holds the current state of the drawing board, including all shapes and scribbles.

4. Initialize SuperViz

Create a function to initialize SuperViz and set up real-time collaboration for the drawing board.


const initialize =  useCallback(async  ()  =>  {
  if  (initialized.current)  return;
  initialized.current  =  true;

 superviz.current  =  await  SuperVizRoom(apiKey,  {
  roomId:  ROOM_ID,
  participant:  {
  id:  PLAYER_ID,
  name:  "player-name",
  },
 group:  {
  id:  "drawing-app",
  name:  "drawing-app",
  },
  });

 const realtime =  new  Realtime(apiKey,  {
  participant:  {
  id:  PLAYER_ID,
  name,
  },
 });
const whoIsOnline =  new  WhoIsOnline();

superviz.current?.addComponent(whoIsOnline);

 channel.current  =  await realtime.connect("board-topic");
 channel.current.subscribe<BoardState>("update-state", handleRealtimeMessage);

 superviz.current?.subscribe(
  ParticipantEvent.LOCAL_UPDATED,
  (participant:  Participant)  =>  {
   setFillColor(participant.slot?.color ||  "#000");

  if  (!ready.current  && participant.slot?.index !==  0)  {
   ready.current  =  true;

   const mousePointers =  new  MousePointers("board-container");
   superviz.current?.addComponent(mousePointers);
   }
  }
 );
},  [handleRealtimeMessage, initialized, ready]);

Explanation:

initialize: Sets up SuperViz, integrates real-time updates for the drawing board, and adds mouse pointers to track participant actions.
Realtime & WhoIsOnline: Handles real-time communication and displays online participants.

5. Handle Real-Time Messages

Create functions to handle incoming real-time messages and update the board state.


const handleRealtimeMessage = useCallback((message: BoardStateMessage) => { 
 if (message.participantId === PLAYER_ID) return; 
 setState(message.data); 
}, []); 

const updateState = useCallback((state: BoardState) => { 
 setState(state); 
 if (channel.current) { 
  channel.current.publish('update-state', state); 
 } 
}, []);

Explanation:

handleRealtimeMessage: Updates the board state when receiving real-time messages from other participants.
updateState: Publishes updates to the board state to synchronize changes across all participants.

Step 3: Render the Drawing Board

Finally, return the JSX structure for rendering the collaborative drawing board.


return ( 
 <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'> 
  <header className='w-full p-5 bg-purple-400 flex items-center justify-between'> 
   <h2 className='text-white text-2xl font-bold'>SuperViz Drawing App</h2> 
  </header> 
  <main ref={contentRef} className='w-full h-full flex items-center justify-center' id='board-container'> 
   { 
    ready && ( 
     <Board 
      state={state} 
      setState={updateState} 
      width={contentRef.current?.clientWidth || 0} 
      height={contentRef.current?.clientHeight || 0} 
      fillColor={fillColor} ]
     /> 
    ) 
   } 
   {
    !ready && ( 
     <div className='w-full h-full flex items-center justify-center'> 
      Loading... 
     </div> 
    ) 
   } 
  </main> 
 </div> 
);

Explanation:

Drawing Board: Renders the collaborative drawing board, where users can interact with shapes and scribbles in real-time. The board is only shown when the app is fully ready.

Step 4: Understanding the Project Structure

Here's a quick overview of how the project structure supports a collaborative drawing application:

App.tsx
- Initializes SuperViz and sets up real-time collaboration for the drawing board.
- Manages the state and updates of the drawing board.
Board Component
- Handles the rendering and interaction logic for the drawing board, including creating shapes, scribbles, and allowing users to manipulate them.
- Updates the drawing state in real-time as participants interact with the board.
Real-Time Communication
- Manages real-time communication between participants using SuperViz, ensuring that the drawing board is synchronized across all users.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:


npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the drawing board and see updates in real-time as other participants join.

2. Test the Application

Collaborative Drawing: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that drawing actions are synchronized in real-time.
Collaborative Interaction: Test the responsiveness of the application by drawing shapes, scribbles, and moving objects, and observing how the board updates for all participants.

Summary

In this tutorial, we built a collaborative drawing application using SuperViz. We configured a React application to handle real-time updates of a drawing board, enabling multiple users to draw and interact seamlessly. This setup can be extended and customized to fit various scenarios where real-time collaboration is essential.

Feel free to explore the full code and further examples in the GitHub repository for more details.

Join us: SuperViz Hackathon 2.0: AI meets RealTime

Get ready to participate in our Super Hackathon 2.0 this October to showcase your innovative real-time AI communication solutions! Hosted by SuperViz and with $5,000 in prizes up for grabs, we challenge you to integrate AI with SuperViz's real-time platform, pushing the boundaries of interactive communication.

Ready to join? Visit the Super Hackathon 2.0 website to register and stay updated.

Learn how to add real-time synchronization to a React Flow application

Pachi 🥑 — Tue, 15 Oct 2024 14:30:00 +0000

Hello everyone 👋🏼

Today's tutorial will guide you through adding real-time synchronization to a React Flow application using SuperViz. Real-time synchronization is a key feature for collaborative applications, allowing multiple users to interact with shared content simultaneously and see each other's changes as they happen. With React Flow and SuperViz, you can build interactive flowcharts that update live, providing a seamless collaborative experience.

We'll demonstrate how to integrate contextual comments and real-time mouse pointers into a React Flow application, enabling users to collaborate on flowcharts with real-time updates. This setup allows multiple participants to add nodes, create connections, and drag elements within the flowchart, with changes instantly visible to all session users.

Let's get started!

Prerequisite

To follow this tutorial, you will need a SuperViz account and a developer token. If you already have an account and a developer token, you can move on to the next step.

Create an account

Retrieving a Developer Token

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate the React Flow and SuperViz SDK for real-time collaboration.

1. Create a New React Project

First, create a new React application using Create React App with TypeScript.


npx create-react-app realtime-react-flow --template typescript
cd realtime-react-flow

2. Install Required Libraries

Next, install the necessary libraries for our project:


npm install @superviz/react-sdk @superviz/realtime reactflow uuid

@superviz/react-sdk: SuperViz SDK for integrating real-time collaboration features.
@superviz/realtime: SuperViz Real-Time library for integrating real-time synchronization into your application.
reactflow: A library for building interactive flowcharts and diagrams.
uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.


npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.


/** @type  {import('tailwindcss').Config} */
export  default  {
content:  [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme:  {
extend:  {},
},
plugins:  [],
}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)


@tailwind base;
@tailwind components;
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.


VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and handle real-time synchronization in a React Flow application.

1. Implement the App Component

Open src/App.tsx and set up the main application component using the SuperVizRoomProvider to manage the collaborative environment.


import  { SuperVizRoomProvider }  from  "@superviz/react-sdk";
import  { v4 as generateId }  from  "uuid";
import Room from  "./Room";
import  { ReactFlowProvider }  from  "reactflow";

const developerKey =  import.meta.env.VITE_SUPERVIZ_API_KEY;
const participantId =  generateId();

export  default  function  App()  {
  return  (
   <SuperVizRoomProvider
    developerKey={developerKey}
    group={{
    id:  "react-flow-tutorial",
    name:  "react-flow-tutorial",
   }}
  participant={{
    id: participantId,
    name:  "Participant",
  }}
  roomId="react-flow-tutorial"
  >
   <ReactFlowProvider>
    <Room participantId={participantId}  />
   </ReactFlowProvider>
  </SuperVizRoomProvider>
 );}

Explanation:

SuperVizRoomProvider: This component wraps the application to enable real-time features and provides configuration for group and participant details.
developerKey: Retrieves the developer key from environment variables to authenticate with SuperViz.
ReactFlowProvider: Wraps the Room component to provide React Flow's context, which manages the state of the flowchart.
Room Component: Contains the logic for rendering the flowchart and handling real-time interactions.

Step 3: Create the Room Component

The Room component will be responsible for integrating React Flow with SuperViz, allowing users to collaborate on the flowchart in real-time.

Step-by-Step Breakdown of the Room Component

Let's break down the Room component step-by-step to understand how it enables real-time collaboration using React Flow and SuperViz.

1. Import Necessary Modules

First, import the required modules and components from both reactflow and @superviz/react-sdk.


import { useCallback, useEffect, MouseEvent, useRef } from "react"; 
import ReactFlow, { 
 useNodesState, 
 Controls, 
 Background, 
 ConnectionLineType, 
 addEdge, 
 useEdgesState, 
 ConnectionMode, 
 Connection, 
 useViewport, 
 Node, 
} from "reactflow"; 
import "reactflow/dist/style.css"; 
import { 
 Comments, 
 MousePointers, 
 useComments, 
 useHTMLPin, 
 useMouse, 
 WhoIsOnline, 
} from "@superviz/react-sdk"; 
import { Realtime, type Channel } from "@superviz/realtime/client";

Explanation:

ReactFlow Imports: Provide flowchart components and utilities to create interactive diagrams.
SuperViz SDK Imports: Includes tools for real-time collaboration, such as comments, mouse pointers, and synchronization.

2. Define Initial Nodes and Edges

Define the initial state of nodes and edges for the flowchart.


type Edge = { 
 type: ConnectionLineType; 
 animated: boolean; 
 source: string | null; 
 target: string | null; 
 sourceHandle: string | null; 
 targetHandle: string | null; 
}; 

const initialNodes = [ 
 { id: "1", position: { x: 381, y: 265 }, data: { label: "Start" } }, 
 { id: "2", position: { x: 556, y: 335 }, data: { label: "Action" } }, 
 { id: "3", position: { x: 701, y: 220 }, data: { label: "Process" } }, 
 { id: "4", position: { x: 823, y: 333 }, data: { label: "End" } }, 
]; 

const initialEdges = [ 
 { 
  id: "e1-2", 
  source: "1", 
  target: "2", 
  type: ConnectionLineType.SmoothStep, 
  animated: true, 
 }, 
 { 
  id: "e2-3", 
  source: "2", 
  target: "3", 
  type: ConnectionLineType.SmoothStep, 
  animated: true, 
 }, 
 { 
  id: "e3-4", 
  source: "3", 
  target: "4", 
  type: ConnectionLineType.SmoothStep, 
  animated: true, 
 }, 
];

Explanation:

Edge Type: Defines the structure of an edge in the flowchart.
initialNodes: An array of objects defining each node's position and label in the flowchart.
initialEdges: An array of objects defining connections between nodes, using a smooth step connection line with animation.

3. Define the Room Component

Create the Room component with properties to manage the participant ID.


type Props = { 
 participantId: string; 
}; 

export default function Room({ participantId }: Props) { 
 const initialized = useRef(false); 
 const channel = useRef<Channel>();

Explanation:

Props Type: Defines the expected properties for the Room component, including the participantId.
initialized Ref: A ref to track whether the component has initialized the Real-Time component and subscribed to real-time events, ensuring it only happens once.
Channel Ref: A ref to store the real-time channel for communication between participants.

4. Set Up Real-Time Hooks and Utilities

Initialize SuperViz hooks and utilities to manage comments, real-time updates, and mouse transformations.


// Managing comments 
const { openThreads, closeThreads } = useComments(); 

// Managing real-time updates 
const { isReady, subscribe, unsubscribe, publish } = useRealtime("default"); 

// Managing mouse pointers 
const { transform } = useMouse(); /

/ Pinning functionality for comments 
const { pin } = useHTMLPin({ 
 containerId: "react-flow-container", 
 dataAttributeName: "data-id", 
 dataAttributeValueFilters: [/.*null-(target|source)$/], 
});

Explanation:

useComments: Provides functions to open and close comment threads.
useRealtime: Offers real-time event handling methods like subscribe, unsubscribe, and publish.
useMouse: Allows transformations based on mouse movements.
useHTMLPin: Enables the pinning of comments to specific HTML elements within the application.

5. Initialize State for Nodes and Edges

Manage the state of nodes and edges using React Flow's hooks.


const  { x, y, zoom }  =  useViewport();
const  [nodes, setNodes, onNodesChange]  =  useNodesState(initialNodes);
const  [edges, setEdges, onEdgesChange]  =  useEdgesState(initialEdges);

Explanation:

useViewport: Provides the current viewport state, including the x and y translation and zoom level.
useNodesState: Manages the state of nodes with initial values and handles changes.
useEdgesState: Manages the state of edges with initial values and handles changes.

6. Handle Edge Connections

Define a callback function for handling new edge connections in the flowchart.


const onConnect = useCallback( 
 (connection: Connection) => { 
  const edge: Edge = { 
   ...connection, 
   type: ConnectionLineType.SmoothStep, 
   animated: true, 
  }; 

  setEdges((eds) => addEdge(edge, eds)); 

  channel.current!.publish("new-edge", { 
   edge, 
  }); 
 }, 
 [setEdges] 
);

Explanation:

onConnect: Handles the creation of new edges, updating the state and publishing the changes to all participants.
addEdge: Adds a new edge to the current state.

7. Handle Node Dragging

Create a callback for handling node dragging events and publish the changes.


const onNodeDrag =  useCallback(
  (_: MouseEvent, node: Node)  =>  {
   publish("node-drag",  { node });
  },
  [publish]
);

Explanation:

onNodeDrag: Publishes node position updates as they are dragged, allowing other participants to see the changes.

8. Handle Drag Over Events

Prevent the default behavior for drag-over events to enable custom dragging interactions.


const onDragOver =  useCallback(
  (event: React.DragEvent<HTMLButtonElement | HTMLDivElement>)  =>  {
    event.preventDefault();
    event.dataTransfer.dropEffect =  "move";
  },
  []
);

Explanation:

onDragOver: Sets the drag effect to "move" to provide visual feedback during drag operations.

9. Update Viewport on Mouse Movement

Adjust the viewport based on mouse movements to keep the flowchart aligned.


useEffect(()  =>  {
   transform({
    translate:  {
     x: x,
     y: y,
   },
   scale: zoom,
  });
},  [x, y, zoom, transform]);

Explanation:

useEffect: Transforms the viewport position and scale when the mouse moves, ensuring all participants have a synchronized view.

10. Set Data Attribute for SuperViz Pinning

Assign a data attribute to the React Flow container for SuperViz pinning.


useEffect(()  =>  {
  const element = document.querySelector(".react-flow__pane");

  if  (!element)  return;

  element.setAttribute("data-superviz-id",  "plane");
},  []);

Explanation:

data-superviz-id: Allows SuperViz to identify elements that can have pins attached, facilitating comment features.

11. Initialize Real-Time Component

Start Real-Time, connect to a channel and set up subscriptions to listen for real-time events and synchronize state changes.


const initializeRealtime = useCallback(async () => { 
 if (initialized.current) return; 
 initialized.current = true; 

 const realtime = new Realtime(developerKey, { 
  participant: { 
   id: participantId, 
   name: "Participant", 
  }, 
 }); 

 channel.current = await realtime.connect("react-flow-tutorial"); 

 const centerNodes = () => { 
  const centerButton = document.querySelector( 
   ".react-flow__controls-fitview" 
  ) as HTMLButtonElement; 
  centerButton?.click(); 
 }; 

 centerNodes(); 

 channel.current!.subscribe<{ edge: Edge }>( 
  "new-edge", 
  ({ data, participantId: senderId }) => { 
   if (senderId === participantId) return; 

   setEdges((eds) => addEdge(data.edge, eds)); 
  } 
 ); 

 channel.current!.subscribe<{ node: Node }>( 
  "node-drag", 
  ({ data, participantId: senderId }) => { 
   if (senderId === participantId) return; 

   setNodes((nds) => 
    nds.map((node) => 
     node.id === data.node.id ? { ...node, ...data.node } : node 
    ) 
   ); 
  } 
 ); 
}, [participantId, setEdges, setNodes]); 

useEffect(() => { 
 initializeRealtime(); 

 return () => { 
  channel.current?.disconnect(); 
 }; 
}, [initializeRealtime]);

Explanation:

initializeRealtime: Use the user API key and participant infos to set up a new Real-Time connection.Listens for specific events (new-edge, node-drag) and updates the local state based on incoming data.
disconnect: Clean up subscriptions when no longer needed.

12. Render the Room Component

Finally, render the Room component with React Flow and SuperViz features.


return ( 
 <div className="w-full h-full bg-gray-200 flex items-center justify-center flex-col"> 
  <header className="w-full p-5 bg-purple-400 flex items-center justify-between"> 
   <h1 className="text-white text-2xl font-bold">React Flow + SuperViz</h1> 
   <div id="comments" className="flex gap-2"></div> 
  </header> 
  <main className="flex-1 w-full h-full"> 
   <div id="react-flow-container" className="w-full h-full"> 
    <ReactFlow 
     nodes={nodes} 
     onNodeDrag={onNodeDrag} 
     edges={edges} 
     onConnect={onConnect} 
     onNodesChange={onNodesChange} 
     onEdgesChange={onEdgesChange} 
     onDragOver={onDragOver} 
     connectionMode={ConnectionMode.Loose} 
    > 
     <Controls showFitView={false} /> 
     <Background /> 
    </ReactFlow> 
   </div> 

   {/* SuperViz Components */} 
   <WhoIsOnline position="comments" /> 
   <Comments 
    pin={pin} 
    position="left" 
    buttonLocation="comments" 
    onPinActive={openThreads} 
    onPinInactive={closeThreads} 
   /> 
   <MousePointers elementId="react-flow-container" /> 
  </main> 
 </div> 
);

Explanation:

ReactFlow: Displays the flowchart with nodes, edges, and interaction handlers.
Realtime: Manages real-time synchronization of state across participants.
WhoIsOnline: Shows a list of online participants in the session.
Comments: Provides the ability to add and view contextual comments.
MousePointers: Displays real-time mouse pointers for all participants.

Step 4: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:


npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the flowchart and see updates in real-time across multiple participants.

2. Test the Application

Collaborative Flowchart: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that changes made by one participant are reflected in real-time for others.
Real-Time Updates: Test the responsiveness of the application to see if it syncs correctly with actions performed by other users.

Summary

In this tutorial, we built a collaborative flowchart application using React Flow and SuperViz for real-time synchronization. We configured a React application to handle node and edge interactions, enabling multiple users to collaborate seamlessly on a shared diagram. This setup can be extended and customized to fit various scenarios where real-time collaboration and workflow visualization are required.

Feel free to explore the full code and further examples in the GitHub repository for more details.

Join us: SuperViz Hackathon 2.0: AI meets RealTime

Ready to join? Visit the Super Hackathon 2.0 website to register and stay updated.

Learn how to build a real-time chat

Pachi 🥑 — Thu, 10 Oct 2024 13:25:02 +0000

Hi there 👋🏼

This tutorial will guide you through building a real-time chat application using SuperViz. Real-time chat is a crucial feature for modern web applications, enabling users to communicate instantly with each other. Whether you're building a collaborative platform, customer support tool, or social networking site, adding real-time chat enhances user interaction and engagement.

We'll demonstrate how to set up a simple chat interface where participants can send and receive messages in real-time. By the end of this tutorial, you'll have a fully functional chat application that you can extend and customize to meet your specific needs.

Let's get started!

Prerequisite

To follow this tutorial, you will need a SuperViz account and a developer token. If you already have an account and a developer token, you can move on to the next step.

Create an account

Retrieving a Developer Token

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate SuperViz for real-time communication.

1. Create a New React Project

First, create a new React application using Vite with TypeScript.


npm create vite@latest realtime-chat -- --template react-ts
cd realtime-chat

2. Install Required Libraries

Next, install the necessary libraries for our project:


npm install @superviz/realtime uuid react-icons

@superviz/realtime: SuperViz Real-Time library for integrating real-time synchronization into your application.
uuid: A library for generating unique identifiers, useful for creating unique participant IDs.
react-icons: A library for including icons in React applications, used here for the send button icon.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.


npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.


/** @type  {import('tailwindcss').Config} */
export  default  {
content:  [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme:  {
extend:  {},
},
plugins:  [],
}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)


@tailwind base;
@tailwind components;
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.


VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and handle real-time chat messages.

1. Implement the App Component

Open src/App.tsx and set up the main application component using SuperViz to manage the chat functionality.


import  { v4 as generateId }  from  "uuid";
import  { useCallback, useEffect, useState, useRef }  from  "react";
import  {
  Realtime,
  type  RealtimeMessage,
  type  Channel,
}  from  "@superviz/realtime/client";
import  {  IoMdSend  }  from  "react-icons/io";

Explanation:

Imports: Import necessary components from React, SuperViz, UUID, and React Icons for managing state, initializing SuperViz, and rendering the chat interface.

2. Define Constants

Define constants for the API key, room ID, and message types.


const apiKey =  import.meta.env.VITE_SUPERVIZ_API_KEY  as  string;
const  ROOM_ID  =  'realtime-chat';

type  Message  =  {
 participantName:  string;
 message:  string;
};

Explanation:

apiKey: Retrieves the SuperViz API key from environment variables.
ROOM_ID: Defines the room ID for the SuperViz session.
Message: A type that will be used to extend RealtimeMessage to include participant name and message content.

3. Create the App Component

Set up the main App component and initialize state variables and references.


export  default  function  App()  {
  const url =  new  URL(window.location.href);
  const name = url.searchParams.get("name")  ||  "Anonymous";

  const participant =  useRef({
   id:  generateId(),
   name:  'participant-name',
  });
  const channel =  useRef<Channel |  null>(null);
  const initialized =  useRef(false);
  const  [message, setMessage]  =  useState('');
  const  [messages, setMessages]  =  useState<Message[]>([]);

Explanation:

participant: Stores the current participant's ID and name using useRef.
channel: Stores the reference to the real-time communication channel.
initialized: Tracks whether SuperViz has been initialized.
message & messages: Manages the current message input and the list of chat messages.

4. Initialize SuperViz

Create a function to initialize SuperViz and set up real-time message handling.


const initialize =  useCallback(async  ()  =>  {
  if  (initialized.current)  return;
  initialized.current  =  true;

  const realtime =  new  Realtime(apiKey,  {
   participant: participant.current,
  });

  channel.current  =  await realtime.connect("message-topic");

  channel.current.subscribe<Message>("message",  (data)  =>  {
   setMessages((prev)  =>
    [...prev, data].sort((a, b)  => a.timestamp  - b.timestamp)
  );
 });
},  [initialized]);

Explanation:

initialize: Initializes SuperViz, sets up the real-time component, and subscribes to the message topic.
Realtime: Handles real-time communication for the chat.
channel.current: Stores the connection to the 'message-topic' channel, where messages are published and subscribed.

5. Handle Sending Messages

Create a function to send messages to the chat.


const sendMessage =  useCallback(()  =>  {
  if  (!channel.current)  return;

  channel.current.publish('message',  {
   message,
   participantName: participant.current!.name,
  });

  setMessage('');
},  [message]);

Explanation:

sendMessage: Publishes the current message to the 'message-topic' channel and resets the message input.

6. Use Effect Hook for Initialization

Use the useEffect hook to trigger the initialize function on component mount.


useEffect(()  =>  {
  initialize();
},  [initialize]);

Explanation:

useEffect: Calls the initialize function once when the component mounts, setting up the SuperViz environment and real-time chat.

Step 3: Render the Chat Interface

Finally, return the JSX structure for rendering the chat interface.


return ( 
<div className="w-full h-full bg-[#e9e5ef] flex items-center justify-center flex-col"> 
 <header className="w-full p-5 bg-purple-400 flex items-center justify-between"> 
  <h1 className="text-white text-2xl font-bold">Realtime Chat</h1> 
 </header> 
 <main className="flex-1 flex w-full flex-col justify-between overflow-hidden"> 
  <div className="bg-[#e9e5ef] w-full p-2 overflow-auto"> 
   {messages.map((message, index) => ( 
    <div 
     key={index} 
     className={`${ 
      message.participantId === participant.current!.id 
       ? "justify-end" 
       : "justify-start" 
      } w-full flex mb-2`} 
     > 
     <div 
      className={`${ 
       message.participantId === participant.current!.id 
        ? "bg-[#f29ee8]" 
        : "bg-[#baa9ff]" 
       } text-black p-2 rounded-lg max-w-xs`} 
      > 
      <div 
       className={`${ 
        message.participantId === participant.current!.id 
         ? "text-right" 
         : "text-left" 
        } text-xs text-[#57535f]`} 
       > {message.participantId === participant.current!.id 
           ? "You" 
           : message.data.participantName} 
        </div> 
        {message.data.message} 
       </div> 
      </div> 
     ))} 
    </div> 
    <div className="p-2 flex items-center justify-between gap-2 w-full h-[58px]"> 
     <input 
      type="text" 
      placeholder="Type your message..." 
      className="flex-1 border rounded-full px-4 py-2 focus:outline-none" 
      value={message} 
      onChange={(e) => setMessage(e.target.value)} 
     /> 
     <button 
      className="bg-purple-400 text-white px-4 py-2 rounded-full disabled:opacity-50" 
      onClick={sendMessage} 
      disabled={!message || !channel.current} 
     > 
      <IoMdSend /> 
     </button> 
    </div>
   </main> 
  </div> 
 )

Explanation:

Chat Interface: Displays the chat messages and an input field with a send button. Messages are styled differently based on whether they are sent by the current participant or others.

Step 4: Understanding the Project Structure

Here's a quick overview of how the project structure supports a real-time chat application:

App.tsx:
- Initializes SuperViz and sets up real-time chat functionality.
- Handles sending and receiving chat messages in real-time.
Chat Interface: Displays messages in a chat bubble format and provides an input field and send button for users to send messages.
Real-Time Communication: Manages real-time communication between participants using SuperViz.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:


npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the chat interface and see messages in real-time as other participants join.

2. Test the Application

Real-Time Messaging: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that messages are sent and received in real-time.
Collaborative Interaction: Test the responsiveness of the application by sending messages and observing how the chat updates for all participants.

Summary

In this tutorial, we built a real-time chat application using SuperViz. We configured a React application to handle real-time messaging, enabling multiple users to communicate seamlessly. This setup can be extended and customized to fit various scenarios where real-time communication is essential.

For more details, please explore the full code and further examples in the GitHub repository.

Join us: SuperViz Hackathon 2.0: AI meets RealTime

Register for our Super Hackathon 2.0 this October to showcase your innovative real-time AI communication solutions! Hosted by SuperViz and with $5,000 in prizes up for grabs, we challenge you to integrate AI with SuperViz's real-time platform, pushing the boundaries of interactive communication.

Ready to join? Visit the Super Hackathon 2.0 website to register and stay updated.

How to build a notifications feature with React

Pachi 🥑 — Tue, 08 Oct 2024 23:46:01 +0000

Hello everyone 👋🏼

In today's tutorial, we'll guide you through building a real-time notifications feature using SuperViz, a powerful platform for real-time communication and data synchronization. Real-time notifications are a critical feature for many applications, enabling instant communication and engagement with users as events unfold.

We'll use SuperViz's Real-Time Data Engine to send and receive notifications, demonstrating how to integrate this functionality into a React application. Although we’ll use a simple example for illustrative purposes, the techniques you’ll learn can be applied to various scenarios such as messaging apps, live updates for e-commerce sites, or alert systems in business applications. Let's dive in!

Prerequisite

You will need a SuperViz account and a developer token to follow this tutorial. If you already have an account and a developer token, you can move on to the next step.

Create an account

Retrieving a Developer Token

You’ll need to provide a developer token to use the platform, as this token is essential for associating platform requests with your account. You can retrieve development and production SuperViz tokens from the dashboard..

Copy and save the developer token, as you will need it in the next steps of this tutorial.

Step 1: Setting Up the Server with Express.js

In this tutorial, we'll guide you through building a real-time notification system using SuperViz, a powerful platform for real-time communication and data synchronization. Real-time notifications are a critical feature for many applications, enabling instant communication and engagement with users as events unfold.

The server will handle incoming notification requests and use SuperViz to send real-time updates to clients.

1. Create a New Project and Install Dependencies

First, set up a new Node.js project and install the necessary packages for the server.


mkdir realtime-notifications-server
cd realtime-notifications-server
npm init -y
npm install express body-parser dotenv cors

express: A web application framework for setting up the server.
body-parser: Middleware to parse incoming JSON request bodies.
dotenv: Loads environment variables from a .env file.
cors: Middleware to enable Cross-Origin Resource Sharing.

2. Set Up the Express Server

Create a file named server.js and configure the server.


// server.js
import  process  from  "node:process";
import  express  from  "express";
import  bodyParser  from  "body-parser";
import  dotenv  from  "dotenv";
import  cors  from  "cors";

dotenv.config();  // Load environment variables

const app =  express();  // Initialize Express application


app.use(bodyParser.json());  // Use body-parser to parse JSON

app.use(cors());  // Enable CORS


// Basic route to check server uptime
app.get("/",  (req, res)  =>  {
    res.send(
        JSON.stringify({
            uptime: process.uptime(),
          })
    );

});

Express App: An Express application is created to handle requests.
Middlewares: bodyParser is used for JSON parsing, and cors is enabled for cross-origin requests.

3. Implement the Notification Endpoint

Define an endpoint to schedule and send notifications using SuperViz.


app.post("/notify", (req, res) => {
  if (!req.body) {
    return res.status(400).send({
      status: "error",
      message: "Missing body",
    });
  }

  const { channel, message, msToWait } = req.body;

  if (!channel || !message || !msToWait) {
    return res.status(400).send({
      status: "error",
      message: "Missing required fields: channel, message, msToWait",
    });
  }

  setTimeout(async () => {
    const response = await fetch(
      `https://api.superviz.com/realtime/${channel}/publish`,
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          client_id: process.env.VITE_SUPERVIZ_CLIENT_ID,
          secret: process.env.VITE_SUPERVIZ_SECRET_KEY,
        },
        body: JSON.stringify({
          name: "new-notification",
          data: message,
        }),
      }
    );

    console.log(
      `Sending data to ${channel}, message: ${message}`,
      response.status
    );
  }, msToWait);

  res.send({
    status: "success",
    message: "Notification scheduled",
  });
});

Notify Endpoint: The /notify endpoint accepts POST requests to schedule notifications.
Request Validation: Validates the presence of channel, message, msToWait, and roomId.
Delayed Execution: Uses setTimeout to wait msToWait milliseconds before sending the notification using the SuperViz API.

4. Start the Server

Launch the server to listen for requests.


app.listen(3000,  ()  =>  {
    console.log("Server is running on <http://localhost:3000>");
});

Server Listening: The server listens on port 3000 and logs a confirmation message when it's running.

Step 2: Setting Up the Frontend with React

The frontend will display notifications in real time using React and SuperViz.

1. Create a New React Project

Initialize a new React application using Create React App with TypeScript.


npx create-react-app realtime-notifications-frontend --template typescript
cd realtime-notifications-frontend

2. Install SuperViz SDK and React Toastify

Add the necessary packages to the project.


npm install @superviz/sdk react-toastify uuid

@superviz/sdk: SDK for real-time collaboration features.
react-toastify: Library for showing notifications as toast messages.
uuid: Library for generating unique identifiers.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.


npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.


/** @type  {import('tailwindcss').Config} */
sexport  default  {
content:  [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme:  {
extend:  {},
},
plugins:  [],

}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)


@tailwind base;
@tailwind components;
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in the frontend directory and add your SuperViz API key.


VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_API_KEY

Environment Variables: Store the API key securely using .env and access it through import.meta.env.

5. Implement the Main App Component

Open src/App.tsx and set up the main component to handle notifications.


import { v4 as generateId } from "uuid";
import { useCallback, useEffect, useState } from "react";
import SuperVizRoom, {
  Realtime,
  RealtimeComponentEvent,
} from "@superviz/sdk";
import { ToastContainer, toast } from "react-toastify";
import "react-toastify/dist/ReactToastify.css";

const apiKey = import.meta.env.VITE_SUPERVIZ_API_KEY as string;
const PARTICIPANT_ID = generateId();

export default function App() {
  const initialized = useRef(false);
  const [message, setMessage] = useState("");
  const [msToWait, setMsToWait] = useState(1000);

  const initialize = useCallback(async () => {
    if (initialized.current) return;

    const realtime = new Realtime(apiKey, {
      participant: {
        id: PARTICIPANT_ID,
        name: "participant-name",
      },
      debug: true,
    });

    initialized.current = true;

    const channel = await realtime.connect("notification-topic");

    channel.subscribe("new-notification", (data) => {
      if (typeof data === "string") return;

      toast.info(data.data as string, {
        position: "top-right",
        autoClose: 3000,
      });
    });
  }, [initialized]);

State Management: The component uses useState to manage the state for initialization, message, and delay time.
SuperViz Initialization: Connects to the SuperViz room using the API key, room ID, and participant details.
Realtime Subscription: Subscribes to new-notification events and displays the notification using react-toastify.

6. Implement the Notification Function

Add the logic for sending notifications.


const notify = useCallback(async () => { 
    try { 
        fetch("http://localhost:3000/notify", { 
            method: "POST", 
            headers: { 
                "Content-Type": "application/json", 
            }, 
            body: JSON.stringify({ 
                roomId: ROOM_ID, 
                channel: "notification-topic", 
                message: message, 
                msToWait: msToWait || 1000, 
            }), 
        }); 

        toast.success("Notification sent!", { 
            position: "top-right", 
            autoClose: 1000, 
        }); 

        setMessage(""); 
        setMsToWait(1000); 
        } catch (error) { 
        toast.error("Failed to send notification!", { 
            position: "top-right", 
            autoClose: 1000, 
        }); 
    } 
}, [message, msToWait]);

Notify Function: Sends a POST request to the server to schedule the notification.
Success/Failure Toasts: Displays a toast message indicating whether the notification was sent successfully or failed.

7. Render the UI Components

Complete the App component by rendering the user interface.


useEffect(() => {
  initialize();
}, [initialize]);

return (
  <>
    <ToastContainer />
    <div className="w-full h-full bg-gray-200 flex items-center justify-center flex-col">
      <header className="w-full p-5 bg-purple-400 flex items-center justify-between">
        <h1 className="text-white text-2xl font-bold">Realtime Notifications</h1>
      </header>
      <main className="flex-1 p-20 flex w-full gap-2 items-center justify-center">
        <form>
          <h2 className="text-xl font-bold">Send Notification</h2>
          <p className="text-gray-500">
            Schedule a notification to be sent to all participants in the room.
          </p>
          <hr className="my-5" />

          <label htmlFor="message" className="text-lg font-bold">
            Message
          </label>
          <input
            type="text"
            id="message"
            name="message"
            placeholder="Hello, World!"
            className="w-full p-3 border border-gray-300 rounded-md"
            value={message}
            onChange={(e) => setMessage(e.target.value)}
          />
          <hr className="my-5" />
          <label htmlFor="msToWait" className="text-lg font-bold">
            Time to wait (ms)
          </label>
          <input
            type="number"
            id="msToWait"
            name="msToWait"
            placeholder="1000"
            className="w-full p-3 border border-gray-300 rounded-md"
            min={1000}
            value={msToWait}
            onChange={(e) => setMsToWait(Number(e.target.value))}
          />
          <hr className="my-5" />
          <button
            type="button"
            onClick={notify}
            className="bg-purple-400 text-white p-3 rounded-md disabled:bg-gray-300"
            disabled={!message || !initialized || msToWait < 1000}
          >
            Send Notification
          </button>
        </form>
      </main>
    </div>
  </>
);

UI Structure: The UI contains an input for the message and delay time, and a button to send notifications.
Form Validation: The button is disabled if the message is empty, the system is not initialized, or the delay time is less than 1000ms.

Step 3: Running the Application

To start the application, run this command in the terminal:


npm run dev

This command will start both the server and the frontend application.

You can access the frontend application at http://localhost:5173 and the server at http://localhost:3000.

Summary

In this tutorial, we've built a real-time notification system using SuperViz, Express.js, and React. The server schedules and sends notifications to clients using SuperViz's real-time API. The frontend subscribes to notification events, displaying them as toast messages. By following these steps, you can customize the notification system to handle different types of messages, add more features, and deploy it to a production environment.

Feel free to refer to the full code in the GitHub repository for more details.

Join us: SuperViz Hackathon 2.0: AI meets RealTime

Ready to join? Visit the Super Hackathon 2.0 website to register and stay updated.

How to add real-time synchronization to your productivity-tool

Pachi 🥑 — Thu, 03 Oct 2024 17:44:24 +0000

Hello everyone,
Today we bring to you a tutorial teaching how to add real-time synchronization to a productivity tool using SuperViz.

Real-time synchronization is a crucial feature for collaborative applications, allowing multiple users to interact with shared content simultaneously and see each other's changes as they happen.
With SuperViz, you can build interactive tools that update live, providing a seamless collaborative experience for users.

We'll demonstrate how to integrate real-time synchronization into a notes application, enabling users to collaborate on notes with real-time updates. This setup allows multiple participants to edit notes, move elements, and see changes instantly as they happen.

Let's get started!

Prerequisite

To follow this tutorial, you will need a SuperViz account and a developer token. If you already have an account and a developer token, you can move on to the next step.

Create an account

Retrieving a Developer Token

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate the SuperViz SDK for real-time synchronization.

1. Create a New React Project

First, create a new React application using Create React App with TypeScript.


npm create vite@latest realtime-notes-app -- --template react-ts
cd realtime-notes-app

2. Install SuperViz SDK

Next, install SuperViz, which will enable us to add real-time synchronization features to our application.


npm install @superviz/sdk uuid

@superviz/sdk: SDK for integrating real-time collaboration features, including synchronization.
uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.


npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.


/** @type  {import('tailwindcss').Config} */
export  default  {
content:  [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme:  {
extend:  {},
},
plugins:  [],
}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)


@tailwind base;
@tailwind components;
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.


VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and handle real-time synchronization in a notes application.

1. Implement the App Component

Open src/App.tsx and set up the main application component using SuperViz to manage the collaborative environment.


import { useCallback, useEffect, useRef, useState } from "react";
import SuperVizRoom, {
  LauncherFacade,
  MousePointers,
  WhoIsOnline,
} from "@superviz/sdk";
import { Realtime, type Channel } from "@superviz/realtime/client";
import { v4 as generateId } from "uuid";
import { NoteNode } from "./components/note-node";
import { Note } from "./common/types";

Explanation:

Imports: Import necessary components from React, SuperViz SDK, and UUID for managing state, initializing SuperViz, and generating unique identifiers.

2. Define Constants

Define constants for the API key, room ID, and participant ID.


const apiKey =  import.meta.env.VITE_SUPERVIZ_API_KEY  as  string;
const  ROOM_ID  =  'video-huddle-application';
const  PARTICIPANT_ID  =  generateId();

Explanation:

apiKey: Retrieves the SuperViz API key from environment variables.
ROOM_ID: Defines the room ID for the SuperViz session.
PARTICIPANT_ID: Generates a unique participant ID using the uuid library.

3. Create the App Component

Set up the main App component and initialize state variables.


export  default  function  App()  {
    const  [initialized, setInitialized]  =  useState(false);
    const  [notes, setNotes]  =  useState<Note[]>([]);
    const superviz =  useRef<LauncherFacade |  null>(null);
    const channel =  useRef<any  |  null>(null);

Explanation:

initialized: A state variable to track whether the SuperViz environment has been set up.
notes: A state variable to manage the list of notes in the application.
superviz: A ref to store the SuperViz room instance.
channel: A ref to store the real-time communication channel.

4. Initialize SuperViz and Real-Time Components

Create an initialize function to set up the SuperViz environment and configure real-time synchronization.


const initialize = useCallback(async () => { 
    if (initialized) return; 

    superviz.current = await SuperVizRoom(apiKey, { 
        roomId: ROOM_ID, 
        participant: { 
            id: PARTICIPANT_ID, 
            name: 'my participant', 
        }, 
        group: { 
            id: 'video-huddle-application', 
            name: 'video-huddle-application', 
        }, 
    })

Explanation:

initialize: An asynchronous function that initializes the SuperViz room and checks if it's already initialized to prevent duplicate setups.
SuperVizRoom: Configures the room, participant, and group details for the session.

5. Set Up Real-Time Synchronization

Within the initialize function, set up real-time synchronization for notes.


const realtime = new Realtime(apiKey, {
  participant: {
    id: PARTICIPANT_ID,
    name,
  },
});

channel.current = await realtime.connect("realtime-sync");

channel.current.subscribe<Note>("note-change", (event) => {
  const note = event.data;

  if (event.participantId === PARTICIPANT_ID || !note) return;

  setNotes((previous) => {
    return previous.map((n) => {
      if (n.id === note.id) {
        return note;
      }

      return n;
    });
  });
});

Explanation:

Realtime: Initializes the real-time component for synchronization.
RealtimeComponentEvent.REALTIME_STATE_CHANGED: Subscribes to changes in the real-time component state.
note-change Subscription: Listens for note changes and updates the local state accordingly, ignoring changes from the current participant to avoid redundancy.

6. Add Mouse Pointers and Online Status

Enhance the application with mouse pointers and online status indicators.


const mousePointers = new MousePointers('mouse-container');
const whoIsOnline = new WhoIsOnline();
superviz.current.addComponent(mousePointers);
superviz.current.addComponent(whoIsOnline)

Explanation:

MousePointers: Displays real-time mouse pointers to show where other participants are interacting.
WhoIsOnline: Shows a list of currently online participants in the session.

7. Initialize Notes

Set the initial state of notes with example content.


setInitialized(true);
setNotes([
  { id:  'note-1', title:  `Unicorn's Shopping List`, content:  'Rainbow sprinkles, cloud fluff, and pixie dust', x:  20, y:  50  },
  { id:  'note-2', title:  `Zombie's To-Do List`, content:  'Find brains, practice groaning, shuffle aimlessly', x:  20, y:  50  },
  { id:  'note-3', title:  `Alien's Earth Observations`, content:  'Humans obsessed with cat videos and avocado toast. Fascinating!', x:  20, y:  50  },

  ]);

},  [initialized, setNotes]);

Explanation:

setInitialized: Marks the application as initialized to prevent reinitialization.
setNotes: Sets the initial notes with predefined content, positioning them on the screen.

8. Handle Note Changes

Implement the handleNoteChange function to manage updates to notes.


const handleNoteChange = useCallback((note: Note) => { 
    setNotes((prevNotes) => { 
        return prevNotes.map(n => { 
            if (n.id === note.id) { 
                return note; 
            } 

            return n; 
        }); 
    }); 

    if (channel.current) { 
        channel.current.publish('note-change', note); 
    } 
}, []);

Explanation:

handleNoteChange: Updates the local state of notes when a note is edited and publishes the change to other participants.
channel.current.publish: Sends the updated note to all participants through the real-time channel.

9. Use Effect Hook for Initialization

Use the useEffect hook to trigger the initialize function on component mount.


useEffect(()  =>  {
  initialize();
},  [initialize]);

Explanation:

useEffect: Calls the initialize function once when the component mounts, setting up the SuperViz environment and real-time synchronization.

10. Render the Application

Return the JSX structure for rendering the application, including notes and collaboration features.


return ( 
    <> 
        <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'>   
            <header className='w-full p-5 bg-purple-400 flex items-center justify-between'> 
                <h2 className='text-white text-2xl font-bold'>Real-Time Sync</h2> 
            </header> 
            <main id="mouse-container" className='flex-1 p-20 flex w-full gap-2 items-center justify-center overflow-hidden'> 
                { 
                    notes.map((note, index) => ( 
                        <NoteNode key={index} note={note} onChange={handleNoteChange} /> 
                    )) 
                }   
            </main> 
        </div> 
    </> 
)

Explanation:

Header: Displays the title of the application.
Main Container: Wraps the notes and collaboration elements, providing a space for interaction.
NoteNode Component: Renders each note, allowing for real-time updates and changes.

Step 3: Create the NoteNode Component

The NoteNode component is responsible for displaying individual notes and handling edits.

1. Create the NoteNode Component

Create a new file named src/components/note-node.tsx and add the following implementation:


import React, { useState } from "react"; 
import { Note } from "../common/types";

interface NoteNodeProps { 
    note: Note; 
    onChange: (note: Note) => void; 
} 

export const NoteNode: React.FC<NoteNodeProps> = ({ note, onChange }) => { 
    const [title, setTitle] = useState(note.title); 
    const [content, setContent] = useState(note.content); 

    const handleTitleChange = (event: React.ChangeEvent<HTMLInputElement>) => { 
        const newTitle = event.target.value; 
        setTitle(newTitle); 
        onChange({ ...note, title: newTitle }); 
    }; 
const handleContentChange = (event: React.ChangeEvent<HTMLTextAreaElement>) => { 
    const newContent = event.target.value; 
    setContent(newContent); 
    onChange({ ...note, content: newContent }); 
}; 

    return ( 
        <div className="note-node p-4 bg-white rounded shadow-lg" style={{ position: "absolute", left: note.x, top: note.y }}> 
            <input 
                type="text" 
                value={title} 
                onChange={handleTitleChange} 
                className="font-bold mb-2 w-full border-none focus:outline-none" 
            /> 
            <textarea 
                value={content} 
                onChange={handleContentChange} 
                className="w-full border-none focus:outline-none" 
                rows={5} 
            /> 
        </div> 
    ); 
}

Explanation:

NoteNode Component: Displays each note with editable fields for title and content.
handleTitleChange & handleContentChange: Updates the state and calls the onChange callback to propagate changes.

2. Define the Note Type

Create a new file named src/common/types.ts and define the Note type.


export  interface  Note  {
     id:  string;
     title:  string;
     content:  string;
     x:  number;
     y:  number;

}

Explanation:

- Note Type: Defines the structure of a note, including ID, title, content, and position.

Step 4: Understanding the Project Structure

Here's a quick overview of how the project structure supports real-time synchronization:

App.tsx
- Initializes the SuperViz environment.
- Sets up participant information and room details.
- Handles real-time synchronization and mouse pointers.
NoteNode.tsx
- Displays individual notes with editable fields.
- Handles local state updates and propagates changes to the parent component.
types.ts
- Defines the data structure for notes used throughout the application.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:


npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the notes and see updates in real-time as other participants join the session.

2. Test the Application

Real-Time Notes: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that changes made to notes are reflected in real-time for all users.
Collaborative Interaction: Test the responsiveness of the application by editing notes and observing how changes appear for other participants.

Summary

In this tutorial, we built a collaborative notes application using SuperViz for real-time synchronization. We configured a React application to handle note editing, enabling multiple users to collaborate seamlessly on shared notes. This setup can be extended and customized to fit various scenarios where real-time collaboration and document editing are required.

Feel free to explore the full code and further examples in the GitHub repository for more details.

Join us: SuperViz Hackathon 2.0: AI meets RealTime

Ready to join? Visit the Super Hackathon 2.0 website to register and stay updated.

SuperViz Hackathon 2.0: AI meets RealTime

Vitor Norton — Wed, 02 Oct 2024 17:39:02 +0000

A couple of months after our first hackathon, we are ready to announce: The Super Hackathon 2.0!

Get ready to participate in our Super Hackathon 2.0 this October to showcase your innovative real-time AI communication solutions! Hosted by SuperViz, this exciting hackathon is the perfect opportunity for developers to unleash their creativity and push the boundaries of using AI with real-time technology.

With $5,000 in prizes up for grabs, we challenge you to integrate AI with SuperViz's real-time platform, pushing the boundaries of interactive communication.

You can utilize any language model, such as GPT, Gemini, LLaMA, or Claude, to create innovative tools that elevate the real-time experience, making communication smarter and more efficient. How will you combine AI with real-time data to create meaningful improvements in collaboration and productivity?

Event Details:

Date: October 18-27, 2024
Prizes:
- Fist Place: $3,500
- Second Place: $1,000
- Third Place: $500
Platform: Online

We will have workshops, feedback sessions, and make sure you have all the resources you need to create the best solution to compete!

Ready to join? Visit the Super Hackathon 2.0 website to register and stay updated. Let's create something amazing!

Learn how to build a multiplayer chess game with React

Pachi 🥑 — Thu, 26 Sep 2024 14:00:00 +0000

Hello and welcome! 👋🏼

Today I bring a tutorial to guide you through building a multiplayer chess game using SuperViz. Multiplayer games require real-time synchronization and interaction between players, making them ideal applications for SuperViz's capabilities.

This tutorial will show you how to create a chess game where two players can play against each other in real-time, seeing each other's moves as they happen.

We'll demonstrate how to set up a chessboard using the react-chessboard library, manage the game state with chess.js, and synchronize player moves with SuperViz. This setup allows multiple participants to join a chess game, make moves, and experience a seamless and interactive chess game environment. Let's get started!

Prerequisite

To follow this tutorial, you will need a SuperViz account and a developer token. If you already have an account and a developer token, you can move on to the next step.

Create an Account

To create an account, go to SuperViz Registration and create an account using either Google or an email/password. It's important to note that when using an email/password, you will receive a confirmation link that you'll need to click to verify your account.

Retrieving a Developer Token

To use the SDK, you’ll need to provide a developer token, as this token is essential for associating SDK requests with your account. You can retrieve both development and production SuperViz tokens from the dashboard. Copy and save the developer token, as you will need it in the next steps of this tutorial.

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate SuperViz.

1. Create a New React Project

First, create a new React application using Create React App with TypeScript.

npm create vite@latest chess-game -- --template react-ts
cd chess-game

2. Install Required Libraries

Next, install the necessary libraries for our project:

npm install @superviz/sdk react-chessboard chess.js uuid

@superviz/sdk: SDK for integrating real-time collaboration features, including synchronization.
react-chessboard: A library for rendering a chessboard in React applications.
chess.js: A library for managing chess game logic and rules.
uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.

/** @type  {import('tailwindcss').Config} */
export  default  {
content:  [
"./index.html",
"./src/**/*.{js,ts,jsx,tsx}",
],
theme:  {
extend:  {},
},
plugins:  [],

}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)


@tailwind base;
@tailwind components;
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.


VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and handle real-time chess moves.

1. Implement the App Component

Open src/App.tsx and set up the main application component using SuperViz to manage the collaborative environment.

import { v4 as generateId } from "uuid";
import { useCallback, useEffect, useRef, useState } from "react";
import SuperVizRoom, { WhoIsOnline } from "@superviz/sdk";
import {
  Realtime,
  type Channel,
  type RealtimeMessage,
} from "@superviz/realtime/client";
import { Chessboard } from "react-chessboard";
import { Chess, Square } from "chess.js";

Explanation:

Imports: Import necessary components from React, SuperViz SDK, react-chessboard, chess.js, and UUID for managing state, initializing SuperViz, rendering the chessboard, and generating unique identifiers.

2. Define Constants

Define constants for the API key, room ID, and player ID.

const apiKey =  import.meta.env.VITE_SUPERVIZ_API_KEY  as  string;
const  ROOM_ID  =  'chess-game';
const  PLAYER_ID  =  generateId();

Explanation:

apiKey: Retrieves the SuperViz API key from environment variables.
ROOM_ID: Defines the room ID for the SuperViz session.
PLAYER_ID: Generates a unique player ID using the uuid library.

3. Define Chess Message Type

Create a type for handling chess move messages.

type ChessMessageUpdate = RealtimeMessage<{
  data: {
    sourceSquare: Square;
    targetSquare: Square;
  };
}>;

Explanation:

ChessMessageUpdate: Extends the RealtimeMessage to include the source and target squares for a chess move.

4. Create the App Component

Set up the main App component and initialize state variables.


export default function App() {
  const initialized = useRef(false);
  const [gameState, setGameState] = useState<Chess>(new Chess());
  const [gameFen, setGameFen] = useState<string>(gameState.fen());

  const channel = useRef<Channel | null>(null);

Explanation:

initialized: A state variable to track whether the SuperViz environment has been set up.
gameState: A state variable to manage the chess game state using the chess.js library.
gameFen: A state variable to store the FEN (Forsyth-Edwards Notation) string representing the current game position.
channel: A ref to store the real-time communication channel.

5. Initialize SuperViz and Real-Time Components

Create an initialize function to set up the SuperViz environment and configure real-time synchronization.

const initialize = useCallback(async () => {
  if (initialized.current) return;
  initialized.current = true;

  const superviz = await SuperVizRoom(apiKey, {
    roomId: ROOM_ID,
    participant: {
      id: PLAYER_ID,
      name: "player-name",
    },
    group: {
      id: "chess-game",
      name: "chess-game",
    },
  });

  const realtime = new Realtime(apiKey, {
    participant: {
      id: PLAYER_ID,
      name: "player-name",
    },
  });
  const whoIsOnline = new WhoIsOnline();

  superviz.addComponent(whoIsOnline);

  channel.current = await realtime.connect("move-topic");

  channel.current.subscribe<ChessMessageUpdate["data"]>(
    "new-move",
    handleRealtimeMessage
  );
}, [handleRealtimeMessage, initialized]);

Explanation:

initialize: An asynchronous function that initializes the SuperViz room and checks if it's already initialized to prevent duplicate setups.
SuperVizRoom: Configures the room, participant, and group details for the session.
Realtime Subscription: Connects to the move-topic channel and listens for new moves, updating the local state accordingly.

6. Handle Chess Moves

Create a function to handle chess moves and update the game state.

const makeMove = useCallback((sourceSquare: Square, targetSquare: Square) => { 
    try { 
        const gameCopy = gameState; 
        gameCopy.move({ from: sourceSquare, to: targetSquare, promotion: 'q' }); 

        setGameState(gameCopy); 
        setGameFen(gameCopy.fen()); 

        return true; 
    } catch (error) { 
        console.log('Invalid Move', error); 
        return false; 
    }
}, [gameState]);

Explanation:

makeMove: Attempts to make a move on the chessboard, updating the game state and FEN string if the move is valid.
Promotion: Automatically promotes a pawn to a queen if it reaches the last rank.

7. Handle Piece Drop

Create a function to handle piece drop events on the chessboard.

const onPieceDrop = (sourceSquare: Square, targetSquare: Square) => { 
    const result = makeMove(sourceSquare, targetSquare); 

    if (result) { 
        channel.current.publish('new-move', { 
            sourceSquare, 
            targetSquare, 
        });
    } 
     return result; 
};

Explanation:

onPieceDrop: Handles the logic for when a piece is dropped on a new square, making the move and publishing it to the SuperViz channel if valid.

8. Handle Real-Time Messages

Create a function to handle incoming real-time messages for moves made by other players.

const handleRealtimeMessage =  useCallback((message: ChessMessageUpdate)  =>  {
  if  (message.participantId ===  PLAYER_ID)  return;

  const  { sourceSquare, targetSquare }  = message.data;
  makeMove(sourceSquare, targetSquare);
},  [makeMove]);

Explanation:

handleRealtimeMessage: Listens for incoming move messages and updates the game state if the move was made by another participant.

9. Use Effect Hook for Initialization

Use the useEffect hook to trigger the initialize function on component mount.


useEffect(()  =>  {
  initialize();
},  [initialize]);

Explanation:

useEffect: Calls the initialize function once when the component mounts, setting up the SuperViz environment and real-time synchronization.

10. Render the Application

Return the JSX structure for rendering the application, including the chessboard and collaboration features.

return ( 
    <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'>
        <header className='w-full p-5 bg-purple-400 flex items-center justify-between'> 
            <h1 className='text-white text-2xl font-bold'>SuperViz Chess Game</h1> 
        </header> 
        <main className='w-full h-full flex items-center justify-center'> 
            <div className='w-[500px] h-[500px] shadow-sm border-2 border-gray-300 rounded-md'>
                <Chessboard position={gameFen} onPieceDrop={onPieceDrop} /> 
                <div className='w-[500px] h-[50px] bg-gray-300 flex items-center justify-center'> 
                    <p className='text-gray-800 text-2xl font-bold'>Turn: {gameState.turn() === 'b' ? 'Black' : 'White'}</p> 
                </div> 
            </div> 
        </main> 
    </div>
);

Explanation:

Header: Displays the title of the application.
Chessboard: Renders the chessboard using the Chessboard component, with gameFen as the position and onPieceDrop as the event handler for piece drops.
Turn Indicator: Displays the current player's turn (Black or White).

Step 3: Understanding the Project Structure

Here's a quick overview of how the project structure supports a multiplayer chess game:

App.tsx
- Initializes the SuperViz environment.
- Sets up participant information and room details.
- Handles real-time synchronization for chess moves.
Chessboard
- Displays the chessboard and manages piece movements.
- Integrates real-time communication to synchronize moves between players.
Chess Logic
- Uses chess.js to manage game rules and validate moves.
- Updates the game state and FEN string to reflect the current board position.

Step 4: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:


npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the chessboard and see moves in real-time as other participants join the session.

2. Test the Application

Real-Time Chess Moves: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that moves made by one player are reflected in real-time for others.
Collaborative Interaction: Test the responsiveness of the application by making moves and observing how the game state updates for all participants.

Summary

In this tutorial, we built a multiplayer chess game using SuperViz for real-time synchronization. We configured a React application to handle chess moves, enabling multiple players to collaborate seamlessly on a shared chessboard. This setup can be extended and customized to fit various scenarios where game interaction is required.

Feel free to explore the full code and further examples in the GitHub repository for more details.

How to add a Who-Is-Online feature on your application with JavaScript

Pachi 🥑 — Thu, 19 Sep 2024 20:27:10 +0000

Hello everyone!

Today I will share a tutorial, that will guide you through integrating a "Who-Is-Online" feature into your JavaScript application using SuperViz. This feature allows users to see who else is currently online in a shared session, which is especially useful for collaborative tools, virtual events, and social platforms.

We'll demonstrate how to set up a simple React application that uses SuperViz to display the list of online participants. By the end of this tutorial, you'll have a fully functional "Who-Is-Online" feature that you can extend and customize to meet your specific needs.

Let's get started!

Prerequisites

To follow this tutorial, you will need a SuperViz account and a developer token. If you already have an account and a developer token, you can move on to the next step.

Create an account

Retrieving a Developer Token

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate SuperViz for the "Who-Is-Online" feature.

1. Create a New React Project

First, create a new React application using Vite with TypeScript.

npm create vite@latest who-is-online -- --template react-ts
cd who-is-online

Vite is a modern build tool that provides a faster and more efficient development experience compared to Create React App. It also supports TypeScript out of the box.

2. Install Required Libraries

Next, install the necessary libraries for our project:

npm install @superviz/sdk uuid

@superviz/sdk: For integrating real-time collaboration features.
uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure tailwind

In this tutorial, we'll use the Tailwind css framework. First, install the tailwind package.

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

We then need to configure the template path.
Open tailwind.config.js in the root of the project and insert the following code.

/** @type {import('tailwindcss').Config} */ 
export default { 
content: [ 
"./index.html", 
"./src/**/*.{js,ts,jsx,tsx}", 
], 
theme: { 
extend: {}, }, 
plugins: [], 
}

Then we need to add the tailwind directives to the global CSS file. (src/index.css)

@tailwind base; 
@tailwind components; 
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.


VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and display the "Who-Is-Online" feature.

1. Implement the App Component

Open src/App.tsx and set up the main application component using SuperViz to manage the online participants list.

import { useCallback, useEffect, useRef, useState } from "react";
import SuperVizRoom, { LauncherFacade, WhoIsOnline } from '@superviz/sdk';
import { v4 as generateId } from 'uuid';

Explanation:

- Imports: Import necessary components from React, SuperViz, and UUID for managing state, initializing SuperViz, and displaying the online participants.

2. Define Constants

Define constants for the API key, room ID, and participant ID.

const apiKey = import.meta.env.VITE_SUPERVIZ_API_KEY as string;
const ROOM_ID = 'who-is-online';

Explanation:

apiKey: Retrieves the SuperViz API key from environment variables.
ROOM_ID: Defines the room ID for the SuperViz session.

3. Create the App Component

Set up the main App component and initialize the "Who-Is-Online" feature.


export  default  function  App()  {
    const  [initialized, setInitialized]  =  useState(false);
    const superviz =  useRef<LauncherFacade |  null>(null);

Explanation:

useState & useRef: Manages the initialization state and stores the SuperViz instance.

4. Initialize SuperViz

Create a function to initialize SuperViz and set up the "Who-Is-Online" feature.

const initialize = useCallback(async () => { 
 if(initialized) return; 

    superviz.current = await SuperVizRoom(apiKey, { 
    roomId: ROOM_ID, 
    participant: { 
        id: generateId(), 
            name: 'participant-name', 
        }, 
        group: { 
            id: 'who-is-online', 
            name: 'who-is-online', 
        } 
        }); 

    const whoIsOnline = new WhoIsOnline({ 
        position: 'who-is-online', 
        disablePresenceControls: true, 
    }); 

    superviz.current.addComponent(whoIsOnline); 

    setInitialized(true); 
    }, [initialized]);

Explanation:

initialize: Initializes SuperViz, sets up the real-time component, and adds the "Who-Is-Online" feature to the application.
WhoIsOnline: Displays the list of participants currently online in the session, positioned within the specified HTML element.

5. Use Effect Hook for Initialization

Use the useEffect hook to trigger the initialize function on component mount and handle cleanup when the component is unmounted.


useEffect(() => {
  initialize();

  return () => {
    superviz.current?.destroy();
  }
}, []);

Explanation:

useEffect: Calls the initialize function once when the component mounts and cleans up the SuperViz instance when the component unmounts.

Step 3: Render the Who-Is-Online Interface

Finally, return the JSX structure for rendering the "Who-Is-Online" interface.


return  (
    <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'>
        <header className='w-full p-5 bg-purple-400 flex items-center justify-between'>
            <h2 className='text-white text-2xl font-bold'>Who is Online</h2>
        </header>
        <main className='flex-1 p-20 flex w-full gap-2 items-center justify-center'>
            <div id="who-is-online"></div>
        </main>
    </div>
);

Explanation:

Viewer Container: The who-is-online div is where the online participants list will be rendered. This is where users will see who else is online in the session.

Step 4: Understanding the Project Structure

Here's a quick overview of how the project structure supports the "Who-Is-Online" feature in a JavaScript application:

- App.tsx
- Initializes SuperViz and sets up the "Who-Is-Online" feature.
- Handles real-time updates of online participants.

- Who-Is-Online Interface

Displays a list of participants currently online in the session.
Updates dynamically as participants join or leave the session.

- Real-Time Communication
- Manages real-time communication between participants using SuperViz.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:

npm run dev

This command will start the development server and open your application in the default web browser. You can see who else is online in real-time as other participants join.

2. Test the Application

Who-Is-Online Feature: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that the list of online users updates in real-time.
Collaborative Interaction: Test the responsiveness of the application by observing how the online participants list changes as users join and leave the session.

Summary

In this tutorial, we built a "Who-Is-Online" feature using SuperViz.

We configured a React application to handle real-time updates of online participants, enabling multiple users to see who else is in the session. This setup can be extended and customized to fit various scenarios where real-time presence information is essential.

Feel free to explore the full code and further examples in the GitHub repository for more details.

How to implement real-time mouse pointers into a web-application using SuperViz React SDK

Vitor Norton — Wed, 28 Aug 2024 16:23:49 +0000

In this tutorial, we will guide you through adding real-time mouse pointers to a web application using the SuperViz React SDK. Real-time mouse pointers are essential for collaborative applications, allowing users to see each other's cursor movements and interactions on a shared screen. This feature enhances communication and collaboration, making it easier for participants to follow along with each other's actions.

We'll demonstrate how to use SuperViz to implement real-time mouse pointers in a React application. Although we’ll use a <canvas> element for rendering shared content, the real-time mouse pointers component is versatile and can be used with other HTML elements as well. This flexibility allows developers to integrate real-time pointers in a variety of web application contexts, providing a dynamic and interactive experience similar to collaborative platforms like Google Docs or Figma. Let's get started!

Prerequisite

To follow this tutorial, you will need a SuperViz account and a developer token. If you already have an account and a developer token, you can move on to the next step.

Create an Account

To create an account, go to https://dashboard.superviz.com/register and sign up using either Google or an email/password. Note that if you choose email/password, you will receive a confirmation link that you'll need to click to verify your account.

Retrieving a Developer Token

To use the SDK, you’ll need a developer token, which is essential for associating SDK requests with your account. You can retrieve both development and production SuperViz tokens from the the dashboard.

Copy and save the developer token, as you will need it in the next steps of this tutorial.

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate the SuperViz SDK for real-time mouse pointers.

1. Create a New React Project

First, create a new React application using Create React App with TypeScript.

npm create vite@latest mouse-pointers-demo -- --template react-ts
cd mouse-pointers-demo

2. Install SuperViz SDK

Next, install SuperViz, which will enable us to add real-time mouse pointer features to our application.

npm install @superviz/react-sdk uuid

@superviz/react-sdk: SDK for integrating real-time collaboration features, including mouse pointers.
uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Configure Tailwind

In this tutorial, we'll use the Tailwind CSS framework. First, install the Tailwind package.

npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

We then need to configure the template path. Open tailwind.config.js in the root of the project and insert the following code.

/** @type {import('tailwindcss').Config} */
export default {
  content: [
    "./index.html",
    "./src/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Then we need to add the tailwind directives to the global CSS file the src/index.css.

@tailwind base;
@tailwind components;
@tailwind utilities;

4. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key. This key will be used to authenticate your application with SuperViz services.

VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and handle real-time mouse pointers.

1. Implement the App Component

Open src/App.tsx and set up the main application component using the SuperVizRoomProvider to manage the collaborative environment.

import { SuperVizRoomProvider } from '@superviz/react-sdk'
import { v4 as generateId } from 'uuid'
import Room from './Room'

const developerKey = import.meta.env.VITE_SUPERVIZ_API_KEY;
const participantId = generateId()

export default function App() {
  return (
    <SuperVizRoomProvider
      developerKey={developerKey}
      group={{
        id: 'realtime-mouse-pointers',
        name: 'realtime-mouse-pointers',
      }}
      participant={{
        id: participantId,
        name: 'Participant',
      }}
      roomId='realtime-mouse-pointers'
    >
      <Room />
    </SuperVizRoomProvider>
  )
}

Explanation:

SuperVizRoomProvider: This component wraps the application to enable real-time features and provides configuration for group and participant details.
developerKey: Retrieves the developer key from environment variables to authenticate with SuperViz.
participantId: Generates a unique ID for each participant using the uuid library.
Room Component: Contains the logic for rendering the canvas and handling mouse pointers.

2. Implement the Room Component

Create a new file named src/Room.tsx and add the following implementation:

import { MousePointers } from "@superviz/react-sdk";

export default function Room() {
  return (
    <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'>
      <header className='w-full p-5 bg-purple-400 flex items-center justify-between'>
        <h2 className='text-white text-2xl font-bold'>SuperViz Real-Time Mouse Pointers</h2>
      </header>
      <main className='flex-1 w-full h-full'>
        <div className='w-full h-full'>
          <canvas id="canvas" className='w-full h-full'></canvas>
        </div>

        <MousePointers elementId="canvas" />
      </main>
    </div>
  )
}

Explanation:

MousePointers Component: Displays the real-time location of each participant's mouse cursor on the canvas, allowing users to see where others are interacting.
elementId: Specifies the ID of the element (canvas) where the mouse pointers will be shown. The component can also be used with other HTML elements such as div or svg, offering flexibility in its application.
Canvas Element: A <canvas> element is used to render the shared content, with an ID that matches the elementId specified in MousePointers.

Step 3: Understanding the Project Structure

Here's a quick overview of how the project structure supports real-time mouse pointers:

App.tsx
- Initializes the SuperViz environment.
- Sets up participant information and room details.
- Renders the Room component within the SuperVizRoomProvider.
Room.tsx
- Contains the main UI elements, including the canvas.
- Integrates the MousePointers component to show real-time cursor movements.

Step 4: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:

npm run dev

This command will start the development server and open your application in the default web browser. You can interact with the canvas and see mouse pointers in real-time as other participants join the session.

2. Test the Application

Real-Time Mouse Pointers: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that mouse movements are displayed in real-time for all users.
Collaborative Interaction: Test the responsiveness of the application by moving the mouse around the canvas and observing the pointers of other participants.

Summary

In this tutorial, we implemented real-time mouse pointers in a web application using SuperViz and React. We configured a React application to display mouse pointers for all participants, enabling seamless collaboration and interaction. This setup can be extended and customized to fit various scenarios where real-time collaboration and visual feedback are required.

Feel free to explore the full code and further examples in the GitHub repository for more details.

How to integrate Contextual Comments into Matterport SDK

Vitor Norton — Mon, 19 Aug 2024 15:12:36 +0000

In this tutorial, we will guide you through adding contextual comments to a Matterport SDK application using SuperViz. Contextual comments enable users to leave feedback directly within a 3D model, making it easier to collaborate on design reviews, walkthroughs, and virtual tours. This feature is particularly useful in scenarios where precise feedback within a spatial context is critical.

We'll demonstrate how to integrate SuperViz with Matterport, allowing participants to add and view comments within the 3D environment in real-time. By the end of this tutorial, you'll have a fully functional Matterport application with a robust commenting system that enhances collaboration and communication.

Let's get started!

Prerequisite

To follow this tutorial, you will need a SuperViz account and a developer token. If you already have an account and a developer token, you can move on to the next step.

Create an Account

Retrieving a Developer Token

Copy and save the developer token, as you will need it in the next steps of this tutorial.

Step 1: Set Up Your React Application

To begin, you'll need to set up a new React project where we will integrate SuperViz and the Matterport SDK.

1. Create a New React Project

First, create a new React application using Create React App with TypeScript.

npm create vite@latest matterport-comments -- --template react-ts
cd matterport-comments

2. Install Required Libraries

Next, install the necessary libraries for our project:

npm install @superviz/sdk @superviz/matterport-plugin uuid

@superviz/sdk: For integrating real-time collaboration features, including comments.
@superviz/matterport-plugin: Plugin for adding SuperViz interaction features to a Matterport Viewer.
uuid: A library for generating unique identifiers, useful for creating unique participant IDs.

3. Set Up Environment Variables

Create a .env file in your project root and add your SuperViz developer key and Matterport application key. These credentials will be used to authenticate your application with SuperViz and Matterport services.

VITE_SUPERVIZ_API_KEY=YOUR_SUPERVIZ_DEVELOPER_KEY
VITE_MATTERPORT_KEY=YOUR_MATTERPORT_KEY

Step 2: Implement the Main Application

In this step, we'll implement the main application logic to initialize SuperViz and the Matterport Viewer, and handle real-time contextual comments.

1. Implement the App Component

Open src/App.tsx and set up the main application component using SuperViz to manage the collaborative environment.

import { v4 as generateId } from 'uuid';
import { useCallback, useEffect, useRef } from "react";
import SuperVizRoom, { Comments } from '@superviz/sdk';
import { MatterportPin } from '@superviz/matterport-plugin';
import type { MpSdk } from '@superviz/matterport-plugin/dist/common/types/matterport.types.d.ts';

Explanation:

Imports: Import necessary components from React, SuperViz, Matterport Plugin, and UUID for managing state, initializing SuperViz, and enabling contextual comments within the Matterport SDK.

2. Define Constants

Define constants for the API key, Matterport key, and room ID.

const apiKey = import.meta.env.VITE_SUPERVIZ_API_KEY as string;
const matterportKey = import.meta.env.VITE_MATTERPORT_KEY as string;

const ROOM_ID = 'matterport-comments';
const PLAYER_ID = generateId();

Explanation:

apiKey & matterportKey: Retrieves the SuperViz and Matterport API keys from environment variables.
ROOM_ID & PLAYER_ID: Defines the room ID for the SuperViz session and generates a unique player ID.

3. Create the App Component

Set up the main App component and initialize references for the Matterport SDK.

export default function App() {
  const matterportSDK = useRef<MpSdk | null>(null);

  useEffect(() => {
    initializeMatterport();
  }, []);
}

Explanation:

matterportSDK: A ref to store the Matterport SDK instance.
useEffect: Calls the initializeMatterport function once when the component mounts, setting up the Matterport Viewer.

4. Initialize SuperViz

Create a function to initialize SuperViz and integrate the contextual commenting system.

const initializeSuperViz = useCallback(async () => {
  const superviz = await SuperVizRoom(apiKey, {
    roomId: ROOM_ID,
    participant: {
      id: PLAYER_ID,
      name: 'player-name',
    },
    group: {
      id: 'matterport-comments',
      name: 'matterport-comments',
    }
  });

  const pinAdapter = new MatterportPin(matterportSDK.current!, document.getElementById('showcase')!);
  const comments = new Comments(pinAdapter, {
    buttonLocation: 'top-right',
  });
  superviz.addComponent(comments);
}, []);

Explanation:

initializeSuperViz: An asynchronous function that initializes SuperViz and adds the contextual comments component to the Matterport Viewer.
MatterportPin: Adapts the Matterport SDK to work with SuperViz's commenting system, allowing users to pin comments directly in the 3D space.

5. Initialize Matterport Viewer

Create a function to initialize the Matterport Viewer with the necessary credentials and configurations.

const initializeMatterport = useCallback(async () => {
  const showcase = document.getElementById('showcase') as MatterportIframe;
  const showcaseWindow = showcase.contentWindow as MatterportIframe['window'];
  const source = \`/vendor/matterport/showcase.html?&play=1&qs=1&applicationKey=\${matterportKey}&m=Zh14WDtkjdC\`;
  showcase.setAttribute('src', source);

  await new Promise((resolve) => {
    showcase.addEventListener('load', async () => {
      matterportSDK.current = await showcaseWindow?.MP_SDK.connect(showcaseWindow, matterportKey);
      resolve(matterportSDK.current);
    });
  });

  initializeSuperViz();
}, [initializeSuperViz]);

Explanation:

initializeMatterport: Loads the Matterport Viewer in an iframe, connects the Matterport SDK, and then initializes SuperViz for real-time collaboration and commenting.

Step 3: Render the Application

Finally, return the JSX structure for rendering the Matterport Viewer and the SuperViz-powered interface.

return (
  <div className='w-full h-full bg-gray-200 flex items-center justify-center flex-col'>
    <header className='w-full p-5 bg-purple-400 flex items-center justify-between'>
      <h2 className='text-white text-2xl font-bold'>SuperViz Matterport Comments</h2>
    </header>
    <main className='w-full h-full flex items-center justify-center relative'>
      <iframe id='showcase' className='w-full h-full' />
    </main>
  </div>
);

Explanation:

Viewer Container: The showcase iframe is where the Matterport Viewer will be rendered, filling the entire screen. This is where users will interact with the 3D space and collaborate in real time with contextual comments.

Step 4: Understanding the Project Structure

Here's a quick overview of how the project structure supports adding contextual comments to a Matterport SDK application:

App.tsx
- Initializes SuperViz.
- Sets up the Matterport Viewer with real-time commenting features.
- Handles the loading of 3D spaces and integration of collaborative tools.
Matterport Viewer
- Renders the 3D space, allowing users to navigate, inspect, and leave comments in a shared virtual environment.
SuperViz Components
- MatterportPin & Comments: Enables users to pin comments to specific locations in the 3D model, enhancing collaborative review sessions.

Step 5: Running the Application

1. Start the React Application

To run your application, use the following command in your project directory:

npm start

This command will start the development server and open your application in the default web browser. You can interact with the 3D space and see real-time comments from other participants.

2. Test the Application

Contextual Comments: Open the application in multiple browser windows or tabs to simulate multiple participants and verify that comments are updated in real-time.
Collaborative Interaction: Test the commenting feature by adding comments to the 3D model and observing how they appear for other participants.

Summary

In this tutorial, we integrated contextual comments into a Matterport SDK application using SuperViz. We configured a React application to handle 3D space navigation and commenting, enabling multiple users to collaborate seamlessly within a shared virtual environment. This setup can be extended and customized to fit various scenarios where real-time collaboration on 3D spaces is required.

Feel free to explore the full code and further examples in the GitHub repository for more details.

What is channels and the benefits of using it when working with events

Vitor Norton — Thu, 15 Aug 2024 12:15:02 +0000

Event handling is a critical aspect of any application development process. It allows applications to respond to user interactions or system occurrences by executing specific sets of code. There are various ways to manage these events, but one effective method is through the use of channels. Within this blog post, I will explore what channels are and the benefits they offer when working with events.

What are Channels?

Channels are a communication mechanism used in concurrent programming for passing data between different parts of a software system. They are essentially pipelines through which you can send and receive values with the channel operator.

Channels provide a way for different routines, threads, or processes to communicate and synchronize. The major concept is that data can flow from one end of the channel to another, enabling different parts of a system to communicate seamlessly.

Why Use Multiple Channels?

While it's possible to use just one channel in your application, there are several reasons for using multiple channels.

One of the main reasons is to keep your application organized and maintainable. Each channel can be dedicated to a specific type of event or interaction, making it easier to manage and debug the application. For example, one channel could handle user interface events, another could handle a chat application, and so on. This separation of concerns makes your application more modular and easier to understand.

Another reason to use multiple channels is to increase the efficiency of your application. Different channels can be processed in parallel, which can lead to performance improvements, especially in multi-core or multi-threaded environments. In contrast, if all events are sent through a single channel, they would have to be processed one after another, which could lead to bottlenecks and reduce the responsiveness of your application.

Lastly, using multiple channels can help prevent data loss. If a single channel is overwhelmed with too many events, it may start dropping events or crash altogether. By spreading the load across multiple channels, you can help ensure that all events are processed successfully.

However, it's important to note that using multiple channels also comes with its own challenges, such as coordinating between different channels and managing concurrency issues. Therefore, it's crucial to design your application carefully and choose the right number of channels based on your specific needs.

What It Looks Like

The code snippet provided below showcases an example of how channels can be used in a real-life setting.

import { Realtime } from "@superviz/sdk";

const realtime = new Realtime();

const uxChannel = realtime.connect('ux');
const chatChannel = realtime.connect('chat');

const buttonClicked = { id: "#buttonId" }
uxChannel.publish("handle.click", buttonClicked);

const connection = { message: "Olá mundo" }
chatChannel.publish("handle.newMessage", connection );

In this scenario, two separate channels are created for handling different types of events - one for User Experience (UX) events and another for chat events. These events are then published to their respective channels, demonstrating how tasks can be effectively segregated and managed using multiple channels.

Channels and SuperViz

We recently introduced the multi-channel feature to our Real-Time Data Engine. It has significantly improved how we handle events on our SuperViz platform.

Now, it is possible to dedicate different channels for different types of events, increasing the efficiency and organization of your application. In addition, the ability to process channels in parallel allows for better performance, especially in multi-core or multi-threaded environments.

Super Hackathon Invitation - Win $5.000

So, while you are here, let me invite you to participate in our upcoming Super Hackathon this August!

From Aug 9-31, you'll be challenge to transform your virtual interactions with SuperViz’s real-time communication and data synchronization platform and a chance to win a prize of $5,000.