> ## 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.

# Actors – Dateien und Code

> Vollständige Referenz für die Klasse Actor, ihre Handler, Verbindungen, Speicher und Timer

<div className="dev-docs-banner">
  <div className="dev-docs-banner-content">
    <div className="dev-docs-banner-title">
      Du siehst gerade die Entwicklerdokumentation
    </div>

    <div className="dev-docs-banner-text">
      Diese Dokumentation richtet sich an Entwickler, die mit der Base44-Entwicklerplattform arbeiten.
    </div>
  </div>
</div>

Vollständige Referenz für die Klasse `Actor`, die im Backend deiner App läuft. Das Client-SDK, das sich mit einer Session verbindet, findest du in der [`actors` SDK-Referenz](/de/developers/references/sdk/docs/type-aliases/actors).

Konzepte und Terminologie zu Actors findest du in der [Actors-Übersicht](/de/developers/backend/resources/actors/overview).

## Erforderliche Handler

Die Klasse `Actor` ist abstrakt. Implementiere den Rumpf jedes der folgenden Handler. Die Handler reagieren auf Ereignisse von Clients und Timern.

| Handler | Ereignisse |
| - | - |
| [`handleConnect()`](#lifecycle-handlers) | Ein Client verbindet sich. |
| [`handleMessage()`](#lifecycle-handlers) | Ein verbundener Client sendet eine Nachricht. |
| [`handleClose()`](#lifecycle-handlers) | Ein Client trennt die Verbindung. |
| [`handleTick()`](#timer-handlers-and-settings) | Jedes Tick-Intervall, solange das Ticken aktiv ist. |

## Optionale Handler

Implementiere diese Handler, wenn dein Actor sie braucht.

| Handler | Ereignisse |
| - | - |
| [`handleStart()`](#lifecycle-handlers) | Die Session startet, bevor Base44 eine Verbindung verarbeitet. |
| [`shouldTick()`](#timer-handlers-and-settings) | Nach jeder Verbindung, Nachricht, Trennung und jedem Tick. |
| [`handleWake()`](#timer-handlers-and-settings) | Ein mit `schedule()` festgelegter Zeitpunkt ist erreicht. |

Wenn die Session tickt, setze [`tickIntervalMs`](#timer-handlers-and-settings). Wenn du `shouldTick()` weglässt, tickt die Session nie.

## Aufrufbare Methoden

Die Actor-Klasse bietet eingebaute Funktionen. Die folgenden Methoden kannst du bei der Implementierung der Handler eines Actors verwenden.

| Methode | Zweck |
| - | - |
| [`schedule()`](#timer-handlers-and-settings) | Einen Wake zu einem gewählten Zeitpunkt planen. |
| [`cancelSchedule()`](#timer-handlers-and-settings) | Einen geplanten Wake entfernen. |
| [`conn.send()`](#connections) | Einem Client antworten. |
| [`conn.reject()`](#connections) | Einen verbindenden Client ablehnen. |
| [`broadcast()`](#connections) | Alle Clients in der Session erreichen. |
| [`getConnections()`](#connections) | Die verbundenen Clients auflisten. |
| [`this.storage.get()`](#storage) | Einen gespeicherten Session-Wert lesen. |
| [`this.storage.put()`](#storage) | Einen Session-Wert speichern. |
| [`this.storage.delete()`](#storage) | Einen gespeicherten Wert entfernen. |
| [`this.storage.deleteAll()`](#storage) | Den Session-Speicher leeren. |
| [`secrets.get()`](#read-secrets) | Ein App-Secret lesen. |

Verwende [`this.client`](#entity-access), um [Entitäten](/de/developers/backend/resources/entities/overview) zu lesen und zu schreiben.

## Klassendeklaration

Importiere `Actor` aus `base44:runtime/actors` und exportiere eine Klasse, die `Actor` erweitert, als Default-Export aus `base44/actors/<actor-name>/entry.ts`.
Der Ordnername wird zum Actor-Namen im SDK. Details zur Einrichtung findest du unter [Einen Actor erstellen](/de/developers/backend/resources/actors/create-actor).

<ResponseField name="Incoming" type="generic">
  Typisiert die Nachrichten, die der Actor von verbundenen Clients empfängt. Gilt für den
  Parameter `msg` von `handleMessage()`.
</ResponseField>

<ResponseField name="Outgoing" type="generic">
  Typisiert die Nachrichten, die der Actor an verbundene Clients sendet. Gilt für
  `conn.send()` und `broadcast()`.
</ResponseField>

## Runtime-API

Actors importieren die Klasse `Actor` aus dem Modul `base44:runtime/actors`:

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

### Secrets lesen

Verwende `secrets.get()`, um die Umgebungsvariablen deiner App in einem Handler zu lesen. Die Methode gibt den Wert als String zurück oder `undefined`, wenn das Secret nicht gesetzt ist.

Importiere `secrets` aus dem Modul `base44:runtime`:

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

Konfiguriere Secrets über die CLI mit [`secrets set`](/de/developers/references/cli/commands/secrets-set).

Für Aufgaben, die ein Secret brauchen, empfehlen wir den Aufruf einer [Backend-Funktion](/de/developers/backend/resources/backend-functions/overview). Die Funktion liest das Secret und gibt das Ergebnis zurück, sodass der Actor das Secret nie erhält. Einen Beispielablauf findest du unter [Eine Backend-Funktion für Aufgaben mit Secrets aufrufen](/de/developers/backend/resources/actors/sample-flows#call-a-backend-function-for-secret-work).

## Lebenszyklus-Handler

Base44 ruft diese Handler als Reaktion auf Client-Aktivität in der Session auf.
Du implementierst jeweils den Rumpf.
Erfahre mehr darüber, [wie Actors und Clients interagieren](/de/developers/backend/resources/actors/overview#how-actors-and-clients-interact).
Einen Beispielablauf findest du unter [Client-Verbindungen verwalten](/de/developers/backend/resources/actors/sample-flows#manage-client-connections).

<ResponseField name="handleStart" type="method">
  Läuft bei jeder Aktivierung einer Session, zum Beispiel:

  * Wenn die Session zum ersten Mal erstellt wird.
  * Wenn sich ein Client mit einer inaktiven Session verbindet.
  * Wenn eine Nachricht bei einer inaktiven Session eingeht.
  * Wenn ein geplanter Zeitpunkt erreicht ist.

  Gibt `void` oder ein `Promise<void>` zurück.
</ResponseField>

<ResponseField name="handleConnect" type="method" required>
  Läuft, wenn sich ein Client mit der Session verbindet.
  Du kannst den aktuellen Session-Zustand mit `conn.send()` senden oder die Verbindung mit `conn.reject()` ablehnen.
  Gibt `void` oder ein `Promise<void>` zurück.

  <Expandable title="Parameter">
    <ResponseField name="conn" type="Conn" required>
      Steht für den Client, der sich verbunden hat.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleMessage" type="method" required>
  Läuft, wenn ein verbundener Client eine Nachricht sendet.
  Du kannst die Nachricht validieren, bevor du den Session-Zustand änderst oder auf App-Daten zugreifst.
  Gibt `void` oder ein `Promise<void>` zurück.

  <Expandable title="Parameter">
    <ResponseField name="conn" type="Conn" required>
      Steht für den Client, der die Nachricht gesendet hat.
    </ResponseField>

    <ResponseField name="msg" type="Incoming" required>
      Enthält die vom Client gesendete Nachricht. Das Generic `Incoming` definiert
      den Nachrichtentyp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="handleClose" type="method" required>
  Läuft, wenn ein Client die Verbindung trennt.
  Verwende diesen Handler, um Session-Zustand zu entfernen, der mit der Verbindungs-ID verknüpft ist.
  Eine erneute Verbindung mit derselben ID ersetzt den alten Socket, ohne `handleClose()` auszuführen.
  Gibt `void` oder ein `Promise<void>` zurück.

  <Expandable title="Parameter">
    <ResponseField name="conn" type="Conn" required>
      Steht für den Client, der die Verbindung getrennt hat.
    </ResponseField>
  </Expandable>
</ResponseField>

## Timer-Handler und Einstellungen

Diese Handler und Einstellungen steuern zeitgesteuerte Arbeit in der Session.
Base44 ruft sie auf, wenn ein geplanter Zeitpunkt erreicht ist, nicht als Reaktion auf Client-Aktivität.
Erfahre mehr über [geplante Arbeit](/de/developers/backend/resources/actors/overview#scheduled-work).
Beispielabläufe findest du unter [Ticks ausführen](/de/developers/backend/resources/actors/sample-flows#run-ticks) und [Wakes planen](/de/developers/backend/resources/actors/sample-flows#schedule-wakes).

<ResponseField name="handleTick" type="method" required>
  Läuft einmal pro Intervall, solange `shouldTick()` `true` zurückgibt und die Session mindestens einen Client hat.
  Gibt `void` oder ein `Promise<void>` zurück.
</ResponseField>

<ResponseField name="tickIntervalMs" type="number">
  Legt das Intervall zwischen Ticks in Millisekunden fest. Standardwert ist `100`.
</ResponseField>

<ResponseField name="shouldTick" type="method">
  Gibt einen `boolean` zurück. Gib `true` zurück, damit die Session weiter tickt, oder `false`, um das Ticken zu stoppen. Diese Methode ist synchron.

  Halte diese Methode schnell und frei von Seiteneffekten. Base44 ruft sie nach jeder Verbindung, Nachricht, Trennung und jedem Tick auf.
</ResponseField>

<ResponseField name="handleWake" type="method">
  Läuft einmal, wenn ein mit `schedule()` festgelegter Zeitpunkt erreicht ist.
  Gibt `void` oder ein `Promise<void>` zurück.

  <Expandable title="Parameter">
    <ResponseField name="key" type="string" required>
      Enthält den an `schedule()` übergebenen Schlüssel.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="schedule" type="method">
  Plant eine einmalige Ausführung von `handleWake()` zu einem festgelegten Zeitpunkt.
  Gibt ein `Promise` zurück, das erfüllt wird, nachdem Base44 den Zeitplan gespeichert hat.
  Der Zeitplan übersteht Leerlaufphasen und kann eine inaktive Session starten.
  Ein erneuter Aufruf mit demselben Schlüssel ersetzt den geplanten Zeitpunkt.

  <Expandable title="Parameter">
    <ResponseField name="key" type="string" required>
      Identifiziert den geplanten Wake. Wird an `handleWake()` übergeben, wenn der Wake ausgelöst wird.
    </ResponseField>

    <ResponseField name="at" type="number | Date" required>
      Legt fest, wann `handleWake()` läuft. Verwende ein `Date`-Objekt oder Millisekunden
      seit dem 1. Januar 1970.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="cancelSchedule" type="method">
  Bricht den geplanten Wake ab, der mit einem Schlüssel verknüpft ist.
  Gibt ein `Promise` zurück, das erfüllt wird, nachdem Base44 den Zeitplan entfernt hat.

  <Expandable title="Parameter">
    <ResponseField name="key" type="string" required>
      Gibt den an `schedule()` übergebenen Schlüssel an.
    </ResponseField>
  </Expandable>
</ResponseField>

## Verbindungen

Diese Eigenschaften und Methoden stehen im Objekt `conn` zur Verfügung, das an Lebenszyklus-Handler mit Client-Bezug übergeben wird.
Verwende sie, um die Client-Identität zu lesen, Nachrichten zu senden und die Verbindung zu verwalten.
Einen Überblick über Nachrichten findest du unter [Echtzeitnachrichten](/de/developers/backend/resources/actors/overview#realtime-messages).
Einen Beispielablauf findest du unter [Client-Verbindungen verwalten](/de/developers/backend/resources/actors/sample-flows#manage-client-connections).

<Note>
  `conn` ist das Backend-Ende des WebSockets, und `Connection` im Client ist das andere Ende desselben Sockets. Verwende `conn` in der Actor-Klasse. Das Client-Objekt findest du in der `actors` SDK-Referenz.
</Note>

<ResponseField name="conn.id" type="string">
  Identifiziert diese Verbindung. Entspricht der ID, die der Client beim Verbinden übergeben hat,
  oder einer vom SDK generierten ID.
</ResponseField>

<ResponseField name="conn.identity" type="object">
  Identifiziert den Client dieser Verbindung. Bei allen
  Verbindungen vorhanden.

  <Expandable title="Eigenschaften">
    <ResponseField name="type" type="string" required>
      Enthält `authenticated` oder `anonymous`.
    </ResponseField>

    <ResponseField name="userId" type="string">
      Identifiziert den angemeldeten Client. Vorhanden, wenn `type`
      `authenticated` ist.
    </ResponseField>

    <ResponseField name="anonymousId" type="string">
      Identifiziert den anonymen Client. Vorhanden, wenn `type` `anonymous` ist.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.send" type="method">
  Sendet eine Nachricht an diese Verbindung. Gibt `void` zurück.

  <Expandable title="Parameter">
    <ResponseField name="data" type="Outgoing" required>
      Enthält die Nachricht, die an diese Verbindung gesendet wird. Das Generic `Outgoing` definiert den Nachrichtentyp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="conn.reject" type="method">
  Lehnt eine Verbindung in `handleConnect()` ab. Gibt `void` zurück.

  <Expandable title="Parameter">
    <ResponseField name="code" type="number" required>
      Gibt den an den Client gesendeten Statuscode an.
    </ResponseField>

    <ResponseField name="reason" type="string" required>
      Beschreibt, warum der Actor die Verbindung abgelehnt hat.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="broadcast" type="method">
  Sendet eine Nachricht an jede aktive Verbindung in der Session. Gibt `void` zurück.

  <Expandable title="Parameter">
    <ResponseField name="data" type="Outgoing" required>
      Enthält die Nachricht, die an jede Verbindung in der Session gesendet wird. Das Generic `Outgoing` definiert den Nachrichtentyp.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="getConnections" type="method">
  Gibt ein Array der aktiven `conn`-Objekte in der Session zurück. Verwende diese Methode in
  `handleStart()`, um wiederhergestellte Daten den Clients zuzuordnen, die während einer
  Leerlaufphase verbunden geblieben sind.
</ResponseField>

<ResponseField name="this.instanceId" type="string">
  Eigenschaft auf Session-Ebene. Enthält die Session-ID, mit der der Client
  diese Session erreicht hat.
</ResponseField>

## Speicher

Verwende `this.storage`, um Session-Daten zu lesen und zu schreiben. Anders als Klassenfelder übersteht der Speicher Leerlaufphasen. Wie du zwischen Speicher und Klassenfeldern wählst, erfährst du unter [Speicher](/de/developers/backend/resources/actors/overview#storage). Einen Beispielablauf findest du unter [Session-Daten persistieren](/de/developers/backend/resources/actors/sample-flows#persist-session-data).

<ResponseField name="this.storage.get" type="method">
  Ruft einen Wert über seinen Schlüssel ab. Gibt ein `Promise` zurück, das mit dem gespeicherten
  Wert aufgelöst wird, oder mit `undefined`, wenn der Schlüssel nicht existiert.

  <Expandable title="Parameter">
    <ResponseField name="key" type="string" required>
      Gibt den abzurufenden Schlüssel an.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.put" type="method">
  Speichert einen Wert unter einem Schlüssel. Ersetzt den bereits unter dem Schlüssel gespeicherten Wert. Gibt
  ein `Promise` zurück, das erfüllt wird, wenn der Schreibvorgang abgeschlossen ist.

  <Expandable title="Parameter">
    <ResponseField name="key" type="string" required>
      Gibt den zu speichernden Schlüssel an.
    </ResponseField>

    <ResponseField name="value" type="unknown" required>
      Gibt den JSON-kompatiblen Wert an, der gespeichert wird.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.delete" type="method">
  Entfernt einen Wert über seinen Schlüssel. Gibt ein `Promise` zurück, das mit `true` aufgelöst wird, wenn der
  Schlüssel existierte, andernfalls mit `false`.

  <Expandable title="Parameter">
    <ResponseField name="key" type="string" required>
      Gibt den zu entfernenden Schlüssel an.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="this.storage.deleteAll" type="method">
  Entfernt alle gespeicherten Daten der Session. Gibt ein `Promise` zurück, das erfüllt wird, wenn
  der Speicher leer ist. Eine spätere Verbindung startet mit demselben leeren Speicher wie eine
  neue Session.
</ResponseField>

## Zugriff auf Entitäten

Verwende `this.client` und `this.client.asServiceRole`, um in einem Actor-Handler App-Entitäten zu lesen und zu schreiben. Einen Beispielablauf findest du unter [Entitätsdaten aus einer Session schreiben](/de/developers/backend/resources/actors/sample-flows#write-entity-data-from-a-session).

<ResponseField name="this.client" type="Base44Client">
  Stellt einen App-Client bereit, der auf diese Session beschränkt ist. Dieser Client verwendet anonyme
  Authentifizierung. Der Zugriff auf Entitäten folgt daher denselben Regeln wie bei einem abgemeldeten
  Client, und er liest Produktionsdaten.
</ResponseField>

<ResponseField name="this.client.asServiceRole" type="Base44Client">
  Bietet erweiterten Zugriff, der die Sicherheit auf Zeilenebene umgeht. Validiere Nachrichten,
  bevor du diesen Client verwendest. Gestalte Schreibvorgänge wiederholbar, da die Session einen Handler
  nach einem Fehler erneut ausführen kann.
</ResponseField>

## Siehe auch

* [Actors – Übersicht](/de/developers/backend/resources/actors/overview): Konzepte und Terminologie
* [Actors – Beispielabläufe](/de/developers/backend/resources/actors/sample-flows): Lebenszyklus, Timer, Verbindungen, Speicher, Entitäten und Backend-Funktionen
* [`actors` SDK-Referenz](/de/developers/references/sdk/docs/type-aliases/actors): API des Client-SDK
* [`secrets set`](/de/developers/references/cli/commands/secrets-set): Umgebungsvariablen über die CLI konfigurieren

<Note>Diese Seite wurde mit KI übersetzt. Die genauesten und aktuellsten Informationen findest du in der [englischen Version](/). </Note>


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