아우라베이스 로고
아우라베이스문서
문서›가이드›Realtime and presence (SDK)

JavaScript SDK를 사용하여 실시간 메시지 및 현재 상태 보내기

실행 중인 스택에 대해 관찰된 각 호출의 동작을 포함하는 aura.realtime의 일상적인 흐름입니다.

7분 읽기·레벨 중급·2026. 10. 12.에 개정됨
이 영어 텍스트는 프랑스어 원본에서 자동으로 생성되었으며 아직 검토되지 않았습니다.
이 번역 이후 영어 소스가 변경되었습니다. 일부 정보는 최신 정보가 아닐 수 있습니다.
이 페이지는 자동으로 번역되었습니다. 영어 버전은 권위가 있습니다.
#
채널

1. 채널 및 채널 현황

채널은 이름이 지정된 방입니다. 같은 이름을 여는 클라이언트는 서로의 메시지를 받습니다. 구독하면 클라이언트가 자체적으로 연결됩니다.

channel.tstypescript
const room = aura.realtime.channel('room-1')

room.subscribe((status) => {
  // '구독' | '채널_오류' | 'TIMED_OUT' | '폐쇄'
  if (status === 'SUBSCRIBED') console.log('ready')
})

SUBSCRIBED이후에만 보냅니다. 그 전이나 거부 후 send()는 보내는 대신 not_connected 또는 requires_subscription와 같은 상태를 반환합니다. 채널의 범위는 프로젝트로 지정됩니다. 두 프로젝트는 서로 표시되지 않고 동일한 이름을 사용할 수 있습니다.

#
방송

2. 방송 메시지

broadcast.tstypescript
// 수신
room.on('broadcast', { event: 'ping' }, (message) => {
  console.log(message.payload) // { 이벤트: 'ping', n: 1, 텍스트: 'hello' }
})

// 구독 후 보내기
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → '알았어'

실제 실행에서는 로그인한 두 번째 클라이언트가 2초 이내에 메시지를 받았습니다.

페이로드는 event 키를 전달합니다.

받는 메시지에는 payload에 이벤트 이름이 추가됩니다: { "event": "ping", "n": 1, … }. 자체 event 키가 있는 페이로드는 거부됩니다(channel.send는 'invalid_payload'를, httpBroadcast는 realtime_payload_event_reserved를 반환). 키 이름을 바꾸세요(예: kind).

  • 기본적으로 자신의 메시지를 받지 않습니다. { config: { broadcast: { self: true } } }로 채널을 열어서 받으세요.
  • 메시지에는 id, topic, timestamp, event 및 payload이 포함됩니다.
#
존재

3. 존재감

현재 상태는 선택한 상태에 따라 채널에 연결된 사람을 보여줍니다.

presence.tstypescript
const lobby = aura.realtime.channel('lobby', { config: { presence: { key: user.id } } })

lobby.on('presence', { event: 'sync' }, () => {
  console.log(lobby.presenceState())
})
lobby.subscribe(async (status) => {
  if (status === 'SUBSCRIBED') await lobby.track({ name: 'Bob' })
})

presenceState()는 사용자 ID로 입력됩니다. 각 항목에는 사용자의 연결이 나열됩니다.

presenceState()json
{
  "d6ba3994-…": [
    { "client_id": "936cb015-…", "user_id": "d6ba3994-…", "metadata": { "name": "Bob" },
      "joined_at": "2026-10-12T19:32:19.093Z", "last_seen": "2026-10-12T19:32:19.096Z" }
  ]
}

untrack()은(는) 목록에서 귀하를 제거하며, 채널을 떠나거나 페이지를 닫으면 자동으로 처리됩니다.

#
변경 사항

4. 데이터베이스 변경

자체 데이터베이스가 있는 프로젝트

postgres_changes는 자체 데이터베이스가 있는 프로젝트에서 작동합니다. 먼저 각 테이블을 활성화하세요: PUT /v1/db/{project_id}/schema/tables/{table}/realtime에 본문 {"enabled": true}와 service_role 키를 사용합니다. 수신은 첫 번째 클라이언트가 구독할 때 시작되고 마지막 클라이언트가 떠난 뒤 몇 분 후에 멈춥니다. 전달은 최소 한 번입니다. 서버가 재시작된 뒤 같은 변경이 두 번 도착할 수 있으므로 핸들러를 멱등하게 만드세요(예: 행의 기본 키를 기준으로 처리). 사용량이 많은 클러스터는 용량 오류로 새 수신을 거부할 수 있으니 잠시 후 다시 시도하세요. 채널 이름은 테이블에 맞춰 db:public.<table>로 지정하세요. 변경 사항은 이 채널로 게시됩니다. 첫 구독자는 구독 직전에 이루어진 최대 5초 분량의 변경을 받을 수 있습니다. 변경 사항은 복구를 위해 1시간 보관된 뒤 삭제됩니다. 클러스터가 가득 차면 구독이 capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez 오류로 실패합니다. 수신이 1분 넘게 끊긴 상태가 계속되면 채널은 CHANNEL_ERROR 상태가 되며, 복구되면 다시 구독하세요. 1시간 보관 기간보다 긴 장애 동안의 변경 사항은 유실됩니다.

changes.tstypescript
const changes = aura.realtime
  .channel('db:public.todos')
  .on('postgres_changes', { event: '*', schema: 'public', table: 'todos' }, (payload) => {
    console.log(payload.eventType, payload.new)
  })
  .subscribe((status) => {
    if (status === 'CHANNEL_ERROR') console.warn('database changes are not available for this project')
  })
#
정리

5. 청소

cleanup.tstypescript
room.unsubscribe()                 // 채널 하나 나가기
aura.realtime.removeChannel(room)  // 떠나고 잊어버려
aura.realtime.removeAllChannels()  // 모든 채널에서 나가세요
aura.realtime.disconnect()         // 연결을 닫아

aura.realtime.onStateChange(callback) 및 onError(callback)와의 연결을 살펴보세요. 삭제 후 setAutoReconnect(false)를 호출하지 않으면 클라이언트가 자동으로 다시 연결됩니다.

마지막 업데이트 · 2026. 10. 12.