Logo Aurabase
aurabasedocuments
documents›Guides›Realtime and presence (SDK)

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.

7 min de lecture·Niveau intermédiaire·Révisé le 12 oct. 2026
Ce texte anglais a été généré automatiquement à partir de l’original français et n’a pas encore été relu.
La source anglaise a changé depuis cette traduction. Certaines informations peuvent être en retard.
Cette page a été traduite automatiquement. La version anglaise fait foi.
#
Canaux

1. 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.

#
Diffusion

2. 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 reçu contient le nom de l’événement ajouté au payload : { "event": "ping", "n": 1, … }. Un payload qui porte lui-même une clé event est refusé (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

3. 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.

#
Changements

4. Modifications de la base de données

Projets avec leur propre base de données

postgres_changes fonctionne sur les projets qui ont leur propre base de données. Activez d’abord chaque table : PUT /v1/db/{project_id}/schema/tables/{table}/realtime avec le corps {"enabled": true} et une clé service_role. L’écoute démarre quand le premier client s’abonne et s’arrête quelques minutes après le départ du dernier. La livraison est au moins une fois : après un redémarrage du serveur, un changement peut arriver deux fois ; rendez donc votre traitement idempotent, par exemple en vous appuyant sur la clé primaire de la ligne. Un cluster chargé peut refuser une nouvelle écoute avec une erreur de capacité ; réessayez un peu plus tard. Nommez le canal d’après la table, db:public.<table> : c’est sur ce canal que les changements sont publiés. Le premier abonné peut recevoir jusqu’à 5 secondes de changements faits juste avant son abonnement. Les changements sont conservés une heure pour la reprise, puis supprimés. Quand 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 perdue plus d’une minute, le canal passe en CHANNEL_ERROR ; réabonnez-vous une fois l’écoute rétablie. Une panne plus longue que l’heure de rétention perd les changements faits pendant celle-ci.

changes.tstypescript
const changes = aura.realtime
  .channel('db:public.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')
  })
#
Nettoyage

5. 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).

Dernière mise à jour · 12 oct. 2026