Przejdź do treści
Logo Aurabase
aurabaza

Wysyłaj wiadomości na żywo i informacje o obecności za pomocą pakietu JavaScript SDK

Codzienne przepływy aura.realtime z zachowaniem każdego wywołania obserwowanym na działającym stosie.

Przewodnik krok po kroku7 min przeczytanePoziom mediatorZmieniono 12 paź 2026

Ta strona została przetłumaczona automatycznie. Wersja angielska jest miarodajna.

Kanały i ich status#

Kanał to nazwany pokój. Klienci, którzy otworzą tę samą nazwę, otrzymają wzajemne wiadomości. Klient łączy się sam po wykupieniu subskrypcji.

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

room.subscribe((status) => {
  // „SUBSKRYBOWANO” | „BŁĄD KANAŁU” | „TIMED_OUT” | 'ZAMKNIĘTE'
  if (status === 'SUBSCRIBED') console.log('ready')
})

Wyślij dopiero po SUBSCRIBED. Przed tym lub po odmowie send() zamiast wysyłać zwraca status taki jak not_connected lub requires_subscription. Kanały są ograniczone do Twojego projektu: dwa projekty mogą używać tej samej nazwy, nie widząc się nawzajem.

Rozgłaszaj wiadomości#

broadcast.tstypescript
// Odbierać
room.on('broadcast', { event: 'ping' }, (message) => {
  console.log(message.payload) // { zdarzenie: 'ping', n: 1, tekst: 'witaj' }
})

// Wyślij po SUBSKRYBCJI
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → „ok”

W rzeczywistości drugi zalogowany klient otrzymał wiadomość w czasie krótszym niż dwie sekundy.

Ładunek zawiera klucz event

Do otrzymanej wiadomości dodano nazwę zdarzenia w postaci payload: { "event": "ping", "n": 1, … }. Ładunek posiadający własny klucz event zostaje odrzucony (channel.send zwraca 'invalid_payload', httpBroadcast zwraca realtime_payload_event_reserved): zmień nazwę klucza, na przykład kind.

  • Domyślnie nie otrzymujesz własnych wiadomości. Otwórz kanał za pomocą { config: { broadcast: { self: true } } }, aby je otrzymać.
  • Wiadomość zawiera id, topic, timestamp, event i payload.

Obecność#

Obecność pokazuje, kto jest podłączony do kanału, w wybranym przez Ciebie stanie.

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() jest wprowadzany na podstawie identyfikatora użytkownika. Każdy wpis zawiera listę połączeń użytkownika:

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() usuwa Cię z listy, a opuszczenie kanału lub zamknięcie strony robi to za Ciebie.

Zmiany w bazie danych#

Projekty z własną bazą danych

postgres_changes pracuje nad projektami z własną bazą danych. Najpierw włącz każdą tabelę: PUT /v1/db/schema/tables/{table}/realtime (lub aura db table realtime <table> on) z treścią {"enabled": true} i kluczem service_role. Słuchanie rozpoczyna się w momencie zapisania się pierwszego klienta i kończy kilka minut po wyjściu ostatniego klienta. Dostarczenie następuje co najmniej raz: po ponownym uruchomieniu serwera zmiana może nadejść dwukrotnie, dlatego należy ustawić program obsługi jako idempotentny, na przykład poprzez wpisanie klucza podstawowego wiersza. Zajęty klaster może odmówić przyjęcia nowego słuchacza z powodu błędu pojemności; spróbuj ponownie wkrótce. Działa każda nazwa kanału: table każdego filtra wybiera tabelę do odsłuchiwania, a jeden kanał może odsłuchiwać kilka tabel. Na kanale, który nie ma nazwy db:<schema>.<table>, każdy filtr potrzebuje table. Pierwszy abonent może otrzymać do 5 sekund zmian dokonanych tuż przed subskrypcją. Zmiany są przechowywane przez godzinę w celu ich odzyskania, a następnie usuwane. Gdy klaster jest pełny, subskrypcja kończy się niepowodzeniem z capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Jeśli słuchanie nie będzie trwało dłużej niż minutę, kanał zostanie przeniesiony na CHANNEL_ERROR, a po przywróceniu słuchania z powrotem na SUBSCRIBED; nie musisz ponownie subskrybować. Jeśli awaria trwa dłużej niż godzina, kanał otrzymuje również CHANNEL_ERROR z changements postgres_changes perdus pendant l'interruption, resynchronisez: ponowne załadowanie danych z bazy danych. Zmiana pozostaje taka sama id za każdym razem, gdy jest dostarczana, więc możesz także pominąć id, który już obsłużyłeś. Wiersz do usunięcia już nie istnieje, więc nie można na nim ocenić bezpieczeństwa na poziomie wiersza. W przypadku tabeli z zabezpieczeniem na poziomie wiersza DELETE jest zatem dostarczany tylko subskrybentom, których rola ma politykę SELECT w tabeli (lub omija RLS, np. service_role): gość (anon) bez polityki odczytu nie otrzymuje jej. Na stole bez zabezpieczenia na poziomie wiersza otrzymuje go każdy subskrybent. payload.old z DELETE przechowuje tylko kolumny klucza podstawowego (nic, jeśli tabela nie ma klucza podstawowego), a filtr w jakiejkolwiek innej kolumnie nigdy nie pasuje do usunięcia. W przypadku UPDATE``payload.old przechowuje również tylko kolumny klucza podstawowego z poprzedniego wiersza (ich poprzednie wartości w przypadku zmiany klucza), nigdy inne wartości: bezpieczeństwo na poziomie wiersza jest sprawdzane tylko w nowym wierszu. Filtr UPDATE dotyczy nowego wiersza. Trzymaj poufne informacje poza kluczami podstawowymi.

changes.tstypescript
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')
  })

Posprzątać#

cleanup.tstypescript
room.unsubscribe()                 // opuść jeden kanał
aura.realtime.removeChannel(room)  // wyjdź i zapomnij
aura.realtime.removeAllChannels()  // opuść każdy kanał
aura.realtime.disconnect()         // zamknij połączenie

Obejrzyj połączenie z aura.realtime.onStateChange(callback) i onError(callback). Po zrzuceniu klient sam się ponownie łączy, chyba że wywołasz setAutoReconnect(false).