La instancia Socket (lado del cliente)

Un Socket es la clase fundamental para interactuar con el servidor. Hereda la mayoría de los métodos del EventEmitter de Node.js, como emit, on, once u off.

Además de emitir y escuchar eventos, la instancia Socket tiene algunos atributos que pueden ser útiles en tu aplicación:

Socket#id

A cada nueva conexión se le asigna un identificador aleatorio de 20 caracteres.

Este identificador está sincronizado con el valor en el lado del servidor.

// lado del servidor
io.on("connection", (socket) => {
  console.log(socket.id); // x8WIv7-mJelg7on_ALbx
});

// lado del cliente
socket.on("connect", () => {
  console.log(socket.id); // x8WIv7-mJelg7on_ALbx
});

socket.on("disconnect", () => {
  console.log(socket.id); // undefined
});

precaución

Por favor nota que, a menos que la recuperación del estado de conexión esté habilitada, el atributo id es un ID efímero que no está destinado a ser usado en tu aplicación (o solo con propósitos de depuración) porque:

• este ID se regenera después de cada reconexión (por ejemplo cuando la conexión WebSocket se corta, o cuando el usuario actualiza la página)
• dos pestañas de navegador diferentes tendrán dos IDs diferentes
• no hay cola de mensajes almacenada para un ID dado en el servidor (es decir, si el cliente está desconectado, los mensajes enviados desde el servidor a este ID se pierden)

Por favor usa un ID de sesión regular en su lugar (ya sea enviado en una cookie, o almacenado en el localStorage y enviado en el payload de auth).

Ver también:

• Parte II de nuestra guía de mensajes privados
• Cómo manejar cookies

Socket#connected

Este atributo describe si el socket está actualmente conectado al servidor.

socket.on("connect", () => {
  console.log(socket.connected); // true
});

socket.on("disconnect", () => {
  console.log(socket.connected); // false
});

Socket#io

Una referencia al Manager subyacente.

socket.on("connect", () => {
  const engine = socket.io.engine;
  console.log(engine.transport.name); // en la mayoría de los casos, imprime "polling"

  engine.once("upgrade", () => {
    // se llama cuando el transporte se actualiza (es decir, de HTTP long-polling a WebSocket)
    console.log(engine.transport.name); // en la mayoría de los casos, imprime "websocket"
  });

  engine.on("packet", ({ type, data }) => {
    // se llama para cada paquete recibido
  });

  engine.on("packetCreate", ({ type, data }) => {
    // se llama para cada paquete enviado
  });

  engine.on("drain", () => {
    // se llama cuando el buffer de escritura se vacía
  });

  engine.on("close", (reason) => {
    // se llama cuando la conexión subyacente se cierra
  });
});

Ciclo de vida

Eventos

La instancia Socket emite tres eventos especiales:

• connect
• connect_error
• disconnect

consejo

Desde Socket.IO v3, la instancia Socket ya no emite ningún evento relacionado con la lógica de reconexión. Puedes escuchar los eventos en la instancia Manager directamente:

socket.io.on("reconnect_attempt", () => {
  // ...
});

socket.io.on("reconnect", () => {
  // ...
});

Más información se puede encontrar en la guía de migración.

connect

Este evento es disparado por la instancia Socket al conectarse y reconectarse.

socket.on("connect", () => {
  // ...
});

precaución

Los manejadores de eventos no deben registrarse en el manejador connect mismo, ya que se registrará un nuevo manejador cada vez que la instancia socket se reconecte:

MAL ⚠️

socket.on("connect", () => {
  socket.on("data", () => { /* ... */ });
});

BIEN 👍

socket.on("connect", () => {
  // ...
});

socket.on("data", () => { /* ... */ });

connect_error

• error <Error>

Este evento se dispara al fallar la conexión.

Razón	¿Reconexión automática?
La conexión de bajo nivel no puede establecerse (fallo temporal)	✅ SÍ
La conexión fue denegada por el servidor en una función middleware	❌ NO

El atributo socket.active indica si el socket intentará reconectarse automáticamente después de un pequeño retraso aleatorizado:

socket.on("connect_error", (error) => {
  if (socket.active) {
    // fallo temporal, el socket intentará reconectarse automáticamente
  } else {
    // la conexión fue denegada por el servidor
    // en ese caso, `socket.connect()` debe llamarse manualmente para reconectarse
    console.log(error.message);
  }
});

disconnect

• reason <string>
• details <DisconnectDetails>

Este evento se dispara al desconectarse.

socket.on("disconnect", (reason, details) => {
  // ...
});

Aquí está la lista de posibles razones:

Razón	Descripción	¿Reconexión automática?
io server disconnect	El servidor ha desconectado forzosamente el socket con socket.disconnect()	❌ NO
io client disconnect	El socket fue desconectado manualmente usando socket.disconnect()	❌ NO
ping timeout	El servidor no envió un PING dentro del rango pingInterval + pingTimeout	✅ SÍ
transport close	La conexión se cerró (ejemplo: el usuario perdió conexión, o la red cambió de WiFi a 4G)	✅ SÍ
transport error	La conexión encontró un error (ejemplo: el servidor fue detenido durante un ciclo HTTP long-polling)	✅ SÍ

El atributo socket.active indica si el socket intentará reconectarse automáticamente después de un pequeño retraso aleatorizado:

socket.on("disconnect", (reason) => {
  if (socket.active) {
    // desconexión temporal, el socket intentará reconectarse automáticamente
  } else {
    // la conexión fue cerrada forzosamente por el servidor o el cliente mismo
    // en ese caso, `socket.connect()` debe llamarse manualmente para reconectarse
    console.log(reason);
  }
});

precaución

Los siguientes nombres de eventos están reservados y no deben usarse en tu aplicación:

• connect
• connect_error
• disconnect
• disconnecting
• newListener
• removeListener

// MAL, lanzará un error
socket.emit("disconnect");

API completa

La API completa expuesta por la instancia Socket se puede encontrar aquí.