Skip to main content
Vous consultez la documentation pour développeurs
Cette documentation est destinée aux développeurs travaillant avec la plateforme développeur Base44.
Un acteur est un processus backend de longue durée auquel plusieurs clients se connectent simultanément. Avec les acteurs, vous pouvez créer des instances de session en direct qui prennent en charge les fonctionnalités suivantes :
  • Messagerie en temps réel : envoyez et recevez des messages avec les clients via WebSockets.
  • Stockage persistant : conservez l’état de la session entre les périodes d’inactivité.
  • Tâches planifiées : exécutez une logique à intervalle fixe ou à un moment précis.
Utilisez les acteurs pour créer des fonctionnalités où plusieurs clients ont besoin de mises à jour et d’interactions en temps réel, comme un salon de discussion ou un jeu multijoueur.

​
Acteurs

Actor est la classe que vous étendez dans votre backend. La classe d’acteur définit le comportement d’une session en direct. Avec les acteurs, vous pouvez :
  • Gérer les connexions : accepter ou refuser un client qui se connecte à la session, et identifier qui se connecte.
  • Traiter les messages : recevoir un message d’un client, mettre à jour l’état de la session, et répondre à un client ou diffuser à tous.
  • Planifier des tâches : exécuter une logique à intervalle régulier ou à un moment planifié.

​
Sessions

Une session est une instance en cours d’exécution d’un acteur, identifiée par le nom de l’acteur et un ID de session que vous choisissez.
Chaque session gère indépendamment son propre état, son stockage et ses connexions clients.

​
Connexions

Une connexion représente le WebSocket d’un client vers une session. Chaque client qui rejoint la session obtient une connexion unique. Un acteur utilise cette connexion pour identifier qui se connecte, gérer les connexions clients et envoyer des messages. Pour en savoir plus, consultez connexions. Pour un exemple de flux, consultez gérer les connexions des clients.

​
Sessions actives et inactives

Une session est toujours dans l’un des états suivants :
  • Active : la session est en direct et traite des événements. Une session devient active lorsqu’un client se connecte, lorsqu’un client envoie un message à une session inactive, ou lorsqu’une heure de réveil planifiée arrive.
  • Inactive : la session ne traite pas d’événements. Une session devient inactive peu après avoir traité son dernier message et lorsque toutes les tâches planifiées s’arrêtent. La session conserve ses données stockées, ses heures planifiées et ses connexions ouvertes jusqu’à ce qu’elle redevienne active.
Lorsqu’une session devient inactive, les clients avec des connexions ouvertes restent connectés. Leur prochain message ou un réveil planifié réactive la session.

​
Client

Utilisez base44.actors dans le SDK JavaScript pour connecter un client à une session d’acteur et échanger des messages. Le SDK des acteurs prend en charge les fonctionnalités suivantes :
  • Connecter : ouvrir une connexion WebSocket vers une session.
  • S’abonner : recevoir les messages de l’acteur.
  • Envoyer : envoyer des messages à l’acteur.
  • Fermer : fermer la connexion WebSocket vers l’acteur.
Pour en savoir plus, consultez connecter un client à une session.

​
Interaction entre acteurs et clients

Le diagramme suivant montre l’interaction générale entre un client et un acteur :
  1. Le client se connecte à l’acteur via un WebSocket.
  2. La session s’active. handleStart() s’exécute au premier démarrage et à chaque réactivation de la session après une période d’inactivité.
  3. L’acteur traite la connexion. Vous pouvez vérifier l’identité du client et refuser la connexion, ou envoyer l’état actuel.
  4. Le client envoie un message.
  5. L’acteur traite le message. Vous pouvez valider le format et les autorisations de l’expéditeur avant de modifier l’état de la session.
  6. L’acteur diffuse la mise à jour à tous les clients connectés, ou répond uniquement à l’expéditeur.
  7. Le client ferme la connexion.
  8. L’acteur traite la déconnexion. Vous pouvez supprimer l’état propre à la connexion.

​
Messages en temps réel

Chaque client connecté appartient à une session et peut envoyer des messages en temps réel via WebSockets. Les clients peuvent aussi écouter les messages entrants avec subscribe().
Base44 propose plusieurs fonctionnalités en temps réel qui utilisent un écouteur par abonnement :
  • subscribe() des acteurs écoute les messages que l’acteur envoie aux clients connectés.
  • subscribe() des entités écoute les modifications des entités de l’application.
Vérifiez quel service vous utilisez pour recevoir les événements attendus.
Avec les messages en temps réel, vous pouvez :
  • Répondre à un client précis.
  • Diffuser à tous les clients connectés.
  • Lister les clients actuellement connectés.
  • Identifier chaque client et vérifier s’il est connecté à son compte.
Pour en savoir plus, consultez connexions. Pour un exemple de flux, consultez gérer les connexions des clients.

​
Types de messages

Un client et un acteur échangent des messages via une connexion. Les messages se répartissent dans les types suivants :
  • Messages entrants : ce qu’un client connecté envoie à l’acteur, comme un texte, un coup ou un vote. Le client les envoie avec send(), et l’acteur les reçoit dans handleMessage().
  • Messages sortants : ce que l’acteur envoie aux clients connectés, comme une réponse à un client, une diffusion à tous les clients connectés ou le plateau actuel quand quelqu’un rejoint la session. L’acteur les envoie avec conn.send() ou broadcast(), et le client les reçoit dans un callback subscribe().
Nous vous recommandons de typer vos messages pour que l’acteur et le client s’accordent sur la forme de chaque message :
  • Backend : passez les types Incoming et Outgoing comme génériques à la classe Actor. Pour un exemple complet, consultez créer un acteur.
  • Client : étendez l’interface ActorRegistry avec les mêmes formes, pour que TypeScript vérifie les types de send() et subscribe().

​
Stockage

Les acteurs proposent plusieurs options de stockage selon la façon dont votre session utilise et conserve les données :
  • Stockage en mémoire : l’état de travail qui réside dans les champs de la classe pendant que la session est active, et qui se réinitialise lorsque la session devient inactive.
  • Stockage persistant : un magasin clé-valeur pour les données qui doivent survivre quand la session devient inactive.

​
Stockage en mémoire

Les champs de la classe contiennent l’état de travail pendant que la session est active, comme le plateau actuel ou un minuteur de manche. Utilisez le stockage en mémoire lorsque vos données changent souvent et n’ont pas besoin de persister quand la session devient inactive, comme un score en direct ou la position d’un curseur. Lorsqu’une session devient inactive, les champs de la classe se réinitialisent.

​
Stockage persistant

Chaque session possède son propre magasin clé-valeur, que vous gérez entièrement. Utilisez le stockage persistant lorsque vos données doivent survivre quand la session devient inactive, comme un historique de discussion ou un plateau de jeu. Pour stocker des données disponibles dans toute l’application, utilisez les entités. Pour en savoir plus sur le stockage des acteurs, consultez stockage.

​
Restaurer l’état

Lorsqu’une session devient inactive, l’état en mémoire se réinitialise. Le stockage persistant survit, mais la session ne recharge pas automatiquement les données stockées en mémoire lors de sa réactivation. Utilisez handleStart() pour restaurer les données persistantes, comme l’historique de discussion ou le plateau de jeu. Pour un exemple de flux, consultez persister les données de session.

​
Tâches planifiées

Les acteurs permettent à une session d’exécuter une logique selon un planning, indépendamment des messages des clients :
  • Ticks : exécutez du code à intervalle régulier et gardez la session active pendant qu’ils se répètent.
  • Réveils : exécutez du code une seule fois au moment choisi, que la session soit active ou inactive.

​
Ticks

Les ticks exécutent du code à intervalle régulier et gardent la session active pendant qu’ils se répètent. Utilisez shouldTick() pour définir les conditions d’exécution des ticks. Un acteur réévalue shouldTick() après chaque connexion, message, déconnexion et tick. Les ticks s’arrêtent donc dès que la condition n’est plus remplie.
Les ticks nécessitent au moins un client connecté.
Avec les ticks, vous pouvez :
  • Choisir la durée de chaque intervalle.
  • Définir une condition qui démarre et arrête les ticks, comme « au moins deux joueurs sont dans la session ».
  • Écrire le code qui s’exécute à chaque intervalle.
Utilisez les ticks pour garder une session active même lorsque les clients n’envoient pas de messages, par exemple pour mettre à jour un minuteur de manche. Pour en savoir plus sur les ticks, consultez gestionnaires et paramètres de minuteur, et exécuter des ticks pour un exemple de flux.

​
Réveils

Un réveil s’exécute une seule fois au moment que vous choisissez, que la session soit active ou inactive. Avec les réveils, vous pouvez :
  • Planifier le moment où un réveil s’exécute.
  • Implémenter la logique qui s’exécute lors d’un réveil.
Utilisez un réveil pour planifier une action ponctuelle, comme terminer un tour de jeu, fermer un lobby vide, déclencher un rappel ou démarrer un événement à un moment précis. Pour en savoir plus sur les réveils, consultez gestionnaires et paramètres de minuteur, et planifier des réveils pour un exemple de flux.

​
Déployer un acteur

Déployez les acteurs avec actors deploy. Pour pousser toutes les ressources du projet en une fois, utilisez deploy. Le déploiement ajoute et met à jour les acteurs distants et laisse les autres en place.

​
Supprimer un acteur

Pour supprimer un acteur :
  • Exécutez actors delete pour supprimer l’acteur distant de Base44.
  • Supprimez le répertoire de l’acteur de votre projet local.
Si vous ne supprimez pas l’acteur de votre projet local, le prochain actors deploy ou deploy recrée et déploie l’acteur dans votre projet Base44.

​
Voir aussi

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