breakout-rooms

Miro Breakout rooms

This example shows you how leverage collaborative and real-time features, including sessions and real-time events and storage.

Note: To utilize all the functionality for this app, including the timer method, you will need to be on a Starter or higher Miro plan, and authorize the app under a non-developer team.

👨🏻‍💻 App Demo

BreakoutRooms.mov

📒 Table of Contents

• Included Features
• Tools and Technologies
• Prerequisites
• Run the app locally
• Folder Structure
• License

⚙️ Included Features

• Miro Web SDK

  • miro.board.canUse() in hooks.tsx
  • miro.board.getById() in RoomConfig Component
  • miro.board.get() in hooks.tsx
  • miro.board.getUserInfo() in hooks.tsx
  • miro.board.viewport.zoomTo() in hooks.tsx
  • miro.board.deselect() in BreakoutManager Component(experimental)
  • miro.board.notifications.showError() in BreakoutManager Component
  • miro.board.notifications.showInfo() in BreakoutManager Component

• Collaborative sessions

  • miro.board.collaboration.startSession() in hooks.tsx
  • miro.board.collaboration.getSessions() in hooks.tsx
  • miro.board.collaboration.zoomTo() in hooks.tsx

• Real-time events

  • miro.board.events.on() in BreakoutManager Component
  • miro.board.events.off() in BreakoutManager Component
  • miro.board.events.broadcast() in WaitingRoom Component

• Real-time storage

  • miro.board.storage.collection() in hooks.tsx
  • miro.board.storage.collection.set() in hooks.tsx
  • miro.board.storage.collection.get() in hooks.tsx
  • miro.board.storage.collection.remove() in hooks.tsx
  • miro.board.storage.collection.onValue in hooks.tsx
  • miro.board.storage.collection.offValue in hooks.tsx

• Timer

  • miro.board.timer.get() in hooks.tsx
  • miro.board.timer.isStarted() in hooks.tsx
  • miro.board.timer.start() in hooks.tsx
  • miro.board.timer.pause() in hooks.tsx
  • miro.board.timer.stop() in hooks.tsx
  • miro.board.timer.on() in hooks.tsx
  • miro.board.timer.off() in hooks.tsx

🛠️ Tools and Technologies

• React
• TypeScript
• Vite
• Miro Design System

Note: Miro Design System can be installed from npmjs but it is internally supported only, you can use this example as guidance, but the team is working on public documentation, but with no ETA. Feel free to use Mirotone in the meanwhile.

✅ Prerequisites

• You have a Miro account.
• You're signed in to Miro.
• Your Miro account has a Developer team.
• Your development environment includes Node.js 14.13 or a later version.
• All examples use npm as a package manager and npx as a package runner.

🏃🏽‍♂️ Run the app locally

1. Run npm install to install dependencies.

2. Run npm start to start developing.
   Your URL should be similar to this example:

   http://localhost:3000
   

3. Open the app manifest editor by clicking Edit in Manifest.
   In the app manifest editor, configure the app as follows:

   • sdkUri: assign http://localhost:3000 as a value for this property.
     It defines the entry point of the app, and it corresponds to the URL of the server that the app runs on.
   • scopes: add the permission scopes that users need to grant the app when they install it.
     To enable the app to read from and write to the board, add the following permissions:
     • boards:read
     • boards:write
     • identity:read

Example of app yaml

# See https://developers.miro.com/docs/app-manifest on how to use this
appName: Breakout rooms
sdkVersion: SDK_V2
sdkUri: http://localhost:3000
scopes:
  - boards:read
  - boards:write
  - identity:read

4. Go back to your app home page, and under the Permissions section, you will see a blue button that says Install app and get OAuth token. Click that button. Then click on Add as shown in the video below. In the video we install a different app, but the process is the same regardless of the app.

⚠️ We recommend to install your app on a developer team while you are developing or testing apps.⚠️

install-app.mov

5. Go to your developer team, and open your boards.
6. Click on the app icon on the left sidebar.

🗂️ Folder structure

.
├── components
│   ├── Avatar
│   │   ├── Avatar.css
│   │   ├── Avatar.tsx
│   │   └── index.tsx
│   ├── BreakoutManager <-- Main React component displayed in the panel to facilitators
│   ├── BreakoutStarter <-- Component displayed when no rooms were configured
│   ├── RoomConfig <-- Component displayed for each configured room
│   ├── Timer <-- Timer controller component
│   ├── WaitingList <-- Component with unassigned users in the sessiin.
│   ├── WaitingRoom <-- Page displayed to participants while facilitator prepares the session.
│   ├── app.tsx <-- The app typescript entrypoint used in the panel.
│   ├── hooks.tsx <-- React hooks used in the app, including useCurrentUser, useBreakout, useTimer and some others.
│   ├── index.ts <-- The app main typescript entrypoint, rendered inside the headless iframe.
│   ├── types.ts <-- The app typescript types.
│   └── utils.ts <-- General code utilities, such as formatting and converting time in different units.
├── app.html  <-- The app content displayed in the content when user clicks on the app icon on Miro boards.
├── index.html <-- The app entry point. This is the value you assign to 'sdkUri' in the app manifest file.

🫱🏻‍🫲🏽 Contributing

If you want to contribute to this example, or any other Miro Open Source project, please review Miro's contributing guide.

🪪 License

MIT License.