> ## Documentation Index
> Fetch the complete documentation index at: https://docs.base44.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Internal links on these pages omit the .md extension. Append .md to a docs page URL, or send an Accept: text/markdown header, to get that page as markdown.

# Fichiers et code des acteurs

> Référence complète de la classe Actor, de ses gestionnaires, connexions, stockage et minuteurs

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      Vous consultez la documentation pour développeurs
    </div>

    <div className="dev-docs-banner-text">
      Cette documentation est destinée aux développeurs travaillant avec la plateforme développeur Base44.
    </div>
  </div>
</div>

Référence complète de la classe `Actor` qui s'exécute dans le backend de votre application. Pour le SDK client qui se connecte à une session, consultez la [référence SDK `actors`](/fr/developers/references/sdk/docs/type-aliases/actors).

Pour les concepts et la terminologie des acteurs, consultez la [présentation des acteurs](/fr/developers/backend/resources/actors/overview).

## Gestionnaires obligatoires

La classe `Actor` est abstraite. Implémentez le corps de chacun des gestionnaires suivants. Les gestionnaires répondent aux événements des clients et des minuteurs.

| Gestionnaire | Événements |
| - | - |
| [`handleConnect()`](#lifecycle-handlers) | Un client se connecte. |
| [`handleMessage()`](#lifecycle-handlers) | Un client connecté envoie un message. |
| [`handleClose()`](#lifecycle-handlers) | Un client se déconnecte. |
| [`handleTick()`](#timer-handlers-and-settings) | À chaque intervalle de tick, tant que les ticks sont actifs. |

## Gestionnaires facultatifs

Implémentez ces gestionnaires lorsque votre acteur en a besoin.

| Gestionnaire | Événements |
| - | - |
| [`handleStart()`](#lifecycle-handlers) | La session démarre, avant que Base44 ne traite une connexion. |
| [`shouldTick()`](#timer-handlers-and-settings) | Après chaque connexion, message, déconnexion et tick. |
| [`handleWake()`](#timer-handlers-and-settings) | Une heure définie avec `schedule()` arrive. |

Lorsque la session utilise des ticks, définissez [`tickIntervalMs`](#timer-handlers-and-settings). Si vous omettez `shouldTick()`, la session n'exécute jamais de ticks.

## Méthodes à appeler

La classe d'acteur fournit des fonctionnalités intégrées. Voici les méthodes que vous pouvez utiliser pour implémenter les gestionnaires d'un acteur.

| Méthode | Rôle |
| - | - |
| [`schedule()`](#timer-handlers-and-settings) | Programmer un réveil au moment de votre choix. |
| [`cancelSchedule()`](#timer-handlers-and-settings) | Annuler un réveil planifié. |
| [`conn.send()`](#connections) | Répondre à un client. |
| [`conn.reject()`](#connections) | Refuser un client qui se connecte. |
| [`broadcast()`](#connections) | Atteindre tous les clients de la session. |
| [`getConnections()`](#connections) | Lister les clients connectés. |
| [`this.storage.get()`](#storage) | Lire une valeur de session enregistrée. |
| [`this.storage.put()`](#storage) | Enregistrer une valeur de session. |
| [`this.storage.delete()`](#storage) | Supprimer une valeur enregistrée. |
| [`this.storage.deleteAll()`](#storage) | Vider le magasin de la session. |
| [`secrets.get()`](#read-secrets) | Lire un secret de l'application. |

Utilisez [`this.client`](#entity-access) pour lire et écrire des [entités](/fr/developers/backend/resources/entities/overview).

## Déclaration de classe

Importez `Actor` depuis `base44:runtime/actors` et exportez par défaut une classe qui étend `Actor` depuis `base44/actors/<actor-name>/entry.ts`.
Le nom du dossier devient le nom de l'acteur dans le SDK. Pour les détails de configuration, consultez [créer un acteur](/fr/developers/backend/resources/actors/create-actor).

<ResponseField name="Incoming" type="generic">
  Type les messages que l'acteur reçoit des clients connectés. S'applique au
  paramètre `msg` de `handleMessage()`.
</ResponseField>

<ResponseField name="Outgoing" type="generic">
  Type les messages que l'acteur envoie aux clients connectés. S'applique à
  `conn.send()` et `broadcast()`.
</ResponseField>

## API d'exécution

Les acteurs importent la classe `Actor` depuis le module `base44:runtime/actors` :

```typescript theme={null}
import { Actor } from "base44:runtime/actors";
```

### Lire les secrets

Utilisez `secrets.get()` pour lire les variables d'environnement de votre application depuis un gestionnaire. La méthode renvoie la valeur sous forme de chaîne, ou `undefined` si le secret n'est pas défini.

Importez `secrets` depuis le module `base44:runtime` :

```typescript theme={null}
import { secrets } from "base44:runtime";
```

Configurez les secrets depuis la CLI avec [`secrets set`](/fr/developers/references/cli/commands/secrets-set).

Nous vous recommandons d'appeler une [fonction backend](/fr/developers/backend/resources/backend-functions/overview) pour les tâches qui nécessitent un secret. La fonction lit le secret et renvoie le résultat, l'acteur ne reçoit donc jamais le secret. Pour un exemple de flux, consultez [appeler une fonction backend pour les tâches avec secret](/fr/developers/backend/resources/actors/sample-flows#call-a-backend-function-for-secret-work).

## Gestionnaires de cycle de vie

Base44 appelle ces gestionnaires en réponse à l'activité des clients dans la session.
Vous implémentez le corps de chacun.
En savoir plus sur [l'interaction entre acteurs et clients](/fr/developers/backend/resources/actors/overview#how-actors-and-clients-interact).
Pour un exemple de flux, consultez [gérer les connexions des clients](/fr/developers/backend/resources/actors/sample-flows#manage-client-connections).

<ResponseField name="handleStart" type="method">
  S'exécute chaque fois qu'une session s'active, par exemple :

  * Lorsque la session est créée pour la première fois.
  * Lorsqu'un client se connecte à une session inactive.
  * Lorsqu'un message arrive sur une session inactive.
  * Lorsqu'une heure planifiée arrive.

  Renvoie `void` ou une `Promise<void>`.
</ResponseField>

<ResponseField name="handleConnect" type="method" required>
  S'exécute lorsqu'un client se connecte à la session.
  Vous pouvez envoyer l'état actuel de la session avec `conn.send()`, ou refuser la connexion avec `conn.reject()`.
  Renvoie `void` ou une `Promise<void>`.

  <Expandable title="Paramètres">
    <ResponseField name="conn" type="Conn" required>
      Représente le client qui s'est connecté.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleMessage" type="method" required>
  S'exécute lorsqu'un client connecté envoie un message.
  Vous pouvez valider le message avant de modifier l'état de la session ou d'accéder aux données de l'application.
  Renvoie `void` ou une `Promise<void>`.

  <Expandable title="Paramètres">
    <ResponseField name="conn" type="Conn" required>
      Représente le client qui a envoyé le message.
    </ResponseField>

    <ResponseField name="msg" type="Incoming" required>
      Contient le message envoyé par le client. Le générique `Incoming` définit
      le type du message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleClose" type="method" required>
  S'exécute lorsqu'un client se déconnecte.
  Utilisez ce gestionnaire pour supprimer tout état de session associé à l'ID de connexion.
  Une reconnexion qui réutilise le même ID remplace l'ancien socket sans exécuter `handleClose()`.
  Renvoie `void` ou une `Promise<void>`.

  <Expandable title="Paramètres">
    <ResponseField name="conn" type="Conn" required>
      Représente le client qui s'est déconnecté.
    </ResponseField>
  </Expandable>
</ResponseField>

## Gestionnaires et paramètres de minuteur

Ces gestionnaires et paramètres contrôlent les tâches minutées de la session.
Base44 les appelle lorsqu'une heure planifiée arrive, et non en réponse à l'activité des clients.
En savoir plus sur [les tâches planifiées](/fr/developers/backend/resources/actors/overview#scheduled-work).
Pour des exemples de flux, consultez [exécuter des ticks](/fr/developers/backend/resources/actors/sample-flows#run-ticks) et [planifier des réveils](/fr/developers/backend/resources/actors/sample-flows#schedule-wakes).

<ResponseField name="handleTick" type="method" required>
  S'exécute une fois par intervalle tant que `shouldTick()` renvoie `true` et que la session a au moins un client.
  Renvoie `void` ou une `Promise<void>`.
</ResponseField>

<ResponseField name="tickIntervalMs" type="number">
  Indique l'intervalle entre les ticks en millisecondes. Valeur par défaut : `100`.
</ResponseField>

<ResponseField name="shouldTick" type="method">
  Renvoie un `boolean`. Renvoyez `true` pour maintenir les ticks de la session, ou `false` pour les arrêter. Cette méthode est synchrone.

  Gardez cette méthode rapide et sans effets de bord. Base44 l'appelle après chaque connexion, message, déconnexion et tick.
</ResponseField>

<ResponseField name="handleWake" type="method">
  S'exécute une fois lorsqu'une heure définie avec `schedule()` arrive.
  Renvoie `void` ou une `Promise<void>`.

  <Expandable title="Paramètres">
    <ResponseField name="key" type="string" required>
      Contient la clé passée à `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="method">
  Planifie une exécution de `handleWake()` à une heure donnée.
  Renvoie une `Promise` qui se résout après l'enregistrement du planning par Base44.
  Le planning survit à une période d'inactivité et peut démarrer une session inactive.
  Appeler à nouveau cette méthode avec la même clé remplace l'heure planifiée.

  <Expandable title="Paramètres">
    <ResponseField name="key" type="string" required>
      Identifie le réveil planifié. Passée à `handleWake()` au déclenchement du réveil.
    </ResponseField>

    <ResponseField name="at" type="number | Date" required>
      Indique quand `handleWake()` s'exécute. Utilisez un objet `Date` ou un nombre de millisecondes
      depuis le 1er janvier 1970.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancelSchedule" type="method">
  Annule le réveil planifié associé à une clé.
  Renvoie une `Promise` qui se résout après la suppression du planning par Base44.

  <Expandable title="Paramètres">
    <ResponseField name="key" type="string" required>
      Indique la clé passée à `schedule()`.
    </ResponseField>
  </Expandable>
</ResponseField>

## Connexions

Ces propriétés et méthodes sont disponibles sur l'objet `conn` passé aux gestionnaires de cycle de vie qui concernent un client.
Utilisez-les pour lire l'identité du client, envoyer des messages et gérer la connexion.
Pour une présentation de la messagerie, consultez [messages en temps réel](/fr/developers/backend/resources/actors/overview#realtime-messages).
Pour un exemple de flux, consultez [gérer les connexions des clients](/fr/developers/backend/resources/actors/sample-flows#manage-client-connections).

<Note>
  `conn` est l'extrémité backend du WebSocket, et `Connection` côté client est l'autre extrémité du même socket. Utilisez `conn` dans la classe d'acteur. Consultez la référence SDK `actors` pour l'objet client.
</Note>

<ResponseField name="conn.id" type="string">
  Identifie cette connexion. Correspond à l'ID passé par le client lors de la connexion,
  ou à un ID généré par le SDK.
</ResponseField>

<ResponseField name="conn.identity" type="object">
  Identifie le client sur cette connexion. Présent sur toutes les
  connexions.

  <Expandable title="Propriétés">
    <ResponseField name="type" type="string" required>
      Contient `authenticated` ou `anonymous`.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Identifie le client connecté à son compte. Présent lorsque `type` vaut
      `authenticated`.
    </ResponseField>

    <ResponseField name="anonymousId" type="string">
      Identifie le client anonyme. Présent lorsque `type` vaut `anonymous`.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.send" type="method">
  Envoie un message à cette connexion. Renvoie `void`.

  <Expandable title="Paramètres">
    <ResponseField name="data" type="Outgoing" required>
      Contient le message à envoyer à cette connexion. Le générique `Outgoing` définit le type du message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.reject" type="method">
  Refuse une connexion depuis `handleConnect()`. Renvoie `void`.

  <Expandable title="Paramètres">
    <ResponseField name="code" type="number" required>
      Indique le code de statut envoyé au client.
    </ResponseField>

    <ResponseField name="reason" type="string" required>
      Décrit pourquoi l'acteur a refusé la connexion.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="broadcast" type="method">
  Envoie un message à chaque connexion active de la session. Renvoie `void`.

  <Expandable title="Paramètres">
    <ResponseField name="data" type="Outgoing" required>
      Contient le message à envoyer à chaque connexion de la session. Le générique `Outgoing` définit le type du message.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="getConnections" type="method">
  Renvoie un tableau des objets `conn` actifs dans la session. Utilisez cette méthode dans
  `handleStart()` pour associer les données restaurées aux clients restés connectés
  pendant une période d'inactivité.
</ResponseField>

<ResponseField name="this.instanceId" type="string">
  Propriété au niveau de la session. Contient l'ID de session que le client a utilisé pour atteindre
  cette session.
</ResponseField>

## Stockage

Utilisez `this.storage` pour lire et écrire les données de session. Contrairement aux champs de la classe, le stockage survit aux périodes d'inactivité. Pour choisir entre le stockage et les champs de la classe, consultez [stockage](/fr/developers/backend/resources/actors/overview#storage). Pour un exemple de flux, consultez [persister les données de session](/fr/developers/backend/resources/actors/sample-flows#persist-session-data).

<ResponseField name="this.storage.get" type="method">
  Récupère une valeur par clé. Renvoie une `Promise` qui se résout avec la
  valeur stockée, ou `undefined` si la clé n'existe pas.

  <Expandable title="Paramètres">
    <ResponseField name="key" type="string" required>
      Indique la clé à récupérer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.put" type="method">
  Enregistre une valeur par clé. Remplace la valeur déjà stockée sous cette clé. Renvoie
  une `Promise` qui se résout lorsque l'écriture est terminée.

  <Expandable title="Paramètres">
    <ResponseField name="key" type="string" required>
      Indique la clé à enregistrer.
    </ResponseField>

    <ResponseField name="value" type="unknown" required>
      Indique la valeur compatible JSON à enregistrer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.delete" type="method">
  Supprime une valeur par clé. Renvoie une `Promise` qui se résout avec `true` si la
  clé existait, et `false` sinon.

  <Expandable title="Paramètres">
    <ResponseField name="key" type="string" required>
      Indique la clé à supprimer.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.deleteAll" type="method">
  Supprime toutes les données enregistrées de la session. Renvoie une `Promise` qui se résout lorsque
  le magasin est vide. Une connexion ultérieure démarre avec le même stockage vide qu'une
  nouvelle session.
</ResponseField>

## Accès aux entités

Utilisez `this.client` et `this.client.asServiceRole` pour lire et écrire les entités de l'application depuis un gestionnaire d'acteur. Pour un exemple de flux, consultez [écrire des données d'entité depuis une session](/fr/developers/backend/resources/actors/sample-flows#write-entity-data-from-a-session).

<ResponseField name="this.client" type="Base44Client">
  Fournit un client d'application limité à cette session. Ce client utilise une
  authentification anonyme. L'accès aux entités suit donc les mêmes règles qu'un
  client non connecté, et il lit les données de production.
</ResponseField>

<ResponseField name="this.client.asServiceRole" type="Base44Client">
  Fournit un accès élevé qui contourne la sécurité au niveau ligne. Validez les messages
  avant d'utiliser ce client. Rendez les écritures sûres à répéter, car la session peut réexécuter un gestionnaire
  après une erreur.
</ResponseField>

## Voir aussi

* [Présentation des acteurs](/fr/developers/backend/resources/actors/overview) : concepts et terminologie
* [Acteurs : exemples de flux](/fr/developers/backend/resources/actors/sample-flows) : cycle de vie, minuteurs, connexions, stockage, entités et fonctions backend
* [Référence SDK `actors`](/fr/developers/references/sdk/docs/type-aliases/actors) : API du SDK client
* [`secrets set`](/fr/developers/references/cli/commands/secrets-set) : configurer les variables d'environnement depuis la CLI

<Note>Cette page a été traduite par IA. Pour les informations les plus précises et à jour, consultez la [version anglaise](/). </Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.