Actores: flujos de ejemplo

Usa estos flujos de ejemplo como punto de partida para tu implementación.

Conectar un cliente a una sesión

Cuando el frontend necesita unirse a una sesión en vivo, recibir mensajes del actor y enviarle mensajes, conecta un cliente a una sesión de actor. Para conectar un cliente a una sesión:

Llama a base44.actors.ActorName(sessionId) para seleccionar la sesión.
Llama a .connect() para abrir la conexión WebSocket.
Llama a conn.subscribe() para registrar un listener para los mensajes del actor.
Llama a conn.send() para enviar un mensaje al actor.

El siguiente ejemplo se conecta a una sesión del actor chatRoom, escucha los mensajes y envía un mensaje:

const conn = base44.actors.chatRoom("lobby-1").connect();

conn.subscribe((msg) => {
  if (msg.type === "message") console.log(msg.text);
});

conn.send({ type: "message", text: "Hello" });

Para más información sobre las conexiones, consulta conexiones.

Ejecutar ticks

Cuando un trabajo debe repetirse en un intervalo mientras hay clientes en la sesión, ejecuta ticks. Por ejemplo, para difundir el estado de un juego o actualizar un temporizador de ronda. Para ejecutar ticks:

Define tickIntervalMs con la duración del intervalo en milisegundos.
Implementa shouldTick() para que devuelva true para seguir con los ticks y false para detenerlos.
En handleTick(), ejecuta el trabajo de cada intervalo.

El siguiente ejemplo ejecuta un tick cada segundo mientras hay al menos dos clientes en la sesión, y difunde una cuenta atrás en cada tick:

export default class Game extends Actor<Incoming, Outgoing> {
  tickIntervalMs = 1000;
  countdown = 60;

  shouldTick() {
    return this.getConnections().length >= 2;
  }

  async handleTick() {
    this.countdown--;
    this.broadcast({ type: "tick", countdown: this.countdown });
  }
}

Para más información sobre los ticks, consulta manejadores y configuración de temporizadores.

Programar despertares

Cuando un trabajo debe ejecutarse una vez a una hora concreta, tanto si la sesión está activa como inactiva, programa un despertar. Por ejemplo, para terminar un turno después de 30 segundos o cerrar una sala de espera vacía. Para programar un despertar:

Llama a schedule() con una clave y una hora para programar el despertar.
En handleWake(), comprueba la clave y ejecuta el trabajo de ese despertar.
Cuando el despertar ya no sea necesario, llama a cancelSchedule() con la clave.

El siguiente ejemplo programa un tiempo límite de turno cuando empieza un turno y difunde un mensaje cuando se activa el tiempo límite:

export default class Game extends Actor<Incoming, Outgoing> {
  async handleMessage(_conn, msg) {
    if (msg.type === "start-turn") {
      await this.schedule("turn-timeout", Date.now() + 30_000);
    }
    if (msg.type === "end-turn") {
      await this.cancelSchedule("turn-timeout");
    }
  }

  async handleWake(key: string) {
    if (key === "turn-timeout") {
      this.broadcast({ type: "timeout" });
    }
  }
}

Para más información sobre los despertares, consulta manejadores y configuración de temporizadores.

Gestionar las conexiones de clientes

Cuando necesitas decidir quién puede unirse a una sesión, responder a un cliente concreto y llegar a todos los clientes de la sesión, gestiona las conexiones de clientes. Para gestionar las conexiones de clientes:

En handleConnect(), comprueba conn.identity y llama a conn.reject() para rechazar a un cliente.
Llama a conn.send() para responder solo a ese cliente.
En handleMessage(), llama a broadcast() para llegar a todos los clientes conectados. Para identificar al remitente, incluye campos de conn en el mensaje.

El siguiente ejemplo rechaza a los clientes anónimos, envía el historial al cliente que se conecta y difunde los mensajes con el ID de usuario del remitente:

async handleConnect(conn) {
  if (conn.identity.type === "anonymous") {
    conn.reject(401, "Login required");
    return;
  }
  conn.send({ type: "history", messages: this.messages });
}

async handleMessage(conn, msg) {
  this.broadcast({ type: "message", from: conn.identity.userId, text: msg.text });
}

Para más información sobre las conexiones, consulta conexiones.

Conservar los datos de sesión

Cuando los valores deben sobrevivir a un periodo de inactividad, conserva los datos de sesión. Por ejemplo, un tablero, una lista de historial o el turno actual. Para conservar los datos de sesión:

En handleStart(), carga los valores de this.storage en los campos de clase.
Después de cada cambio, llama a this.storage.put() para guardar el valor actualizado.
Para reiniciar la sesión, llama a this.storage.delete() o this.storage.deleteAll().

El siguiente ejemplo carga un tablero al inicio, lo guarda después de cada movimiento y vacía el almacenamiento cuando se desconecta el último cliente:

async handleStart() {
  this.board = (await this.storage.get<Board>("board")) ?? newBoard();
}

async handleMessage(_conn, msg) {
  applyMove(this.board, msg.move);
  await this.storage.put("board", this.board);
}

async handleClose(_conn) {
  if (this.getConnections().length === 0) {
    await this.storage.deleteAll();
  }
}

Para más información sobre el almacenamiento, consulta almacenamiento.

Escribir datos de entidades desde una sesión

Cuando la sesión necesita crear o actualizar registros de la app, escribe datos de entidades. Por ejemplo, una puntuación final o un pedido completado. Para escribir datos de entidades desde una sesión:

Valida el mensaje entrante antes de escribir.
Lee el ID de usuario de conn.identity.userId.
Usa this.client.asServiceRole para obtener acceso elevado. Escribe con una clave estable, como el ID de sesión, para que un manejador repetido actualice el mismo registro.

El siguiente ejemplo guarda una puntuación final para el cliente autenticado. Un guardado posterior para la misma sesión actualiza ese registro:

async handleMessage(conn, msg) {
  if (msg.type !== "save-score" || conn.identity.type !== "authenticated") return;
  if (typeof msg.score !== "number") return;

  const fields = {
    sessionId: this.instanceId,
    userId: conn.identity.userId,
    score: msg.score,
  };
  const [existing] = await this.client.asServiceRole.entities.Score.filter({
    sessionId: this.instanceId,
  });

  if (existing) {
    await this.client.asServiceRole.entities.Score.update(existing.id, fields);
  } else {
    await this.client.asServiceRole.entities.Score.create(fields);
  }
}

Para más información sobre el acceso a entidades, consulta acceso a entidades.

Llamar a una función de backend para trabajo con secretos

Los actores pueden leer los secretos de la app con secrets.get(). Cuando un manejador necesita un trabajo que usa un secreto, como llamar a una API externa con una clave de API, te recomendamos llamar a una función de backend. La función lee el secreto y devuelve el resultado, nunca el secreto. Para llamar a una función de backend desde un actor:

Crea una función de backend que lea el secreto con secrets.get(), haga el trabajo y devuelva el resultado.
En un manejador, llama a this.client.functions.invoke() con el nombre de la función y los datos que quieres enviar.
Usa el resultado en tu sesión, por ejemplo, difundiéndolo a los clientes conectados.

El siguiente ejemplo muestra una función de backend que lee una clave de API y devuelve una traducción:

// base44/functions/translateText/entry.ts
import { secrets } from "base44:runtime";

export default async function (req: Request): Promise<Response> {
  const { text } = await req.json();
  const apiKey = secrets.get("TRANSLATE_API_KEY");

  const res = await fetch("https://api.example.com/translate", {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}` },
    body: JSON.stringify({ text }),
  });
  const { translation } = await res.json();

  return Response.json({ translation });
}

El siguiente ejemplo llama a esa función desde un actor y difunde el resultado:

export default class ChatRoom extends Actor<Incoming, Outgoing> {
  async handleMessage(_conn, msg) {
    const result = await this.client.functions.invoke("translateText", { text: msg.text });
    this.broadcast({ type: "message", text: result.data.translation });
  }
}

Ver también

Resumen de actores: Conceptos y terminología
Crear un actor: Archivos del actor y una clase mínima
Archivos y código de actores: API completa de la clase de backend
actors deploy: Despliega los actores locales

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

Resumen

Inicio rápido

Proyecto

Herramientas de Desarrollo con IA

Recursos

Conectar un cliente a una sesión

Ejecutar ticks

Programar despertares

Gestionar las conexiones de clientes

Conservar los datos de sesión

Escribir datos de entidades desde una sesión

Llamar a una función de backend para trabajo con secretos

Ver también

​Conectar un cliente a una sesión

​Ejecutar ticks

​Programar despertares

​Gestionar las conexiones de clientes

​Conservar los datos de sesión

​Escribir datos de entidades desde una sesión

​Llamar a una función de backend para trabajo con secretos

​Ver también

Conectar un cliente a una sesión

Ejecutar ticks

Programar despertares

Gestionar las conexiones de clientes

Conservar los datos de sesión

Escribir datos de entidades desde una sesión

Llamar a una función de backend para trabajo con secretos

Ver también