Отправляйте живые сообщения и информацию о присутствии с помощью 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) // { событие: «пинг», n: 1, текст: «привет» }
})
// Отправьте, как только ПОДПИШИТЕСЬ
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → 'ок'
В реальных условиях второй вошедший в систему клиент получил сообщение менее чем за две секунды.
В полученное сообщение к 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() кодируется идентификатором пользователя. В каждой записи перечислены соединения пользователя:
{
"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 работает над проектами со своей базой данных. Сначала включите каждую таблицу: PUT /v1/db/schema/tables/{table}/realtime (или aura db table realtime <table> on) с телом {"enabled": true} и ключом service_role. Прослушивание начинается, когда подписывается первый клиент, и прекращается через несколько минут после ухода последнего. Доставка осуществляется как минимум один раз: после перезапуска сервера изменение может поступить дважды, поэтому сделайте свой обработчик идемпотентным, например, введя первичный ключ строки. Занятый кластер может отклонить новый прослушиватель из-за ошибки емкости; повторите попытку в ближайшее время. Подойдет любое имя канала: table каждого фильтра выбирает таблицу для прослушивания, и один канал может прослушивать несколько таблиц. На канале, который не называется db:<schema>.<table>, каждому фильтру требуется table. Первый подписчик может получить до 5 секунд изменений, внесенных непосредственно перед подпиской. Изменения хранятся в течение часа для восстановления, а затем удаляются. Когда кластер заполнен, подписка завершается с ошибкой capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Если прослушивание прекращается более минуты, канал перемещается на CHANNEL_ERROR, а затем обратно на SUBSCRIBED, как только прослушивание будет восстановлено; вам не нужно подписываться снова. Если сбой превышает один час хранения, канал также получает CHANNEL_ERROR с changements postgres_changes perdus pendant l'interruption, resynchronisez: перезагрузить данные из базы данных. Изменение сохраняет один и тот же id каждый раз при доставке, поэтому вы также можете пропустить уже обработанный id. Строка удаления больше не существует, поэтому безопасность на уровне строки не может быть оценена по ней. Таким образом, в таблице с безопасностью на уровне строк DELETE доставляется только подписчикам, чья роль имеет политику SELECT в таблице (или обходит RLS, например service_role): посетитель (anon) без политики чтения не получает его. В таблице без защиты на уровне строк ее получает каждый подписчик. payload.old из DELETE содержит только столбцы первичного ключа (ничего, если таблица не имеет первичного ключа), а фильтр для любого другого столбца никогда не соответствует удалению. Для 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).