Cycle de vie d'une connexion et reconnexion

Une connexion Realtime est un seul WebSocket. Les changements de réseau, les appareils en veille et les redémarrages d'infrastructure peuvent la fermer. Le client se reconnecte automatiquement, et votre application peut afficher l'état actuel de la connexion.

Les six états

bird.connection.state dans le client navigateur, et bird.connectionState en Swift et Kotlin, vaut toujours l'un de ceux-ci (Kotlin les exprime sous forme de constantes ConnectionState, donc unavailable se lit ConnectionState.UNAVAILABLE) :

État	Signification
initialized	Le client existe et n'a pas encore ouvert de socket.
connecting	Un socket est en cours d'ouverture, ou ouvert en attente du handshake.
connected	Le handshake a abouti. La connexion possède un ID et peut s'abonner.
unavailable	La connexion a été interrompue et une reconnexion est programmée.
disconnected	Vous avez appelé disconnect(). Rien n'est programmé.
failed	Le serveur a refusé cette connexion. Le client ne réessaie pas.

Bindez state_change pour observer chaque transition, ou bindez un seul nom d'état quand un seul vous intéresse :

import { BirdRealtime } from "@messagebird/realtime";

const bird = new BirdRealtime({ appKey: "your-app-key", region: "us1" });

bird.connection.bind("state_change", ({ previous, current }) => {
  console.log(previous, "->", current);
});

bird.connection.bind("unavailable", () => showReconnectingBanner());
bird.connection.bind("connected", () => hideReconnectingBanner());

import BirdRealtime

let bird = BirdRealtime(options: .init(appKey: "your-app-key", region: "us1"))

bird.onConnectionStateChange { previous, current in
    print(previous, "->", current)
    if current == .unavailable { showReconnectingBanner() }
    if current == .connected { hideReconnectingBanner() }
}

import com.bird.realtime.BirdRealtime
import com.bird.realtime.BirdRealtimeOptions
import com.bird.realtime.ConnectionState

val bird = BirdRealtime(BirdRealtimeOptions(appKey = "your-app-key", region = "us1"))

bird.onConnectionStateChange { previous, current ->
    println("$previous -> $current")
    if (current == ConnectionState.UNAVAILABLE) showReconnectingBanner()
    if (current == ConnectionState.CONNECTED) hideReconnectingBanner()
}

Swift et Kotlin utilisent un seul observateur pour chaque transition : branchez sur current. Les handlers s'exécutent sur la main queue en Swift et sur le main looper Android en Kotlin quand il est disponible. Passez un deliveryQueue ou Executor pour utiliser un autre contexte d'exécution.

Un socket ouvert reste dans l'état connecting jusqu'à l'arrivée du handshake du serveur. Le handshake définit bird.connection.connectionId avant que l'état ne passe à connected, pour que l'autorisation puisse signer cet ID. Si le handshake omet l'ID, le client signale une erreur et ferme le socket.

Reconnexion automatique

Après une coupure imprévue, le client attend avant d'ouvrir un nouveau socket. Le délai utilise un backoff exponentiel avec jitter complet, une base d'une seconde et un plafond de 30 secondes. Chaque handshake réussi réinitialise le backoff.

Le code de fermeture détermine lequel de ces trois comportements se produit :

Code de fermeture	Comportement
4000 à 4099	Refusé. Pas de réessai, l'état passe à failed.
4200 à 4299	Réessai immédiat.
Tout le reste	L'état passe à unavailable, puis réessai avec backoff.

Les pannes réseau empruntent le chemin du backoff. Gérez les codes de refus dans votre interface, car ces échecs terminaux ne déclenchent pas de reconnexion automatique.

La vérification de connexion inactive

Un socket peut sembler ouvert après la perte de son chemin réseau. Le client envoie un ping après le délai d'inactivité, qui vaut par défaut 120 secondes sauf si le handshake fournit une autre valeur. Si aucun pong n'arrive dans le délai de pong par défaut de 30 secondes, le client ferme le socket avec un code de réessai immédiat.

Ce qui arrive à vos channels

Les abonnements appartiennent à la connexion : une coupure les supprime. Le client conserve chaque objet channel, se réabonne après le prochain état connected et garde ses handlers existants.

Le client rappelle votre authEndpoint pour chaque channel privé et de présence en utilisant le nouvel ID de connexion. Il ne peut pas réutiliser l'ancienne signature, car celle-ci inclut l'ID de connexion précédent. Après un appel signin(), le client se connecte aussi sur chaque nouvelle connexion et signale les échecs ultérieurs via signin_error.

bird.connection.bind("signin_error", ({ message }) => {
  console.warn("connection has no identity:", message);
});

bird.onSigninError { error in
    print("connection has no identity:", error.message)
}

bird.onSigninError { error ->
    println("connection has no identity: ${error.message}")
}

Pendant la reconnexion d'un channel, channel.trigger renvoie false sans envoyer l'événement client. Vérifiez channel.subscribed, ou envoyez après bird:subscription_succeeded, qui se déclenche après chaque réabonnement réussi.

const room = bird.subscribe("presence-room-1");

room.bind("bird:subscription_succeeded", ({ members }) => {
  renderMembers(members);
});

guard let room = bird.subscribe("presence-room-1") as? PresenceChannel else { return }

room.bind(BirdProtocol.Event.subscriptionSucceeded) { _ in
    renderMembers(room.members)
}

val room = bird.subscribe("presence-room-1")
if (room is PresenceChannel) {
    room.bind(BirdProtocol.Event.SUBSCRIPTION_SUCCEEDED) {
        renderMembers(room.members)
    }
}

Realtime ne rejoue pas les événements publiés pendant la déconnexion d'un client. Si une vue doit récupérer après une interruption, récupérez son état actuel lors de bird:subscription_succeeded et appliquez les événements suivants à partir de là.

Se déconnecter volontairement

bird.disconnect() ferme le socket sans programmer de reconnexion. Utilisez-le quand un client déconnecté ou inactif n'a plus besoin de données en temps réel. Le client conserve les channels, donc un appel ultérieur à bird.connect() rouvre le socket et se réabonne.

bird.disconnect(); // state: disconnected, no reconnect
bird.connect(); // reopens and re-subscribes

bird.disconnect() // state: disconnected, no reconnect
bird.connect() // reopens and re-subscribes

bird.disconnect() // state: DISCONNECTED, no reconnect
bird.connect() // reopens and re-subscribes

Sur mobile, déconnectez-vous quand la vue ou l'activité concernée s'arrête, et reconnectez-vous quand elle reprend. Les objets channel et les bindings restent disponibles.

Erreurs sur la connexion et erreurs sur un channel

Les erreurs serveur liées à un channel arrivent sur ce channel. Un abonnement refusé est le cas le plus courant, et un authorizer qui renvoie 403 apparaît ici :

room.bind("bird:subscription_error", (err) => {
  console.warn("could not join:", err);
});

room.bind(BirdProtocol.Event.subscriptionError) { error in
    print("could not join:", error ?? "")
}

room.bind(BirdProtocol.Event.SUBSCRIPTION_ERROR) { error ->
    println("could not join: $error")
}

Tout ce que le protocole n'attribue pas à un channel arrive sur la connexion :

bird.connection.bind("error", ({ code, message }) => {
  console.warn(code, message);
});

bird.onError { error in
    print(error.code ?? 0, error.message)
}

bird.onError { error ->
    println("${error.code} ${error.message}")
}

Gérer le code de fermeture 4009

Le code 4009 se trouve dans la plage sans réessai : la connexion passe à l'état failed. Vérifiez la raison pour distinguer ces situations :

Un membre déconnecté. Votre backend a appelé le disconnect API pour ce membre, et chaque connexion qu'il détenait a été fermée. Voir Fermer les connexions d'un membre.
Une connexion jamais autorisée. L'application exige des connexions autorisées et celle-ci ne s'est pas autorisée à temps. Voir Exiger des connexions autorisées.

Le client ne se reconnecte pas automatiquement : votre application décide de la suite :

bird.connection.bind("error", ({ code }) => {
  if (code === 4009) showSignedOutScreen();
});

bird.onError { error in
    if error.code == 4009 { showSignedOutScreen() }
}

bird.onError { error ->
    if (error.code == 4009) showSignedOutScreen()
}

Un état déconnecté est approprié quand l'authentification est terminée. Appeler bird.connect() lance une nouvelle connexion et répète l'autorisation : ne vous reconnectez qu'après un changement de l'état d'autorisation de l'appelant.

Étapes suivantes

Autoriser les channels est le contrat que votre backend implémente, et la requête que le client répète à chaque reconnexion.
Exiger des connexions autorisées transforme une connexion non autorisée en connexion fermée.
Fermer les connexions d'un membre explique comment une connexion est fermée volontairement avec 4009.
Vue d'ensemble de Realtime couvre les channels, les membres et les connexions en tant que modèle.

Ressources associées

Poursuivez avec la documentation, les guides et les exemples sur ce sujet. Les ressources sont en anglais.

Explorer la fonctionnalitéRealtime Suivre le parcours d'apprentissageBuild your first integration Guide d'implémentationSend your first realtime event

Essayez la pratique et obtenez un guide d'implémentation