Knuddels User Apps - API Dokumentation

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

    • Knuddels
    User App Entwicklung
    API Dokumentation
    UserPersistenceNumbers

    UserPersistenceNumbers Klasse

    Modul: Persistence

    Mit dieser Klasse ist es möglich nicht User-spezifische Abfragen auf die UserPersistence auszuführen.

    Übersicht

    Methoden

    Methoden

    addNumber

    (
    • key
    • value
    • [parameters]
    )
    Number static

    Addiert einen Wert für Einträge mit einem bestimmten key in der UserPersistence.
    Hinweis: Da diese Methode ein Batch-Update ist werden keine Change-Listener (ToplistRankChangeEvent, ToplistLabelChangeEvent) ausgelöst.

    Parameter:

    • key String

      Name des keys, der betrachtet werden soll

    • value Number

      Wert der addiert werden soll

    • [parameters] Object optional

      Objekt, mit dem bestimmt werden kann, welche Einträge betrachtet werden sollen

      • [minimumValue] Number optional

        Mindestwert, den der Eintrag haben muss, um für die Änderung in Betracht zu kommen

      • [maximumValue] Number optional

        Höchstwert, den der Eintrag haben darf, um für die Änderung in Betracht zu kommen

      • [targetUsers] User[] optional

        Nutzer, auf die die Abfrage limitiert werden soll. Achtung: Es wird keine Änderung vorgenommen, falls der Nutzer für diesen key keinen Eintrag hat

    Rückgabewert:

    Number:

    Anzahl der Einträge, die geändert wurden

    Beispiel:

    UserPersistenceNumbers.addNumber('gold', 100, {
    minimumValue: 0,
    maximumValue: 500
});

    deleteAll

    (
    • key
    )
    Number static

    Löscht alle gespeicherten Zahlen-Werte für den übergebenen key.

    Parameter:

    Rückgabewert:

    Number:

    Anzahl der gelöschten Einträge

    Beispiel:

    var deleted = UserPersistenceNumbers.deleteAll('knuddelSpent');

    each

    (
    • key
    • callback
    • [parameters]
    )
    static

    Ruft eine Funktion für alle Nutzer auf, die einen bestimmten key in der UserPersistence gesetzt haben. Hierbei greifen die übergebenen Filter.

    Parameter:

    • key String
    • callback Function

      wird asynchron für jeden Eintrag aufgerufen. Wenn diese Methode false returned, dann wird für alle weiteren Einträge der callback nicht aufgerufen.

    • [parameters] Object optional
      • [ascending] Boolean optional

        Entscheidet, ob numerisch aufwärts (true, default) oder abwärts (false) sortiert werden soll.

      • [minimumValue] Number optional
      • [maximumValue] Number optional
      • [maximumCount] Number optional

        Maximale Anzahl an Elementen, für die each aufgerufen werden soll.

      • [onStart] Function optional

        Methode, die aufgerufen wird, bevor damit begonnen wird für jedes Element die callback-Methode aufzurufen.

      • [onEnd] Function optional

        Methode, die aufgerufen wird, nachdem für jedes Element die callback-Methode aufgerufen wurde oder die callback-Methode false returned hat.

      • [online] Boolean optional

        Verfügbar ab Version AppServer 20200525-192452

        Wenn angegeben, so wird der callback nur für User mit dem entsprechenden Online Status aufgerufen (so wie user.isOnline() == online). Es wird aber empfohlen anstatt user.isOnline() diesen Parameter zu verwenden, da dieser intern optimiert ist und nur die passenden User überhaupt lädt.

    Beispiel:

    UserPersistenceNumbers.each('points', function(user, value, index, totalCount, key) {
    var place = index + 1;
    user.sendPostMessage('Toplistenplatzierung', 'Gratulation. Du hast diesen Monat den ' + place + '. Platz gemacht.');
    return place <= 10;
}, { ascending: false, maximumCount: 10 });

    getAllKeys

    (
    • [filterKey]
    )
    String[] static

    Verfügbar ab Version AppServer 82483

    Liefert alle keys, die für User in der Persistence gespeichert wurden.

    Parameter:

    • [filterKey] String optional

      Zeichenkette, die im key vorkommen muss, damit sie für die Rückgabe relevant ist

    Rückgabewert:

    String[]:

    Liste mit allen keys

    Beispiel:

    var allKeys = UserPersistenceNumbers.getAllKeys(); // i.e.: [ 'points', 'knuddelLost' ]

    getCount

    (
    • key
    • [parameters]
    )
    Number static

    Liefert die Anzahl aller unterschiedlichen Nutzer, die Werte für einen bestimmten key gespeichert haben. Hierbei kann optional der Wertebereich über die parameters eingegrenzt werden.

    Parameter:

    • key String
    • [parameters] Object optional

      Objekt, das optionale Parameter zum eingrenzen beinhaltet.

      • [minimumValue] Number optional
      • [maximumValue] Number optional

    Rückgabewert:

    Number:

    Beispiel:

    var usersPlayed = UserPersistenceNumbers.getCount('usersPlayed');

    getNicksByKey

    (
    • key
    • callback
    )

    Verfügbar ab Version AppServer 20201113-145716, ChatServer 20201113-145716

    Liefert ein Array von Nicks für einen bestimmten key.

    Parameter:

    Beispiel:

    UserPersistenceNumbers.getNicksByKey(
        "playedGame",
        function(nicks) {
            KnuddelsServer
                .getDefaultBotUser()
                .sendPublicMessage(JSON.stringify(nicks))
        }
    );

    getPosition

    (
    • key
    • user|userId
    • [parameters]
    )
    Number static

    Liefert die absolute Position des Nutzers in der Liste. Die Position ist im Gegensatz zum Rang immer eindeutig.

    Bei gleichem Wert hat der Nutzer die höhere Position, der zuerst einen Eintrag in der Persistenz hatte.

    Mit der Methode getRank kann man den Rang des Nutzers herausfinden. Dieser ist identisch, wenn unterschiedliche Nutzer denselben Wert haben.

    Parameter:

    • key String
    • user|userId User | Number
    • [parameters] Object optional
      • [ascending] Boolean optional

        Entscheidet, ob numerisch aufwärts (true, default) oder abwärts (false) sortiert werden soll.

      • [minimumValue] Number optional

    Rückgabewert:

    Number:

    Beispiel:

    var position = UserPersistenceNumbers.getPosition('points', user, {
    ascending: false
}); // i.e.: 2

    getRank

    (
    • key
    • user|userId
    • [parameters]
    )
    Number static

    Liefert den Rang des Nutzers. Der Rang ist nicht eindeutig. Bei gleicher Punktzahl haben Nutzer denselben Rang. Mit der Methode getPosition kann man die Position eindeutige Position, statt des Ranges herausfinden.

    Parameter:

    • key String
    • user|userId User | Number
    • [parameters] Object optional
      • [ascending] Boolean optional

        Entscheidet, ob numerisch aufwärts (true, default) oder abwärts (false) sortiert werden soll.

      • [minimumValue] Number optional

    Rückgabewert:

    Number:

    Beispiel:

    var rank = UserPersistenceNumbers.getRank('points', user, {
    ascending: false
}); // i.e.: 1

    getSortedEntries

    (
    • key
    • [parameters]
    )
    UserPersistenceNumberEntry[] static

    Liefert ein Array mit UserPersistenceNumberEntry-Objekten für einen bestimmten key. Hierdurch kann beispielsweise eine blätterbare Topliste abgebildet werden.

    Parameter:

    • key String
    • [parameters] Object optional
      • [ascending] Boolean optional

        Entscheidet, ob numerisch aufwärts (true, default) oder abwärts (false) sortiert werden soll.

      • [count] Number optional

        Anzahl der Einträge (default 25, maximal 100)

      • [page] Number optional

        Seite, die abgerufen werden soll (default 0)

      • [minimumValue] Number optional
      • [maximumValue] Number optional

    Rückgabewert:

    UserPersistenceNumberEntry[]:

    Gefundene Elemente - falls keine Elemente vorhanden sind ist das Array leer.

    Beispiel:

    var bestUsers = UserPersistenceNumbers.getSortedEntries('points', {
    ascending: false,
    count: 10,
});

    getSortedEntriesAdjacent

    (
    • key
    • user|userId
    • [parameters]
    )
    UserPersistenceNumberEntry[] static

    Liefert ein Array mit UserPersistenceNumberEntry-Objekten für einen bestimmten key. Hierbei werden die nähesten Elemente gewählt, die am übergebenen User/UserId liegen.

    Beispiel: Der Nutzer ist in der Liste auf Position 20, dann werden die Resultate von 14-24 bei einem Count von 10 ausgegeben. Beispiel: Der Nutzer ist in der Liste auf Position 3, dann werden die Resultate von 1-10 bei einem Count von 10 ausgegeben.

    Parameter:

    • key String
    • user|userId User | Number
    • [parameters] Object optional
      • [ascending] Boolean optional

        Entscheidet, ob numerisch aufwärts (true, default) oder abwärts (false) sortiert werden soll.

      • [count] Number optional

        Anzahl der Einträge (default 25, maximal 100)

    Rückgabewert:

    UserPersistenceNumberEntry[]:

    Gefundene Elemente - falls keine Elemente vorhanden sind ist das Array leer.

    Beispiel:

    var toplistForUser = UserPersistenceNumbers.getSortedEntriesAdjacent('points', user, {
    ascending: false,
    count: 10,
});

    getSum

    (
    • key
    )
    Number static

    Liefert die Summe aller via UserPersistence gespeicherten Zahlen für den übergebenen key.

    Parameter:

    Rückgabewert:

    Number:

    Summe

    Beispiel:

    var totalKnuddelSpent = UserPersistenceNumbers.getSum('knuddelSpent');

    getUserIdsByKey

    (
    • key
    • callback
    )

    Verfügbar ab Version AppServer 20201113-145716, ChatServer 20201113-145716

    Liefert ein Array von UserIds für einen bestimmten key.

    Parameter:

    Beispiel:

    UserPersistenceNumbers.getUserIdsByKey(
        "playedGame",
        function(userIds) {
            KnuddelsServer
                .getDefaultBotUser()
                .sendPublicMessage(JSON.stringify(userIds))
        }
    );

    updateKey

    (
    • oldKeyName
    • newKeyName
    )
    Number static

    Ändert einen bestimmten key bei allen UserPersistence.

    Parameter:

    • oldKeyName String

      Name des keys vor der Änderung

    • newKeyName String

      Name des keys nach der Änderung. Wird dieser Name bereits genutzt, so wirft die Methode eine Exception.

    Rückgabewert:

    Number:

    Anzahl der aktualisierten Nutzer

    Beispiel:

    var keyChangeCount = UserPersistenceNumbers.updateKey('foo', 'bar');

    updateValue

    (
    • key
    • oldValue
    • newValue
    )
    Number static

    Ändert alle Werte für einen bestimmten key, die vorher einen bestimmten anderen Wert hatten in der UserPersistence.
    Hinweis: Da diese Methode ein Batch-Update ist werden keine Change-Listener (ToplistRankChangeEvent, ToplistLabelChangeEvent) ausgelöst.

    Parameter:

    • key String

      Name des keys, der betrachtet werden soll

    • oldValue Number

      Wert der aktualisiert werden soll

    • newValue Number

      Wert nach der Änderung

    Rückgabewert:

    Number:

    Anzahl der Einträge, die geändert wurden

    Beispiel:

    UserPersistenceNumbers.updateValue('points', 0, 1000);