Aller au contenu
Logo Aurabase
aurabase

Envoyez des messages en direct et une présence avec le SDK JavaScript

Les flux quotidiens de aura.realtime, avec le comportement de chaque appel observé sur une pile en cours d'exécution.

Guide pratique7 min de lectureNiveau intermédiaireRévisé le 12 oct. 2026

Cette page a été traduite automatiquement. La version anglaise fait foi.

Chaînes et leur statut#

Un canal est une pièce nommée. Les clients qui ouvrent le même nom reçoivent les messages des autres. Le client se connecte tout seul lors de votre inscription.

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

room.subscribe((status) => {
  // 'ABONNE' | 'CANAL_ERREUR' | 'TIMED_OUT' | 'FERMÉ'
  if (status === 'SUBSCRIBED') console.log('ready')
})

Envoyez uniquement après SUBSCRIBED. Avant cela, ou après un refus, send() renvoie un statut tel que not_connected ou requires_subscription au lieu d'envoyer. Les chaînes sont limitées à votre projet : deux projets peuvent utiliser le même nom sans se voir.

Messages diffusés#

broadcast.tstypescript
// Recevoir
room.on('broadcast', { event: 'ping' }, (message) => {
  console.log(message.payload) // { événement : 'ping', n : 1, texte : 'bonjour' }
})

// Envoyer, une fois INSCRIT
const status = await room.send({ type: 'broadcast', event: 'ping', payload: { n: 1, text: 'hello' } })
// → 'd'accord'

Lors d'une exécution réelle, un deuxième client connecté a reçu le message en moins de deux secondes.

La charge utile porte une clé event

Le message que vous recevez contient le nom de l'événement ajouté à payload: { "event": "ping", "n": 1, … }. Une charge utile qui possède sa propre clé event est refusée (channel.send renvoie 'invalid_payload', httpBroadcast renvoie realtime_payload_event_reserved) : renommez la clé, par exemple kind.

  • Vous ne recevez pas vos propres messages par défaut. Ouvrez la chaîne avec { config: { broadcast: { self: true } } } pour les recevoir.
  • Un message transporte id, topic, timestamp, event et payload.

Présence#

La présence indique qui est connecté à un canal, avec un état que vous choisissez.

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() est saisi par identifiant utilisateur. Chaque entrée répertorie les connexions de l'utilisateur :

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() vous supprime de la liste et quitter la chaîne ou fermer la page le fait à votre place.

Modifications de la base de données#

Projets avec leur propre base de données

postgres_changes travaille sur des projets avec leur propre base de données. Activez d'abord chaque table : PUT /v1/db/schema/tables/{table}/realtime (ou aura db table realtime <table> on) avec le corps {"enabled": true} et une clé service_role. L'écoute démarre dès l'inscription du premier client et s'arrête quelques minutes après le départ du dernier. La livraison s'effectue au moins une fois : après un redémarrage du serveur, une modification peut arriver deux fois, rendez donc votre gestionnaire idempotent, par exemple en saisissant la clé primaire de la ligne. Un cluster occupé peut refuser un nouvel écouteur avec une erreur de capacité ; réessayez sous peu. N'importe quel nom de chaîne fonctionne : le table de chaque filtre sélectionne la table à écouter, et une chaîne peut écouter plusieurs tables. Sur un canal qui n'est pas nommé db:<schema>.<table>, chaque filtre a besoin d'un table. Le premier abonné peut recevoir jusqu'à 5 secondes des modifications effectuées juste avant sa souscription. Les modifications sont conservées une heure pour être récupérées, puis supprimées. Lorsque le cluster est plein, l'abonnement échoue avec capacité d'écoute postgres_changes atteinte pour la base de ce projet, réessayez. Si l'écoute reste coupée pendant plus d'une minute, la chaîne passe à CHANNEL_ERROR, puis revient à SUBSCRIBED une fois l'écoute rétablie ; vous n'avez pas besoin de vous abonner à nouveau. Si une panne dépasse la rétention d'une heure, le canal reçoit également CHANNEL_ERROR avec changements postgres_changes perdus pendant l'interruption, resynchronisez: rechargez les données de la base de données. Une modification conserve le même id à chaque fois qu'elle est livrée, vous pouvez donc également ignorer un id que vous avez déjà traité. La ligne d'une suppression n'existe plus, la sécurité au niveau de la ligne ne peut donc pas y être évaluée. Sur une table avec une sécurité au niveau des lignes, un DELETE est donc délivré uniquement aux abonnés dont le rôle a une politique SELECT sur la table (ou contourne RLS, comme service_role) : un visiteur (anon) sans politique de lecture ne le reçoit pas. Sur une table sans sécurité au niveau des lignes, chaque abonné le reçoit. payload.old d'un DELETE ne contient que les colonnes de clé primaire (rien si la table n'a pas de clé primaire), et un filtre sur une autre colonne ne correspond jamais à une suppression. Pour un UPDATE, payload.old ne contient également que les colonnes de clé primaire de la ligne précédente (leurs valeurs précédentes si la clé a changé), jamais ses autres valeurs : la sécurité au niveau de la ligne est vérifiée uniquement sur la nouvelle ligne. Le filtre d'un UPDATE s'applique à la nouvelle ligne. Gardez les informations sensibles hors des clés primaires.

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')
  })

Nettoyer#

cleanup.tstypescript
room.unsubscribe()                 // laisser une chaîne
aura.realtime.removeChannel(room)  // pars et oublie ça
aura.realtime.removeAllChannels()  // quitter toutes les chaînes
aura.realtime.disconnect()         // fermer la connexion

Surveillez la connexion avec aura.realtime.onStateChange(callback) et onError(callback). Après une chute, le client se reconnecte tout seul sauf si vous appelez setAutoReconnect(false).