JavaScript SDK を使用してライブ メッセージとプレゼンスを送信する
aura.realtimeの日常的なフローと、実行中のスタックに対して観察された各呼び出しの動作。
チャンネルとそのステータス#
チャンネルは名前付きのルームです。同じ名前を開いたクライアントは、お互いのメッセージを受信します。サブスクライブすると、クライアントは自動的に接続します。
const room = aura.realtime.channel('room-1')
room.subscribe((status) => {
// '購読済み' | 'チャンネルエラー' | 'チャンネルエラー' | 'タイムアウト' | 「閉店」
if (status === 'SUBSCRIBED') console.log('ready')
})
SUBSCRIBEDの後にのみ送信します。その前または拒否の後、send() は送信する代わりに not_connected や requires_subscription などのステータスを返します。チャネルのスコープはプロジェクトに限定されます。2 つのプロジェクトは、相互に認識することなく同じ名前を使用できます。
ブロードキャストメッセージ#
// 受信
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 番目にサインインしたクライアントが 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 は、独自のデータベースを使用してプロジェクトで動作します。最初に各テーブルを有効にします: PUT /v1/db/schema/tables/{table}/realtime (または aura db table realtime <table> on) 本体 {"enabled": true} と service_role キー。最初のクライアントがサブスクライブするとリスニングが開始され、最後のクライアントが退出してから数分後に停止します。配信は少なくとも 1 回です。サーバーの再起動後、変更は 2 回届く可能性があるため、行の主キーをキー入力するなどして、ハンドラーを冪等にします。ビジーなクラスターは、容量エラーにより新しいリスナーを拒否する可能性があります。すぐに再試行してください。任意のチャネル名が機能します。各フィルターの table はリッスンするテーブルを選択し、1 つのチャネルで複数のテーブルをリッスンできます。 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() // 1つのチャンネルを残す
aura.realtime.removeChannel(room) // 離れて忘れてください
aura.realtime.removeAllChannels() // すべてのチャンネルを離れる
aura.realtime.disconnect() // 接続を閉じる
aura.realtime.onStateChange(callback) および onError(callback)との接続を確認します。ドロップ後、 setAutoReconnect(false)を呼び出さない限り、クライアントは自動的に再接続します。