App Lifecycle

App-Lifecycle und Hooks

Jede UserApp durchläuft einen definierten Lebenszyklus. Über Hooks reagierst du auf Ereignisse wie App-Start, Nutzer-Aktionen oder Nachrichten.

---

Das App-Objekt

Jede UserApp muss ein globales App-Objekt definieren. Darin werden alle Hooks und Chat-Befehle registriert. Das Pattern sieht so aus:

var App = (new function() {

    // --- Hooks ---
    this.onAppStart = function() {
        // App wurde gestartet
    };

    // --- Chat-Befehle ---
    this.chatCommands = {
        hilfe: function(user, params, func) {
            user.sendPrivateMessage('Verfügbare Befehle: /hilfe');
        }
    };

    // --- Hilfsfunktionen (kein this. nötig) ---
    function meineHilfsfunktion() {
        // ...
    }

}());

Wichtig: Hooks und chatCommands werden mit this. definiert. Hilfsfunktionen, die nur intern verwendet werden, können als normale function-Deklarationen innerhalb des Blocks stehen.

---

Lebenszyklus einer App

App installiert
      │
      ▼
 onAppStart()       ← App wird initialisiert (einmalig)
      │
      ▼
 App läuft          ← Events werden verarbeitet
      │
      ▼
 onShutdownApp()    ← App wird gestoppt

Die App läuft, solange der Channel existiert und die App installiert ist. Bei einem Server-Neustart oder App-Update wird die App heruntergefahren und neu gestartet.

---

Alle verfügbaren Hooks

In den folgenden Beispielen wird nur der jeweilige Hook gezeigt. Alle Hooks gehören innerhalb des var App = (new function() { ... }());-Blocks und verwenden this..

App-Lifecycle-Hooks

// Wird einmalig beim Start der App aufgerufen
this.onAppStart = function() {
    KnuddelsServer.getDefaultLogger().info('App gestartet!');
};

// Wird beim Herunterfahren der App aufgerufen
this.onShutdownApp = function() {
    KnuddelsServer.getDefaultLogger().info('App wird gestoppt...');
};

Benutzer-Hooks

// Nutzer betritt den Channel
this.onUserJoined = function(user) {
    KnuddelsServer.getDefaultBotUser().sendPublicMessage(
        'Willkommen, ' + user.getProfileLink() + '!'
    );
};

// Nutzer verlässt den Channel
this.onUserLeft = function(user) {
    KnuddelsServer.getDefaultLogger().info(user.getNick() + ' hat den Channel verlassen.');
};

Nachrichten-Hooks

// Öffentliche Nachricht im Channel
this.onPublicMessage = function(publicMessage) {
    var text = publicMessage.getText();
    var author = publicMessage.getAuthor();
    // Nachricht verarbeiten...
};

// Private Nachricht an den Bot
this.onPrivateMessage = function(privateMessage) {
    var text = privateMessage.getText();
    var author = privateMessage.getAuthor();
    author.sendPrivateMessage('Du hast geschrieben: ' + text);
};

// Öffentliche Action-Nachricht (z.B. "/me tanzt")
this.onPublicActionMessage = function(publicActionMessage) {
    // ...
};

// Öffentliche Event-Nachricht
this.onPublicEventMessage = function(publicEventMessage) {
    // ...
};

Knuddel-Hooks

// Bevor ein Nutzer Knuddel an die App sendet
this.onBeforeKnuddelReceived = function(knuddelTransfer) {
    // Return true um den Transfer zu akzeptieren, false um abzulehnen
    return true;
};

// Nachdem Knuddel empfangen wurden
this.onKnuddelReceived = function(sender, receiver, knuddelAmount, transferReason) {
    sender.sendPrivateMessage('Danke für ' + knuddelAmount.asNumber() + ' Knuddel!');
};

// Wenn das App-Konto Knuddel empfängt
this.onAccountReceivedKnuddel = function(sender, receiver, knuddelAmount, transferReason) {
    // ...
};

// Wenn eine Knuddel-Kauftransaktion abgeschlossen ist
this.onAccountChangedKnuddelAmount = function(user, knuddelAmountOld, knuddelAmountNew) {
    // ...
};

Event-Hooks (Client → Server)

// Events vom Frontend empfangen
this.onEventReceived = function(user, type, data, appContentSession) {
    if (type === "buttonClicked") {
        // data enthält die vom Client gesendeten Daten
        appContentSession.sendEvent('response', { status: 'ok' });
    }
};

Nutzerlöschung (DSGVO)

Wenn ein Nutzer seinen Account löscht, wird dieser Hook aufgerufen. Hier solltest du alle gespeicherten Nutzerdaten bereinigen:

this.onUserDeleted = function(userId) {
    // Nutzerdaten aus der App-Persistence entfernen
    KnuddelsServer.getPersistence().deleteString('user_' + userId);
    KnuddelsServer.getDefaultLogger().info('Daten für User ' + userId + ' gelöscht.');
};

Wichtig: Wenn deine App onUserDeleted implementiert, werden Persistence-Daten und der Zugriff auf gespeicherte Nutzerdaten gelöschter Nutzer automatisch bereinigt. Ohne diesen Hook wird die Bereinigung gedrosselt und erst beim nächsten App-Start nachgeholt.

Inter-App-Hooks

// Event von einer anderen App empfangen
this.onAppEventReceived = function(appInstance, type, data) {
    KnuddelsServer.getDefaultLogger().info(
        'Event von ' + appInstance.getAppInfo().getAppName() + ': ' + type
    );
};

---

Chat-Befehle definieren

Chat-Befehle werden als Objekt auf this.chatCommands definiert:

this.chatCommands = {
    // Befehl: /hilfe
    hilfe: function(user, params, func) {
        user.sendPrivateMessage('Verfügbare Befehle: /hilfe, /start, /stats');
    },

    // Befehl: /start mit Parametern
    start: function(user, params, func) {
        if (params.length === 0) {
            user.sendPrivateMessage('Bitte gib einen Spielmodus an: /start schnell oder /start normal');
            return;
        }
        user.sendPrivateMessage('Spiel startet im Modus: ' + params);
    }
};

Hinweis: Der Befehlsname wird automatisch kleingeschrieben. /Hilfe, /hilfe und /HILFE rufen alle dieselbe Funktion auf.

---

Vollständiges Beispiel

So sieht eine vollständige main.js mit mehreren Hooks und Chat-Befehlen aus:

var App = (new function() {

    this.onAppStart = function() {
        KnuddelsServer.getDefaultLogger().info('App gestartet!');
    };

    this.onShutdownApp = function() {
        KnuddelsServer.getDefaultLogger().info('App wird gestoppt...');
    };

    this.onUserJoined = function(user) {
        KnuddelsServer.getDefaultBotUser().sendPublicMessage(
            'Willkommen, ' + user.getProfileLink() + '!'
        );
    };

    this.onEventReceived = function(user, type, data, appContentSession) {
        if (type === 'ping') {
            appContentSession.sendEvent('pong', { success: true });
        }
    };

    this.chatCommands = {
        hilfe: function(user, params, func) {
            user.sendPrivateMessage('Verfügbare Befehle: /hilfe');
        }
    };

}());

---

Reihenfolge der Hook-Aufrufe

Wenn ein Nutzer den Channel betritt und eine Nachricht schreibt, werden die Hooks in dieser Reihenfolge aufgerufen:

1. onUserJoined(user) – Nutzer ist dem Channel beigetreten
2. onPublicMessage(message) – Wenn er eine öffentliche Nachricht schreibt
3. onEventReceived(user, type, data, session) – Wenn er Events vom Frontend sendet
4. onUserLeft(user) – Nutzer verlässt den Channel

---

API-Referenz

Die vollständige Dokumentation aller Hooks und Methoden findest du in der App-Klasse der API-Dokumentation.

---

← Zurück zur Übersicht