> ## 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: Beispielabläufe

> Beispielabläufe für Lebenszyklus-Handler, Timer, Verbindungen, Speicher, Entitäten und Backend-Funktionen

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

Nutze diese Beispielabläufe als Ausgangspunkt für deine Implementierung.

## Einen Client mit einer Session verbinden

Wenn das Frontend einer Live-Session beitreten, Nachrichten vom Actor empfangen und Nachrichten an den Actor senden soll, verbinde einen Client mit einer Actor-Session.

**So verbindest du einen Client mit einer Session:**

1. Rufe [`base44.actors.ActorName(sessionId)`](/de/developers/references/sdk/docs/type-aliases/actors) auf, um die Session auszuwählen.
2. Rufe [`.connect()`](/de/developers/references/sdk/docs/type-aliases/actors#connect) auf, um die WebSocket-Verbindung zu öffnen.
3. Rufe [`conn.subscribe()`](/de/developers/references/sdk/docs/type-aliases/actors#subscribe) auf, um einen Listener für Nachrichten vom Actor zu registrieren.
4. Rufe [`conn.send()`](/de/developers/references/sdk/docs/type-aliases/actors#send) auf, um eine Nachricht an den Actor zu senden.

Das folgende Beispiel verbindet sich mit einer `chatRoom`-Actor-Session, hört auf Nachrichten und sendet eine Nachricht:

```typescript theme={null}
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" });
```

Mehr über Verbindungen erfährst du unter [Verbindungen](/de/developers/backend/resources/actors/reference#connections).

## Ticks ausführen

Wenn sich Arbeit in einem Intervall wiederholen soll, während Clients in der Session sind, führe Ticks aus. Beispiele sind das Broadcasten des Spielzustands oder das Aktualisieren eines Runden-Timers.

**So führst du Ticks aus:**

1. Setze [`tickIntervalMs`](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings) auf die Intervalllänge in Millisekunden.
2. Implementiere [`shouldTick()`](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings) so, dass es `true` zurückgibt, um weiter zu ticken, und `false`, um zu stoppen.
3. Führe in [`handleTick()`](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings) die Arbeit für jedes Intervall aus.

Das folgende Beispiel tickt jede Sekunde, solange mindestens zwei Clients in der Session sind. Bei jedem Tick sendet es einen Countdown per Broadcast:

```typescript theme={null}
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 });
  }
}
```

Mehr über Ticks erfährst du unter [Timer-Handler und Einstellungen](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings).

## Wakes planen

Wenn Arbeit einmalig zu einem bestimmten Zeitpunkt laufen soll, egal ob die Session aktiv oder inaktiv ist, plane einen Wake. Beispiele sind das Beenden eines Zugs nach 30 Sekunden oder das Schließen einer leeren Lobby.

**So planst du einen Wake:**

1. Rufe [`schedule()`](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings) mit einem Schlüssel und einem Zeitpunkt auf, um den Wake zu planen.
2. Prüfe in [`handleWake()`](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings) den Schlüssel und führe die Arbeit für diesen Wake aus.
3. Wenn der Wake nicht mehr gilt, rufe [`cancelSchedule()`](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings) mit dem Schlüssel auf.

Das folgende Beispiel plant ein Zug-Timeout, wenn ein Zug beginnt. Wenn das Timeout ausgelöst wird, sendet es eine Nachricht per Broadcast:

```typescript theme={null}
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" });
    }
  }
}
```

Mehr über Wakes erfährst du unter [Timer-Handler und Einstellungen](/de/developers/backend/resources/actors/reference#timer-handlers-and-settings).

## Client-Verbindungen verwalten

Wenn du festlegen musst, wer einer Session beitreten darf, einem bestimmten Client antworten oder alle Clients in der Session erreichen willst, verwalte Client-Verbindungen.

**So verwaltest du Client-Verbindungen:**

1. Prüfe in [`handleConnect()`](/de/developers/backend/resources/actors/reference#lifecycle-handlers) die Eigenschaft [`conn.identity`](/de/developers/backend/resources/actors/reference#connections) und rufe [`conn.reject()`](/de/developers/backend/resources/actors/reference#connections) auf, um einen Client abzulehnen.
2. Rufe [`conn.send()`](/de/developers/backend/resources/actors/reference#connections) auf, um nur diesem Client zu antworten.
3. Rufe in [`handleMessage()`](/de/developers/backend/resources/actors/reference#lifecycle-handlers) [`broadcast()`](/de/developers/backend/resources/actors/reference#connections) auf, um jeden verbundenen Client zu erreichen. Um den Absender zu identifizieren, füge Felder aus `conn` in die Nachricht ein.

Das folgende Beispiel lehnt anonyme Clients ab, sendet dem verbindenden Client den Verlauf und sendet Nachrichten mit der Nutzer-ID des Absenders per Broadcast:

```typescript theme={null}
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 });
}
```

Mehr über Verbindungen erfährst du unter [Verbindungen](/de/developers/backend/resources/actors/reference#connections).

## Session-Daten persistieren

Wenn Werte eine Leerlaufphase überstehen müssen, persistiere Session-Daten. Beispiele sind ein Spielbrett, eine Verlaufsliste oder der aktuelle Zug.

**So persistierst du Session-Daten:**

1. Lade in [`handleStart()`](/de/developers/backend/resources/actors/reference#lifecycle-handlers) Werte aus [`this.storage`](/de/developers/backend/resources/actors/reference#storage) in Klassenfelder.
2. Rufe nach jeder Änderung [`this.storage.put()`](/de/developers/backend/resources/actors/reference#storage) auf, um den aktualisierten Wert zu speichern.
3. Um die Session zurückzusetzen, rufe [`this.storage.delete()`](/de/developers/backend/resources/actors/reference#storage) oder [`this.storage.deleteAll()`](/de/developers/backend/resources/actors/reference#storage) auf.

Das folgende Beispiel lädt beim Start ein Spielbrett und speichert es nach jedem Zug. Wenn der letzte Client die Verbindung trennt, leert es den Speicher:

```typescript theme={null}
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();
  }
}
```

Mehr über Speicher erfährst du unter [Speicher](/de/developers/backend/resources/actors/reference#storage).

## Entitätsdaten aus einer Session schreiben

Wenn die Session App-Datensätze erstellen oder aktualisieren muss, schreibe Entitätsdaten. Beispiele sind ein Endstand oder eine abgeschlossene Bestellung.

**So schreibst du Entitätsdaten aus einer Session:**

1. Validiere die eingehende Nachricht vor dem Schreiben.
2. Lies die Nutzer-ID aus [`conn.identity.userId`](/de/developers/backend/resources/actors/reference#connections).
3. Verwende [`this.client.asServiceRole`](/de/developers/backend/resources/actors/reference#entity-access) für erweiterten Zugriff. Schreibe mit einem stabilen Schlüssel, etwa der Session-ID. So aktualisiert ein wiederholter Handler denselben Datensatz.

Das folgende Beispiel speichert einen Endstand für den authentifizierten Client. Ein späteres Speichern für dieselbe Session aktualisiert diesen Datensatz:

```typescript theme={null}
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);
  }
}
```

Mehr über den Zugriff auf Entitäten erfährst du unter [Zugriff auf Entitäten](/de/developers/backend/resources/actors/reference#entity-access).

## Eine Backend-Funktion für Aufgaben mit Secrets aufrufen

Actors können App-Secrets mit [`secrets.get()`](/de/developers/backend/resources/actors/reference#read-secrets) lesen. Wenn ein Handler eine Aufgabe mit einem Secret ausführen muss, etwa eine externe API mit einem API-Schlüssel aufrufen, 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, niemals das Secret.

**So rufst du eine Backend-Funktion aus einem Actor auf:**

1. Erstelle eine Backend-Funktion, die das Secret mit `secrets.get()` liest, die Aufgabe erledigt und das Ergebnis zurückgibt.
2. Rufe in einem Handler [`this.client.functions.invoke()`](/de/developers/references/sdk/docs/interfaces/functions#invoke) mit dem Funktionsnamen und den zu sendenden Daten auf.
3. Verwende das Ergebnis in deiner Session, etwa indem du es per Broadcast an verbundene Clients sendest.

Das folgende Beispiel zeigt eine Backend-Funktion, die einen API-Schlüssel liest und eine Übersetzung zurückgibt:

```typescript theme={null}
// 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 });
}
```

Das folgende Beispiel ruft diese Funktion aus einem Actor auf und sendet das Ergebnis per Broadcast:

```typescript theme={null}
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 });
  }
}
```

## Siehe auch

* [Actors – Übersicht](/de/developers/backend/resources/actors/overview): Konzepte und Terminologie
* [Einen Actor erstellen](/de/developers/backend/resources/actors/create-actor): Actor-Dateien und eine minimale Klasse
* [Actors – Dateien und Code](/de/developers/backend/resources/actors/reference): Vollständige API der Backend-Klasse
* [`actors deploy`](/de/developers/references/cli/commands/actors-deploy): Lokale Actors deployen

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