JavaScript SDK를 사용하여 실시간 메시지 및 현재 상태 보내기
실행 중인 스택에 대해 관찰된 각 호출의 동작을 포함하는 aura.realtime의 일상적인 흐름입니다.
채널 및 해당 상태#
채널은 이름이 지정된 방입니다. 같은 이름을 여는 클라이언트는 서로의 메시지를 받습니다. 구독하면 클라이언트가 자체적으로 연결됩니다.
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// '구독' | '채널_오류' | 'TIMED_OUT' | '폐쇄'
if (status === 'SUBSCRIBED') console.log('ready')
})
SUBSCRIBED이후에만 보냅니다. 그 전이나 거부 후 send()는 보내는 대신 not_connected 또는 requires_subscription와 같은 상태를 반환합니다. 채널의 범위는 프로젝트로 지정됩니다. 두 프로젝트는 서로 표시되지 않고 동일한 이름을 사용할 수 있습니다.
방송 메시지#
// 수신
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초 이내에 메시지를 받았습니다.
귀하가 받은 메시지에는 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이 포함됩니다.
존재#
현재 상태는 선택한 상태에 따라 채널에 연결된 사람을 보여줍니다.
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로 입력됩니다. 각 항목에는 사용자의 연결이 나열됩니다.
{
"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()은(는) 목록에서 귀하를 제거하며, 채널을 떠나거나 페이지를 닫으면 자동으로 처리됩니다.
데이터베이스 변경#
postgres_changes는 자체 데이터베이스가 있는 프로젝트에서 작동합니다. 먼저 각 테이블을 활성화합니다. 본문 {"enabled": true} 및 service_role 키를 사용하여 PUT /v1/db/schema/tables/{table}/realtime(또는 aura db table realtime <table> on). 청취는 첫 번째 클라이언트가 구독할 때 시작되고 마지막 클라이언트가 떠난 후 몇 분 후에 중지됩니다. 전달은 최소한 한 번입니다. 서버를 다시 시작한 후에 변경 사항이 두 번 도착할 수 있으므로 예를 들어 행의 기본 키를 입력하여 핸들러를 멱등성으로 만듭니다. 사용량이 많은 클러스터는 용량 오류로 인해 새 수신기를 거부할 수 있습니다. 잠시 후 다시 시도하세요. 모든 채널 이름이 작동합니다. 각 필터의 table는 청취할 테이블을 선택하고 하나의 채널은 여러 테이블을 청취할 수 있습니다. db:<schema>.<table>이름이 아닌 채널에서 모든 필터에는 table이 필요합니다. 첫 번째 구독자는 구독 직전에 변경된 내용을 최대 5초까지 받을 수 있습니다. 변경 사항은 복구를 위해 1시간 동안 보관된 후 삭제됩니다. 클러스터가 가득 차면 capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez로 인해 구독이 실패합니다. 청취가 1분 이상 중단되면 채널은 CHANNEL_ERROR로 이동한 다음 청취가 복원되면 SUBSCRIBED로 돌아갑니다. 다시 구독할 필요가 없습니다. 중단이 1시간 보존 기간보다 오래 지속되면 채널은 changements postgres_changes perdus pendant l'interruption, resynchronisez와 함께 CHANNEL_ERROR도 수신합니다. 데이터베이스에서 데이터를 다시 로드합니다. 변경 사항은 전달될 때마다 동일한 id을 유지하므로 이미 처리한 id을 건너뛸 수도 있습니다. 삭제된 행이 더 이상 존재하지 않으므로 행 수준 보안을 평가할 수 없습니다. 따라서 행 수준 보안이 적용된 테이블에서 DELETE는 테이블에 SELECT 정책이 있는 역할을 가진 구독자에게만 전달됩니다(또는 service_role와 같이 RLS를 우회). 읽기 정책이 없는 방문자(anon)는 이를 수신하지 않습니다. 행 수준 보안이 없는 테이블에서는 모든 구독자가 보안을 받습니다. DELETE의 payload.old에는 기본 키 열만 포함되며(테이블에 기본 키가 없는 경우 아무 것도 포함되지 않음) 다른 열의 필터는 삭제와 일치하지 않습니다. UPDATE의 경우 payload.old는 이전 행의 기본 키 열(키가 변경된 경우 이전 값)만 보유하고 다른 값은 보유하지 않습니다. 행 수준 보안은 새 행에서만 확인됩니다. UPDATE의 필터가 새 행에 적용됩니다. 기본 키에 민감한 정보를 보관하세요.
const changes = aura.realtime
.channel('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')
})
정리하다#
room.unsubscribe() // 채널 하나 나가기
aura.realtime.removeChannel(room) // 떠나고 잊어버려
aura.realtime.removeAllChannels() // 모든 채널에서 나가세요
aura.realtime.disconnect() // 연결을 닫아
aura.realtime.onStateChange(callback) 및 onError(callback)와의 연결을 살펴보세요. 삭제 후 setAutoReconnect(false)를 호출하지 않으면 클라이언트가 자동으로 다시 연결됩니다.