Actor: flussi di esempio

Usa questi flussi di esempio come punto di partenza per la tua implementazione.

Connettere un client a una sessione

Quando il frontend deve unirsi a una sessione live, ricevere messaggi dall’actor e inviare messaggi all’actor, connetti un client a una sessione dell’actor. Per connettere un client a una sessione:

Chiama base44.actors.ActorName(sessionId) per selezionare la sessione.
Chiama .connect() per aprire la connessione WebSocket.
Chiama conn.subscribe() per registrare un listener per i messaggi dell’actor.
Chiama conn.send() per inviare un messaggio all’actor.

L’esempio seguente si connette a una sessione dell’actor chatRoom, ascolta i messaggi e invia un messaggio:

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" });

Per saperne di più sulle connessioni, consulta connessioni.

Eseguire i tick

Quando un’operazione deve ripetersi a intervalli mentre i client sono nella sessione, esegui i tick. Ad esempio, per trasmettere lo stato del gioco o aggiornare il timer di un round. Per eseguire i tick:

Imposta tickIntervalMs sulla durata dell’intervallo in millisecondi.
Implementa shouldTick() in modo che restituisca true per continuare i tick e false per fermarli.
In handleTick(), esegui l’operazione per ogni intervallo.

L’esempio seguente esegue un tick ogni secondo mentre almeno due client sono nella sessione, trasmettendo un conto alla rovescia a ogni 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 });
  }
}

Per saperne di più sui tick, consulta handler e impostazioni dei timer.

Pianificare i wake

Quando un’operazione deve essere eseguita una volta in un momento specifico, sia che la sessione sia attiva sia che sia inattiva, pianifica un wake. Ad esempio, per terminare un turno dopo 30 secondi o chiudere una lobby vuota. Per pianificare un wake:

Chiama schedule() con una chiave e un orario per impostare il wake.
In handleWake(), controlla la chiave ed esegui l’operazione per quel wake.
Quando il wake non serve più, chiama cancelSchedule() con la chiave.

L’esempio seguente pianifica un timeout del turno quando un turno inizia e trasmette un messaggio quando il timeout si attiva:

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" });
    }
  }
}

Per saperne di più sui wake, consulta handler e impostazioni dei timer.

Gestire le connessioni dei client

Quando devi decidere chi può unirsi a una sessione, rispondere a un client specifico e raggiungere tutti i client della sessione, gestisci le connessioni dei client. Per gestire le connessioni dei client:

In handleConnect(), controlla conn.identity e chiama conn.reject() per rifiutare un client.
Chiama conn.send() per rispondere solo a quel client.
In handleMessage(), chiama broadcast() per raggiungere tutti i client connessi. Per identificare il mittente, includi nel messaggio campi di conn.

L’esempio seguente rifiuta i client anonimi, invia la cronologia al client che si connette e trasmette i messaggi con l’ID utente del mittente:

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 });
}

Per saperne di più sulle connessioni, consulta connessioni.

Rendere persistenti i dati di sessione

Quando dei valori devono sopravvivere a un periodo di inattività, rendi persistenti i dati di sessione. Ad esempio, una plancia, un elenco della cronologia o il turno attuale. Per rendere persistenti i dati di sessione:

In handleStart(), carica i valori da this.storage nei campi della classe.
Dopo ogni modifica, chiama this.storage.put() per salvare il valore aggiornato.
Per reimpostare la sessione, chiama this.storage.delete() o this.storage.deleteAll().

L’esempio seguente carica una plancia all’avvio, la salva dopo ogni mossa e svuota lo storage quando l’ultimo client si disconnette:

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();
  }
}

Per saperne di più sullo storage, consulta storage.

Scrivere dati delle entità da una sessione

Quando la sessione deve creare o aggiornare record dell’app, scrivi dati delle entità. Ad esempio, un punteggio finale o un ordine completato. Per scrivere dati delle entità da una sessione:

Valida il messaggio in arrivo prima di scrivere.
Leggi l’ID utente da conn.identity.userId.
Usa this.client.asServiceRole per un accesso elevato. Scrivi con una chiave stabile, come l’ID di sessione, così un handler ripetuto aggiorna lo stesso record.

L’esempio seguente salva un punteggio finale per il client autenticato. Un salvataggio successivo per la stessa sessione aggiorna quel record:

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);
  }
}

Per saperne di più sull’accesso alle entità, consulta accesso alle entità.

Chiamare una funzione backend per operazioni con secret

Gli actor possono leggere i secret dell’app con secrets.get(). Quando un handler deve eseguire un’operazione che usa un secret, come chiamare un’API esterna con una chiave API, ti consigliamo di chiamare una funzione backend. La funzione legge il secret e restituisce il risultato, mai il secret. Per chiamare una funzione backend da un actor:

Crea una funzione backend che legge il secret con secrets.get(), esegue l’operazione e restituisce il risultato.
In un handler, chiama this.client.functions.invoke() con il nome della funzione e i dati da inviare.
Usa il risultato nella tua sessione, ad esempio trasmettendolo ai client connessi.

L’esempio seguente mostra una funzione backend che legge una chiave API e restituisce una traduzione:

// 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 });
}

L’esempio seguente chiama quella funzione da un actor e trasmette il risultato:

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 });
  }
}

Vedi anche

Panoramica degli actor: Concetti e terminologia
Creare un actor: File degli actor e una classe minima
File e codice degli actor: API completa della classe di backend
actors deploy: Distribuisci gli actor locali

Questa pagina è stata tradotta con l’AI. Per le informazioni più accurate e aggiornate, consulta la versione inglese.

Panoramica

Guida rapida

Progetto

Strumenti di sviluppo con IA

Risorse

Connettere un client a una sessione

Eseguire i tick

Pianificare i wake

Gestire le connessioni dei client

Rendere persistenti i dati di sessione

Scrivere dati delle entità da una sessione

Chiamare una funzione backend per operazioni con secret

Vedi anche

​Connettere un client a una sessione

​Eseguire i tick

​Pianificare i wake

​Gestire le connessioni dei client

​Rendere persistenti i dati di sessione

​Scrivere dati delle entità da una sessione

​Chiamare una funzione backend per operazioni con secret

​Vedi anche

Connettere un client a una sessione

Eseguire i tick

Pianificare i wake

Gestire le connessioni dei client

Rendere persistenti i dati di sessione

Scrivere dati delle entità da una sessione

Chiamare una funzione backend per operazioni con secret

Vedi anche