Acteurs : exemples de flux

Utilisez ces exemples de flux comme point de départ pour votre implémentation.

Connecter un client à une session

Lorsque le frontend doit rejoindre une session en direct, recevoir des messages de l’acteur et lui envoyer des messages, connectez un client à une session d’acteur. Pour connecter un client à une session :

Appelez base44.actors.ActorName(sessionId) pour sélectionner la session.
Appelez .connect() pour ouvrir la connexion WebSocket.
Appelez conn.subscribe() pour enregistrer un écouteur des messages de l’acteur.
Appelez conn.send() pour envoyer un message à l’acteur.

L’exemple suivant se connecte à une session de l’acteur chatRoom, écoute les messages et envoie un message :

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

Pour en savoir plus sur les connexions, consultez connexions.

Exécuter des ticks

Lorsqu’une tâche doit se répéter à intervalle régulier pendant que des clients sont dans la session, exécutez des ticks. Par exemple, pour diffuser l’état d’un jeu ou mettre à jour un minuteur de manche. Pour exécuter des ticks :

Définissez tickIntervalMs sur la durée de l’intervalle en millisecondes.
Implémentez shouldTick() pour renvoyer true afin de continuer les ticks, et false pour les arrêter.
Dans handleTick(), exécutez la tâche de chaque intervalle.

L’exemple suivant exécute un tick chaque seconde tant qu’au moins deux clients sont dans la session, et diffuse un compte à rebours à chaque 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 });
  }
}

Pour en savoir plus sur les ticks, consultez gestionnaires et paramètres de minuteur.

Planifier des réveils

Lorsqu’une tâche doit s’exécuter une seule fois à un moment précis, que la session soit active ou inactive, planifiez un réveil. Par exemple, pour terminer un tour après 30 secondes ou fermer un lobby vide. Pour planifier un réveil :

Appelez schedule() avec une clé et une heure pour programmer le réveil.
Dans handleWake(), vérifiez la clé et exécutez la tâche de ce réveil.
Lorsque le réveil n’est plus nécessaire, appelez cancelSchedule() avec la clé.

L’exemple suivant planifie un délai d’expiration au début d’un tour et diffuse un message lorsque le délai expire :

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

Pour en savoir plus sur les réveils, consultez gestionnaires et paramètres de minuteur.

Gérer les connexions des clients

Lorsque vous devez décider qui peut rejoindre une session, répondre à un client précis et atteindre tous les clients de la session, gérez les connexions des clients. Pour gérer les connexions des clients :

Dans handleConnect(), vérifiez conn.identity et appelez conn.reject() pour refuser un client.
Appelez conn.send() pour répondre uniquement à ce client.
Dans handleMessage(), appelez broadcast() pour atteindre tous les clients connectés. Pour identifier l’expéditeur, incluez des champs de conn dans le message.

L’exemple suivant refuse les clients anonymes, envoie l’historique au client qui se connecte et diffuse les messages avec l’ID utilisateur de l’expéditeur :

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

Pour en savoir plus sur les connexions, consultez connexions.

Persister les données de session

Lorsque des valeurs doivent survivre à une période d’inactivité, persistez les données de session. Par exemple, un plateau, une liste d’historique ou le tour en cours. Pour persister les données de session :

Dans handleStart(), chargez les valeurs de this.storage dans les champs de la classe.
Après chaque changement, appelez this.storage.put() pour enregistrer la valeur mise à jour.
Pour réinitialiser la session, appelez this.storage.delete() ou this.storage.deleteAll().

L’exemple suivant charge un plateau au démarrage, l’enregistre après chaque coup et vide le stockage lorsque le dernier client se déconnecte :

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

Pour en savoir plus sur le stockage, consultez stockage.

Écrire des données d’entité depuis une session

Lorsque la session doit créer ou mettre à jour des enregistrements de l’application, écrivez des données d’entité. Par exemple, un score final ou une commande terminée. Pour écrire des données d’entité depuis une session :

Validez le message entrant avant d’écrire.
Lisez l’ID utilisateur depuis conn.identity.userId.
Utilisez this.client.asServiceRole pour un accès élevé. Écrivez avec une clé stable, comme l’ID de session, pour qu’un gestionnaire réexécuté mette à jour le même enregistrement.

L’exemple suivant enregistre un score final pour le client authentifié. Un enregistrement ultérieur pour la même session met à jour cet enregistrement :

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

Pour en savoir plus sur l’accès aux entités, consultez accès aux entités.

Appeler une fonction backend pour les tâches avec secret

Les acteurs peuvent lire les secrets de l’application avec secrets.get(). Lorsqu’un gestionnaire a besoin d’une tâche qui utilise un secret, comme appeler une API externe avec une clé API, nous vous recommandons d’appeler une fonction backend. La fonction lit le secret et renvoie le résultat, jamais le secret. Pour appeler une fonction backend depuis un acteur :

Créez une fonction backend qui lit le secret avec secrets.get(), effectue la tâche et renvoie le résultat.
Dans un gestionnaire, appelez this.client.functions.invoke() avec le nom de la fonction et les données à envoyer.
Utilisez le résultat dans votre session, par exemple en le diffusant aux clients connectés.

L’exemple suivant montre une fonction backend qui lit une clé API et renvoie une traduction :

// 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’exemple suivant appelle cette fonction depuis un acteur et diffuse le résultat :

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

Voir aussi

Présentation des acteurs : concepts et terminologie
Créer un acteur : fichiers d’acteur et classe minimale
Fichiers et code des acteurs : API complète de la classe backend
actors deploy : déployer les acteurs locaux

Cette page a été traduite par IA. Pour les informations les plus précises et à jour, consultez la version anglaise.

Aperçu

Démarrages rapides

Projet

Outils de développement IA

Ressources

Connecter un client à une session

Exécuter des ticks

Planifier des réveils

Gérer les connexions des clients

Persister les données de session

Écrire des données d’entité depuis une session

Appeler une fonction backend pour les tâches avec secret

Voir aussi

​Connecter un client à une session

​Exécuter des ticks

​Planifier des réveils

​Gérer les connexions des clients

​Persister les données de session

​Écrire des données d’entité depuis une session

​Appeler une fonction backend pour les tâches avec secret

​Voir aussi

Connecter un client à une session

Exécuter des ticks

Planifier des réveils

Gérer les connexions des clients

Persister les données de session

Écrire des données d’entité depuis une session

Appeler une fonction backend pour les tâches avec secret

Voir aussi