Knuddels User Apps - API Dokumentation

  • Dokumentation für Version 20240419-122957 (ChatServer: 20240419-122957)

    • Knuddels
    User App Entwicklung
    API Dokumentation
    KnuddelsServer

    KnuddelsServer Klasse

    Modul: Core

    KnuddelsServer ist die 'Einstiegsklasse'. Mit den statischen Methoden des KnuddelsServer erhält man Zugriff auf viele Objekte und Klassen, die im Verlauf der App-Entwicklung benötigt werden.

    Übersicht

    Methoden

    Methoden

    canAccessUser

    (
    • userId
    )
    Boolean Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getUserAccess().mayAccess(userId)

    Parameter:

    Rückgabewert:

    Boolean:

    createKnuddelPot

    (
    • knuddelAmount
    • [params]
    )
    KnuddelPot Veraltet static

    Veraltet: Diese Methode ist veraltet, da {{#crossLink "KnuddelPot"}}KnuddelPot{{/crossLink}} nicht mehr unterstützt wird. Die Methode gibt immer <code>null</code> zurück.

    Erzeugt einen KnuddelPot.

    Ist ein KnuddelPot 30 Minuten nach dem Erzeugen noch nicht gesealt, so wird vom Server automatisch ein refund ausgelöst.

    Parameter:

    • knuddelAmount KnuddelAmount
    • [params] Object optional
      • [payoutTimeoutMinutes] Number optional

        Anzahl der Minuten nachdem der Pot spätestens ausgezahlt wird. Der Standardwert ist 720 Minuten (12 Stunden). Der erlaubte Minimalwert ist 1 Minute und der erlaubte Maximalwert 10.800 Minuten (7 Tage).

      • [shouldSealPot] Function optional

        Methode, die nach dem erfolgreichen Hinzufügen eines Participants aufgerufen wird. Gibt man hier als return-value true an, so wird der Pot geschlossen. Diese Callback-Methode erhält als ersten Parameter den KnuddelPot.

      • [onPotSealed] Function optional

        Diese Methode wird aufgerufen, sobald der Pot erfolgreich mit shouldSealPot oder knuddelPot.seal() gesealt wurde. Diese Callback-Methode erhält als ersten Parameter den KnuddelPot.

    Rückgabewert:

    KnuddelPot:

    Beispiel:

    var knuddelAmount = KnuddelAmount.fromKnuddel(1);
var knuddelPot = KnuddelsServer.createKnuddelPot(knuddelAmount, {
    onPotSealed: function(pot)
    {
        // Tun, was getan werden soll, nachdem der KnuddelPot gesealt wurde.
    },
    shouldSealPot: function(pot)
    {
        // Entscheiden, ob der KnuddelPot geschlossen werden soll.
        return pot.getParticipants().length >= 2;
    },
    payoutTimeoutMinutes: 5
});

    execute

    (
    • fileName
    )
    static

    Führt das angegebene Script aus. Vergleichbar mit require(), jedoch kann es wiederholt verwendet/ausgeführt werden. Dies kann z.B. in Verbindung mit RootAppInstance.updateAppFiles() benutzt werden um Teile der App im laufenden Betrieb auszutauschen bzw. neu zu laden.

    Achtung: Natürlich muss der App-Code dafür entsprechend ausgelegt sein / damit zurecht kommen.

    Parameter:

    Rückgabewert:

    Beispiel:

    KnuddelsServer.execute('my/awesome/script.js');

    getAllKnuddelPots

    () KnuddelPot[] Veraltet static

    Veraltet: Diese Methode ist veraltet, da KnuddelPot nicht mehr unterstützt wird. Die Methode gibt immer ein leeres Array zurück.

    Liefert alle für die App noch verwaltbaren KnuddelPot-Objekte.

    Rückgabewert:

    KnuddelPot[]:

    Beispiel:

    var allknuddelPots = KnuddelsServer.getAllKnuddelPots();

allknuddelPots.forEach(function (knuddelPot)
{
    if (knuddelPot.getState() == KnuddelPotStart.Open)
    {
        knuddelPot.seal();
    }
});

    getAppAccess

    () AppAccess static

    Liefert das AppAccess-Object.

    Rückgabewert:

    AppAccess:

    Beispiel:

    var appAccess = KnuddelsServer.getAppAccess();

var ownInstance = appAccess.getOwnInstance();

    getAppDeveloper

    () User Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getAppAccess().getOwnInstance().getAppInfo().getAppDeveloper()

    Rückgabewert:

    User:

    getAppId

    () String Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getAppAccess().getOwnInstance().getAppInfo().getAppId()

    Rückgabewert:

    String:

    appId

    getAppInfo

    () AppInfo Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getAppAccess().getOwnInstance().getAppInfo()

    Rückgabewert:

    AppInfo:

    getAppManagers

    () User[] Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getAppAccess().getOwnInstance().getAppInfo().getAppManagers()

    Rückgabewert:

    User[]:

    getAppName

    () String Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getAppAccess().getOwnInstance().getAppInfo().getAppName()

    Rückgabewert:

    String:

    Name der App

    getAppProfileEntryAccess

    () AppProfileEntryAccess static

    Liefert das AppProfileEntryAccess-Objekt, über das App-Profileinträge erzeugt und verwaltet werden können.

    Rückgabewert:

    AppProfileEntryAccess:

    Beispiel:

    var appProfileEntryAccess = KnuddelsServer.getAppProfileEntryAccess();

    getAppServerInfo

    () AppServerInfo static

    Liefert die Informationen über den AppServer auf dem die App läuft.

    Rückgabewert:

    AppServerInfo:

    Beispiel:

    var appServerInfo = KnuddelsServer.getAppServerInfo();

var revision = appServerInfo.getRevision();

user.sendPrivateMessage('Der AppServer läuft momentan mit der Revision ' + revision);

    getAppVersion

    () String Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getAppAccess().getOwnInstance().getAppInfo().getAppVersion()

    Rückgabewert:

    String:

    getChannel

    () Channel static

    Liefert den Channel in dem die App läuft.

    Rückgabewert:

    Channel:

    Beispiel:

    var channel = KnuddelsServer.getChannel();

user.sendPrivateMessage('Willkommen im Channel ' + channel);

    getChatServerInfo

    () ChatServerInfo static

    Liefert die Informationen über den ChatServer auf dem die App läuft.

    Rückgabewert:

    ChatServerInfo:

    Beispiel:

    var chatServerInfo = KnuddelsServer.getChatServerInfo();

var revision = chatServerInfo.getRevision();

user.sendPrivateMessage('Der ChatServer läuft momentan mit der Revision ' + revision);

    getDefaultBotUser

    () BotUser static

    Liefert den BotUser, der standardmäßig zur App gehört.

    Rückgabewert:

    BotUser:

    Beispiel:

    var botUser = KnuddelsServer.getDefaultBotUser();

botUser.sendPublicMessage('Hallo, mein Name ist ' + botUser.getProfileLink() + ' und ich bin ein AppBot!');

    getDefaultLogger

    () Logger static

    Liefert den Standard-Logger für diese App. Alles, was geloggt wird, wird vom Nutzer "App-Logs" als private Nachricht zugestellt.

    Rückgabewert:

    Logger:

    Beispiel:

    var logger = KnuddelsServer.getDefaultLogger();

logger.debug('Der Logger wurde aufgerufen.');

    getExternalServerAccess

    () ExternalServerAccess static

    Liefert ein ExternalServerAccess-Objekt, mit dem andere Server angesteuert werden können.

    Rückgabewert:

    ExternalServerAccess:

    Beispiel:

    var externalServerAccess = KnuddelsServer.getExternalServerAccess();

    getFullImagePath

    (
    • imageName
    )
    String static

    Liefert den Pfad eines Bildes zur Integration in der eigenen App. Alle Bilder, die im Ordner /www in der App abgelegt werden können hier referenziert werden.

    Parameter:

    Rückgabewert:

    String:

    Absoluter Pfad zum Einbinden der Grafik

    Beispiel:

    var fullImagePath = KnuddelsServer.getFullImagePath('test.png');

var message = 'Nachricht mit Bild: °>' + fullImagePath + '<°';

user.sendPrivateMessage(message);

    getFullSystemImagePath

    (
    • imageName
    )
    String static

    Liefert den Pfad eines Systembildes zur Integration in der eigenen App. Alle Bilder, die unter http://apps7.knuddels.biz/kimg/ erreichbar sind können hier referenziert werden.

    Parameter:

    Rückgabewert:

    String:

    Absoluter Pfad zum Einbinden der Grafik

    Beispiel:

    var fullSystemImagePath = KnuddelsServer.getFullSystemImagePath('james/sm_james-xx.gif');

var message = 'Oh nein, Sie haben Kenny,... äääh James getötet. °>' + fullSystemImagePath + '<°';

user.sendPrivateMessage(message);

    getKnuddelPot

    (
    • id
    )
    KnuddelPot | Null Veraltet static

    Veraltet: Diese Methode ist veraltet, da {{#crossLink "KnuddelPot"}}KnuddelPot{{/crossLink}} nicht mehr unterstützt wird. Die Methode gibt immer <code>null</code> zurück.

    Liefert den KnuddelPot mit der angegeben id.

    Parameter:

    Rückgabewert:

    KnuddelPot | Null:

    getNickCorrectCase

    (
    • userId
    )
    String Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getUserAccess().getNick(userId)

    Parameter:

    Rückgabewert:

    String:

    getPaymentAccess

    () PaymentAccess static

    Verfügbar ab Version AppServer 108571, ChatServer 108571

    Liefert das PaymentAccess-Objekt, über das Aktionen, die mit Echtgeld zu tun haben, gesteuert werden können.

    Rückgabewert:

    PaymentAccess:

    Beispiel:

    var paymentAccess = KnuddelsServer.getPaymentAccess();

    getPerformanceStats

    () JSON static

    Liefert Performance-Daten über diese App-Instanz zur Analyse von Performance-Problemen.

    • result[0] = Daten der aktuellen, laufenden Minute (unvollständige Minute)
    • result[1] = Daten der Minute davor
    • result[2] = Daten der Minute da davor
    • result[3] = etc.
    Die Anzahl der Minuten kann variieren. Derzeit (als dies geschrieben wird) ist das Maximum 15 Minuten.

    Falls Daten für einen längeren Zeitraum benötigt werden kann folgender Code verwendet werden um diese zu erfassen: 
    setInterval(function() {
    // Logge die Daten der vergangenen Minute als eine Zeile:
    KnuddelsServer.getDefaultLogger().info(JSON.stringify(KnuddelsServer.getPerformanceStats()[1]));
    // Oder logge sie schön formatiert (mit der Hilfsfunktion von unten):
    // KnuddelsServer.getDefaultLogger().info(App.stringify(KnuddelsServer.getPerformanceStats()[1], 2));
    // Alternativ könnten die Daten im Speicher, in der DB oder anderweitig abgespeichert werden.
    // Auch könnten die Daten gefiltert werden, bevor sie geloggt werden um nur interessante Infos zu erfassen.
}, 60000); // 1x pro Minute

    Rückgabewert:

    JSON:

    Ein Array von Arrays mit Objekten mit Performance-Daten (siehe Beispiel).

    Beispiel:

    App.stringify = function(obj, space) { // Hilfsfunktion um JSON.stringify() sortiert auszugeben
    var allKeys = [];
    var seen = {};
    JSON.stringify(obj, function (key, value) {
        if (!(key in seen)) {
            allKeys.push(key);
            seen[key] = null;
        }
        return value;
    });
    allKeys.sort();
    return JSON.stringify(obj, allKeys, space);
}

// [0] = aktuelle (unvollständige) Minute, [1] = die (vollständige) Minute davor
KnuddelsServer.getDefaultLogger().info(App.stringify(KnuddelsServer.getPerformanceStats()[0], 2));

// Ausgabe via "App-Logs":
[
    {
        "hookName": "onUserJoined", // Welcher AppHook war es?
        "source": "main.js:2070", // Code-Stelle, die ausgeführt wurde
        "time": "2021-12-07 16:51", // Zeitpunkt: Welche Minute?
        "values": { // alle diese Werte beziehen sich auf eine Minute
            "calls": 2, // Anzahl Aufrufe dieser Aktion
            "exec": 10, // Summe vergangene Zeit (in ms) für Verarbeitung dieser Aktion
            "execAvg": 5, // Durchschnitt von exec
            "execMax": 6, // Höchstwert von exec
            "memAlloc": 70307, // Summe Speicher-Allokation (in Bytes)
            "memAllocAvg": 35153.5, // Durchschnitt von memAlloc
            "memAllocMax": 40304, // Höchstwert von memAlloc
            "wait": 8, // Summe vergangene Zeit (in ms) für Warten auf Ausführung dieser Aktion
            "waitAvg": 4, // Durchschnitt von wait
            "waitMax": 5 // Höchstwert von wait
        }
    },
    {
        "hookName": "onSlashCommand",
        "slashCommand": "eval", // Name des verarbeiteten Slash-Befehls; nur für onSlashCommand
        "source": "main.js:781",
        "time": "2021-12-07 16:51",
        "values": {
            // siehe oben
        }
    },
    {
        "eventKey": "ping", // Name (type) des verarbeiteten Events; nur für onEventReceived
        "hookName": "onEventReceived",
        "source": "appManager.js:2044",
        "time": "2021-12-07 16:54",
        "values": {
            // siehe oben
        }
    }
]

    getPersistence

    () AppPersistence static

    Liefert die AppPersistence, mit der sich Zahlen, Strings und Javascript-Objekte langfristig und über die Session einer App hinaus gespeichert werden können.

    Rückgabewert:

    AppPersistence:

    Beispiel:

    var appPersistence = KnuddelsServer.getPersistence();

    getToplistAccess

    () ToplistAccess static

    Liefert das ToplistAccess-Objekt, über das Toplisten erzeugt und verwaltet werden können.

    Rückgabewert:

    ToplistAccess:

    Beispiel:

    var toplistAccess = KnuddelsServer.getToplistAccess();

    getUser

    (
    • userId
    )
    User Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getUserAccess().getUserById(userId)

    Parameter:

    Rückgabewert:

    User:

    getUserAccess

    () UserAccess static

    Liefert das UserAccess-Objekt, über das User zugreifbar werden.

    Rückgabewert:

    UserAccess:

    Beispiel:

    var userAccess = KnuddelsServer.getUserAccess();

    getUserId

    (
    • nick
    )
    Number Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getUserAccess().getUserId(nick)

    Parameter:

    Rückgabewert:

    Number:

    isNewAppKnuddelTransferEnabled

    () Boolean static

    Liefert die Information, ob die neuen Knuddel-Transfers mit Tageslimit aktiviert sind. Ist dies der Fall, muss ein Nutzer nicht mehr Knuddel auf ein KnuddelAccount aufladen, um sie in einer App nutzen zu können. Für mehr Informationen siehe KnuddelAccount. Diese Methode ist nur übergangsweise zur Migrierung von bestehenden User-Apps gedacht und wird in Zukunft wieder entfernt. Diese Methode kann nach April 2024 ignoriert werden.

    Rückgabewert:

    Boolean:

    isTestSystem

    () Boolean Veraltet static

    Veraltet: Siehe #getChatServerInfo().isTestSystem()

    Rückgabewert:

    Boolean:

    listFiles

    (
    • path
    )
    String[] static

    Mit dieser Funktion lassen sich alle Dateien und Ordner innerhalb eines Pfades des App-Runtime Ordners auflisten. Ruft man es mit "." oder "/" auf, so bekommt man die Dateien und Ordner auf der obersten Ebene. Zur Unterscheidung haben Ordner einen "/" am Ende, wohingegen Dateien dies nicht haben. Die Ausgabe ist alphabetisch (ignore case) sortiert, jedoch zuerst die Ordner und dann die Dateien. Die Ausgabe ist NICHT rekursiv. Dies kann aber leicht selbst gebaut werden, indem man einfach für jeden Ordner nochmals die Funktion aufruft.

    Parameter:

    Rückgabewert:

    String[]:

    Beispiel:

    var files = KnuddelsServer.listFiles('my/awesome/directory');

    refreshHooks

    () static

    Aktualisiert die Liste der genutzten Hooks. Werden zur Laufzeit chatCommands oder App-Hooks (wie mayJoinChannel) dynamisch erzeugt oder gelöscht, so muss danach refreshHooks() aufgerufen werden, damit diese Änderung wirksam wird.

    Beispiel:

    this.chatCommands['newCommand'] = function (user, params, command)
{
};

KnuddelsServer.refreshHooks();
// Ab hier kann nun /newCommand von den Nutzern benutzt werden

delete this.chatCommands['newCommand'];
KnuddelsServer.refreshHooks();
// Ab hier ist /newCommand nicht mehr verfügbar.

    registerInAppChatMessage

    (
    • chatGroupId
    • sender
    • text
    • receiverUserIds
    )
    static

    Du musst diese Methode jedes Mal verwenden, wenn eine Nachricht in deinem In-App-Chat gesendet wird. Das ist notwendig, um die Moderation von In-App-Chat-Nachrichten zu ermöglichen, ähnlich wie für alle anderen Nachrichten, die auf Knuddels geschrieben werden.

    Überprüfe deine Erlaubnis, einen In-App-Chat zu implementieren

    Knuddels erlaubt UserApps nur dann einen In-App-Chat zu verwenden, wenn es wirklich notwendig für das Funktionieren dieser bestimmten UserApp ist. Wenn du dir unsicher bist, ob du in deinem speziellen Fall einen In-App-Chat bauen darfst, kontaktiere userapps@knuddels.de.

    Sei transparent für die Nutzer

    Sei sehr vorsichtig, dass die Verwendung dieser Methode exakt mit der Wahrnehmung des In-App-Chats durch die Nutzer übereinstimmt. Sonst können unschöne und verwirrende Situationen für Moderatoren und Nutzer entstehen. Nutzer sollten immer genau wissen, wann sie "eine Nachricht senden" und welchen Inhalt sie hat. Es ist verboten, Nachrichten zu registrieren, deren Inhalt der Nutzer nicht explizit produziert hat. Das kann im schlimsten Fall mit Perma-Bann und Schließung der App saktioniert werden.

    Verwendung der API

    Du musst alle Nutzer (bzw. deren User-IDs) als receiverUserIds angeben, die von dem Sender als Empfänger beabsichtigt waren. Wenn eine Nachricht zu einer Gruppe von Nutzern (z.B. einem Channel) gesendet wurde, musst du all diese Nutzer als receiverUserIds angeben.

    Du musst auch eine "Chatgruppen-Id" (groupChatId) angeben. Ein "Chatgruppe" kann etwas Ähnliches wie ein Channel auf Knuddels sein, aber das hängt von der Implementierung deiner UserApp ab. Wenn deine UserApp beispielsweise mehrere Spiele gleichzeitig laufen lässt und diese jeweils einen eigenen Chat haben, könnte chatGroupId einfach die ID dieses Spiels (als String) beinhalten (angenommen, deine Spiele haben soetwas wie "IDs"). Die angegebene chatGroupId wird dann zu Moderationszwecken verwendet. (Zum Beispiel wird sie angezeigt, wenn Admins gemeldete Nachrichten überprüfen.)

    Limits

    • Länge von chatGroupId: mind. 3, max. 100 Zeichen
    • Länge von text: mind. 1, max. 5000 Zeichen
    • Länge von receiverUserIds: mind. 1, max. 1000 Empfänger

    Parameter:

    • chatGroupId String

      ID des "Gruppenchats", in dem die Nachricht gesendet wurde (s.o. für Erklärung)

    • sender User

      Der Nutzer, der die Nachricht gesendet hat.

    • text String

      Der Inhalt der Nachricht, exakt so wie der Nutzer sie eingegeben hat.

    • receiverUserIds Number[]

      Die User-IDs aller Empfänger dieser Nachricht (den Sender ausgeschlossen).

    Rückgabewert:

    Beispiel:

     var message = input.value;
 if (message.length <= 5000) {
     KnuddelsServer.registerInAppChatMessage("Haupt-Chat", sender, message,
         [receiver1.getUserId(), receiver2.getUserId()]);
 }

    userExists

    (
    • nick
    )
    Boolean Veraltet static

    Veraltet: nun verfügbar via KnuddelsServer.getUserAccess().exists(nick)

    Parameter:

    Rückgabewert:

    Boolean: