Skip to main content
Estás viendo la documentación para desarrolladores
Esta documentación es para desarrolladores que trabajan con la plataforma para desarrolladores de Base44.
Un actor es un proceso de backend de larga duración al que se conectan varios clientes simultáneamente. Con los actores, puedes crear instancias de sesión en vivo que admiten la siguiente funcionalidad:
  • Mensajería en tiempo real: Envía y recibe mensajes con los clientes a través de WebSockets.
  • Almacenamiento persistente: Mantén el estado de la sesión entre periodos de inactividad.
  • Trabajo programado: Ejecuta lógica en un intervalo fijo o a una hora concreta.
Usa actores cuando crees funciones en las que varios clientes necesitan actualizaciones e interacción en tiempo real, como una sala de chat o un juego multijugador.

​
Actores

Actor es la clase que extiendes en tu backend. La clase del actor define el comportamiento de una sesión en vivo. Con los actores, puedes:
  • Gestionar conexiones: Acepta o rechaza a un cliente que se conecta a la sesión e identifica quién se conecta.
  • Gestionar mensajes: Recibe un mensaje de un cliente, actualiza el estado de la sesión y responde a un cliente o difunde a todos.
  • Programar trabajo: Ejecuta lógica en un intervalo o a una hora programada.

​
Sesiones

Una sesión es una instancia en ejecución de un actor, identificada por el nombre del actor y un ID de sesión que tú eliges.
Cada sesión gestiona su propio estado, almacenamiento y conexiones de clientes de forma independiente.

​
Conexiones

Una conexión representa el WebSocket de un cliente a una sesión. Cada cliente que se une obtiene una conexión única. Un actor usa esa conexión para identificar quién se conecta, gestionar las conexiones de clientes y enviar mensajes. Para más información, consulta conexiones. Para ver un flujo de ejemplo, consulta gestionar las conexiones de clientes.

​
Sesiones activas e inactivas

Una sesión siempre está en uno de los siguientes estados:
  • Activa: La sesión está en vivo y procesando eventos. Una sesión se activa cuando un cliente se conecta, cuando un cliente envía un mensaje a una sesión inactiva o cuando llega una hora de despertar programada.
  • Inactiva: La sesión no está procesando eventos. Una sesión pasa a estar inactiva poco después de terminar su último mensaje y cuando se detiene todo el trabajo programado. La sesión mantiene sus datos almacenados, sus horas programadas y sus conexiones abiertas hasta que vuelve a activarse.
Cuando una sesión pasa a estar inactiva, los clientes con conexiones abiertas siguen conectados. Su siguiente mensaje o un despertar programado vuelve a activar la sesión.

​
Cliente

Usa base44.actors en el SDK de JavaScript para conectar un cliente a una sesión de actor e intercambiar mensajes. El SDK de actores admite la siguiente funcionalidad:
  • Conectar: Abre una conexión WebSocket a una sesión.
  • Suscribirse: Recibe mensajes del actor.
  • Enviar: Envía mensajes al actor.
  • Cerrar: Cierra la conexión WebSocket con el actor.
Para más información, consulta conectar un cliente a una sesión.

​
Cómo interactúan los actores y los clientes

El siguiente diagrama muestra la interacción general entre un cliente y un actor:
  1. El cliente se conecta al actor a través de un WebSocket.
  2. La sesión se activa. handleStart() se ejecuta en el primer inicio y cada vez que la sesión se activa desde el estado inactivo.
  3. El actor gestiona la conexión. Puedes comprobar la identidad del cliente y rechazar la conexión, o enviar el estado actual.
  4. El cliente envía un mensaje.
  5. El actor gestiona el mensaje. Puedes validar el formato y los permisos del remitente antes de cambiar el estado de la sesión.
  6. El actor difunde la actualización a todos los clientes conectados, o responde solo al remitente.
  7. El cliente cierra la conexión.
  8. El actor gestiona la desconexión. Puedes eliminar el estado por conexión.

​
Mensajes en tiempo real

Cada cliente conectado pertenece a una sesión y puede enviar mensajes en tiempo real a través de WebSockets. Los clientes también pueden escuchar los mensajes entrantes con subscribe().
Base44 ofrece varias funciones en tiempo real que usan un listener basado en suscripciones:
  • subscribe() de los actores escucha los mensajes que el actor envía a los clientes conectados.
  • subscribe() de las entidades escucha los cambios en las entidades de la app.
Comprueba qué servicio usas para recibir los eventos que esperas.
Con los mensajes en tiempo real, puedes:
  • Responder a un cliente concreto.
  • Difundir a todos los clientes conectados.
  • Listar los clientes que están conectados actualmente.
  • Identificar a cada cliente y comprobar si ha iniciado sesión.
Para más información, consulta conexiones. Para ver un flujo de ejemplo, consulta gestionar las conexiones de clientes.

​
Tipos de mensajes

Un cliente y un actor intercambian mensajes a través de una conexión. Los mensajes se dividen en los siguientes tipos:
  • Mensajes entrantes: Lo que un cliente conectado envía al actor, como un texto, un movimiento o un voto. El cliente los envía con send(), y el actor los recibe en handleMessage().
  • Mensajes salientes: Lo que el actor envía a los clientes conectados, como una respuesta a un cliente, una difusión a todos los clientes conectados o el tablero actual cuando alguien se une. El actor los envía con conn.send() o broadcast(), y el cliente los recibe en un callback de subscribe().
Te recomendamos tipar tus mensajes para que el actor y el cliente coincidan en la forma de cada mensaje:
  • Backend: Pasa los tipos Incoming y Outgoing como genéricos a la clase Actor. Para ver un ejemplo completo, consulta crear un actor.
  • Cliente: Extiende la interfaz ActorRegistry con las mismas formas, para que TypeScript compruebe los tipos de send() y subscribe().

​
Almacenamiento

Los actores ofrecen varias opciones de almacenamiento según cómo use y conserve los datos tu sesión:
  • Almacenamiento en memoria: Estado de trabajo que vive en campos de clase mientras la sesión está activa y se reinicia cuando la sesión pasa a estar inactiva.
  • Almacenamiento persistente: Un almacén clave-valor para datos que deben sobrevivir cuando la sesión pasa a estar inactiva.

​
Almacenamiento en memoria

Los campos de clase contienen el estado de trabajo mientras la sesión está activa, como el tablero actual o un temporizador de ronda. Usa el almacenamiento en memoria cuando tus datos cambian con frecuencia y no necesitan conservarse cuando la sesión pasa a estar inactiva, como una puntuación en vivo o la posición de un cursor. Cuando una sesión pasa a estar inactiva, los campos de clase se reinician.

​
Almacenamiento persistente

Cada sesión tiene su propio almacén clave-valor que puedes gestionar por completo. Usa el almacenamiento persistente cuando tus datos deben sobrevivir cuando la sesión pasa a estar inactiva, como el historial de un chat o el tablero de un juego. Para almacenar datos disponibles en toda la app, usa entidades. Para más información sobre el almacenamiento de actores, consulta almacenamiento.

​
Restaurar el estado

Cuando una sesión pasa a estar inactiva, el estado en memoria se reinicia. El almacenamiento persistente sobrevive, pero la sesión no vuelve a cargar automáticamente los datos almacenados en memoria cuando se activa. Usa handleStart() para restaurar los datos persistentes, como el historial del chat o el tablero del juego. Para ver un flujo de ejemplo, consulta conservar los datos de sesión.

​
Trabajo programado

Los actores permiten que una sesión ejecute lógica según una programación, independientemente de los mensajes de los clientes:
  • Ticks: Ejecutan código en un intervalo y mantienen la sesión activa mientras se repiten.
  • Despertares: Se ejecutan una vez a la hora que elijas, tanto si la sesión está activa como inactiva.

​
Ticks

Los ticks ejecutan código en un intervalo y mantienen la sesión activa mientras se repiten. Usa shouldTick() para definir las condiciones en las que se ejecutan los ticks. Un actor vuelve a evaluar shouldTick() después de cada conexión, mensaje, desconexión y tick, así que los ticks se detienen en cuanto la condición deja de cumplirse.
Los ticks necesitan al menos un cliente conectado.
Con los ticks, puedes:
  • Elegir la duración de cada intervalo.
  • Definir una condición que inicie y detenga los ticks, como “hay al menos dos jugadores en la sesión”.
  • Escribir el código que se ejecuta en cada intervalo.
Usa ticks para mantener una sesión activa incluso cuando los clientes no envían mensajes, por ejemplo, para actualizar un temporizador de ronda. Para más información sobre los ticks, consulta manejadores y configuración de temporizadores y ejecutar ticks para ver un flujo de ejemplo.

​
Despertares

Un despertar se ejecuta una vez a la hora que elijas, tanto si la sesión está activa como inactiva. Con los despertares, puedes:
  • Programar cuándo se ejecuta un despertar.
  • Implementar la lógica que se ejecuta cuando ocurre un despertar.
Usa un despertar para programar una acción única, como terminar el turno de un juego, cerrar una sala de espera vacía, activar un recordatorio o iniciar un evento a una hora concreta. Para más información sobre los despertares, consulta manejadores y configuración de temporizadores y programar despertares para ver un flujo de ejemplo.

​
Desplegar un actor

Despliega actores con actors deploy. Para enviar todos los recursos del proyecto a la vez, usa deploy. El despliegue añade y actualiza los actores remotos y deja el resto como está.

​
Eliminar un actor

Para eliminar un actor:
  • Ejecuta actors delete para eliminar el actor remoto de Base44.
  • Elimina el directorio del actor de tu proyecto local.
Si no eliminas el actor de tu proyecto local, el siguiente actors deploy o deploy vuelve a crear y desplegar el actor en tu proyecto de Base44.

​
Ver también

Esta página fue traducida con IA. Para obtener la información más precisa y actualizada, consulta la versión en inglés.