Yjs Awareness로 실시간 사용자 상태 공유하기

Awareness란?

실시간 협업 기능에서 ‘누가 접속했는지’, ‘어디를 보고 있는지’, ‘무엇을 선택하고 있는지’를 보여주는 기능입니다.

Yjs에서는 이런 기능을 Awareness라는 객체로 제공합니다.
문서 내용(Y.Text, Y.Map 등)을 동기화하는 것과는 별도로, 사용자의 위치, 상태, 선택 정보를 가볍게 공유할 수 있게 해주는 도구입니다.

• 현재 접속한 사용자 목록
• 각 사용자의 커서 위치 (마우스 좌표)
• 어떤 객체를 선택했는지
• 편집 중인지 여부 (잠금 표시 등)

Awareness는 이런 상태를 실시간으로 공유해서, 사용자 간의 존재감을 높여주는 역할을 합니다 !

 

1. 기본 구성

import * as Y from 'yjs'
import { WebsocketProvider } from 'y-websocket'

const ydoc = new Y.Doc()
const provider = new WebsocketProvider('wss://your-server.com', 'room-id', ydoc)
const awareness = provider.awareness

• WebsocketProvider에 자동으로 Awareness가 포함됨
• 클라이언트별 상태를 추적하고 브로드캐스트함
• Y.Doc: Yjs 문서 객체
• WebsocketProvider : 실시간 동기화를 위한 연결 도구
• provider.awareness : 자동으로 포함된 사용자 상태 공유 객체

-> 이제부터 awareness를 통해 사용자 상태를 주고받을 수 있습니다.

 

2. 사용자 상태 설정

awareness.setLocalState({
  user: {
    id: 'user-123',
    name: 'name',
    color: '#f87171'
  },
  cursor: {
    x: 120,
    y: 200
  },
  selection: {
    selectedObjectIds: ['obj-1', 'obj-3']
  }
})

• setLocalState()로 현재 사용자의 상태 설정
• user: 사용자 정보
• cursor: 마우스 위치
• selection: 선택한 객체 ID 목록

-> 이 정보는 WebSocket을 통해 다른 클라이언트에게 자동으로 전파됩니다.

 

3. 상태 변경 감지

awareness.on('change', ({ added, updated, removed }) => {
  const states = awareness.getStates()
  states.forEach((state, clientId) => {
    console.log(`[${clientId}] ${state.user?.name} is at (${state.cursor?.x}, ${state.cursor?.y})`)
  })
})

• change 이벤트로 추가/수정/제거 감지 가능
• 현재 전체 상태는 awareness.getStates()로 조회
• 각 사용자에게 부여된 clientId를 기준으로 상태 추적

 

4. 커서 UI 표시하기 (HTML DOM 기반)

function renderCursor(state, clientId) {
  const cursor = document.getElementById(`cursor-${clientId}`) || document.createElement('div')
  cursor.id = `cursor-${clientId}`
  cursor.className = 'cursor'
  cursor.style.left = `${state.cursor.x}px`
  cursor.style.top = `${state.cursor.y}px`
  cursor.style.backgroundColor = state.user.color
  cursor.innerText = state.user.name
  document.body.appendChild(cursor)
}

• 실시간 좌표 반영 가능
• 사용자의 마우스 위치에 따라 커서를 DOM에 표시
• 사용자별 고유 ID로 커서 요소를 생성하고 위치/색상 적용

팀원마다 다른 이름/색상의 커서가 떠다니는 협업 환경을 만들 수 있습니다.

 

5. 사용자 퇴장 처리

awareness.on('change', ({ removed }) => {
  removed.forEach(clientId => {
    document.getElementById(`cursor-${clientId}`)?.remove()
  })
})

• 사용자가 나가면 removed 목록에 ID가 포함됨
• 이때 해당 사용자의 커서도 함께 제거해야 UI가 깨끗하게 유지

 

6.  활용 예시 정리 

기능	Awareness로 구현 여부
접속 사용자 목록 표시	✅ 가능
커서 위치 실시간 표시	✅ 가능
선택한 객체 동기화	✅ 가능
편집 중인 객체 잠금 표시	✅ 가능 (확장 필요)

 

Awareness는 협업 서비스에 꼭 필요한 사용자 상태 공유 수단입니다.

단순한 커서 공유뿐 아니라, 선택 정보, 객체 잠금, 현재 편집 중 정보까지 확장 가능합니다.

앞으로 실시간 협업 기능을 만들 계획이라면, Awareness는 꼭 알아야 할 도구입니다 !