Anzeigen:
Modul: Core

App ist die abstrakte Klasse einer konkreten App, die ein Entwickler schreiben kann. Im eigenen Javascript-Code muss eine Variable mit dem Namen App vorhanden sein, damit eine App lauffähig ist.

Methoden

mayJoinChannel

(
  • user
)
ChannelJoinPermission

Dieses Methode wird aufgerufen, sobald ein Nutzer versucht den Channel zu betreten. Die App kann nun entscheiden, ob der Nutzer den Channel betreten darf.

Hinweis: Um ein responsives User Interface für den Nutzer, der den Channel betreten möchte zu garantieren, muss die App innerhalb von einer Sekunde auf diese Anfrage reagieren, damit ihre Antwort in das Ergebnis einfliesst.

Mit bestimmten Smileyfeatures ist es derzeit trotzdem möglich, den Channel zu betreten. Diese Nutzer können nicht ausgesperrt werden:

  • Channelbesitzer
  • Channelmoderatoren und HZAs
  • Admins (sofern notwendig)
  • Sysadmins
  • User Apps Team (Mitarbeiter von Knuddels)

Ist der Channel mit einem Passwort geschützt und der Nutzer, der versucht den Channel zu betreten kennt das Passwort, so kann er nicht aus dem Channel ausgeschlossen werden.

Parameter:

Rückgabewert:

Beispiel:

this.mayJoinChannel = function(user)
{
  if (user.getAge() < 21)
  {
    return ChannelJoinPermission.denied('Tut mir leid... In professionelle Casinos kommst du erst mit 21.');
  }

  return ChannelJoinPermission.accepted();
};

mayShowPublicActionMessage

(
  • publicActionMessage
)
Boolean

Diese Methode wird jedes Mal aufgerufen, sobald ein Nutzer versucht eine öffentliche Handlung auszuführen. Die App kann nun entscheiden, ob die Handlung ausgeführt werden darf.

Laufen mehrere Apps im selben Channel, so wird die Handlung ausgeführt, sofern alle Apps es erlauben.

Dauert das Fragen aller Apps nach Erlaubnis länger als 10 Sekunden, so wird die Antwort genutzt, die bis dahin gegeben wurde.

Parameter:

Rückgabewert:

Boolean:

true, wenn die Handlung ausgeführt werden soll, false im anderen Fall.

Beispiel:

this.mayShowPublicActionMessage = function(publicActionMessage)
{
    return false;
};

mayShowPublicMessage

(
  • publicMessage
)
Boolean

Diese Methode wird jedes Mal aufgerufen, sobald ein Nutzer versucht eine öffentliche Nachricht zu senden. Die App kann nun entscheiden, ob die Nachricht veröffentlicht werden darf.

Laufen mehrere Apps im selben Channel, so wird die Nachricht veröffentlicht, sofern alle Apps es erlauben.

Dauert das Fragen aller Apps nach Erlaubnis länger als 10 Sekunden, so wird die Antwort genutzt, die bis dahin gegeben wurde.

Parameter:

Rückgabewert:

Boolean:

true, wenn die Nachricht angezeigt werden soll, false im anderen Fall.

Beispiel:

this.mayShowPublicMessage = function(publicMessage)
{
    var showPublicMessage = publicMessage.getText().length > 5;

    if (!showPublicMessage)
    {
        var author = publicMessage.getAuthor();
        author.sendPrivateMessage('Deine Nachricht war etwas kurz und sieht aus wie Spam.');
    }

    return showPublicMessage;
};

onAccountChangedKnuddelAmount

(
  • user
  • knuddelAccount
  • oldKnuddelAmount
  • newKnuddelAmount
)

Diese Methode wird aufgerufen, wenn sich die Anzahl der Knuddel auf einem KnuddelAccount eines User geändert hat.

Parameter:

  • user User

    Nutzer dessen Knuddelwert im Konto sich geändert hat

  • knuddelAccount KnuddelAccount

    in dem sich der Wert verändert hat

  • oldKnuddelAmount KnuddelAmount

    Anzahl der Knuddel, die vorher im KnuddelAccount waren

  • newKnuddelAmount KnuddelAmount

    Anzahl der Knuddel, die jetzt im KnuddelAccount sind

Beispiel:

this.onAccountChangedKnuddelAmount = function(user, knuddelAccount, oldKnuddelAmount, newKnuddelAmount)
{
    var eventPayload = {
        oldKnuddelAmount: oldKnuddelAmount.asNumber(),
        newKnuddelAmount: newKnuddelAmount.asNumber()
    }

    user.sendPrivateMessage('Die Anzahl deiner Knuddel hat sich verändert.');
};

onAccountReceivedKnuddel

(
  • sender
  • receiver
  • knuddelAmount
  • transferReason
  • knuddelAccount
)

Diese Methode wird aufgerufen, wenn ein User Knuddel in seinen KnuddelAccount eingezahlt hat.

Parameter:

  • sender User

    Absender der Knuddel

  • receiver BotUser

    Botnutzer, der die Knuddel erhalten sollte

  • knuddelAmount KnuddelAmount

    Anzahl Knuddel, die in den Account eingezahlt wurden

  • transferReason String

    Grund, der Knuddel-Einzahlung

  • knuddelAccount KnuddelAccount

    Account des Nutzers, vom dem die Knuddel abgezogen werden können

Beispiel:

this.onAccountReceivedKnuddel = function(sender, receiver, knuddelAmount, transferReason, knuddelAccount)
{
    const kNeededKnuddelCount = 10;

    var neededAmount = new KnuddelAmount(kNeededKnuddelCount);

    if (knuddelAccount.hasEnough(neededAmount)) 
    {
        // Auf dem Account sind jetzt genug Knuddel, also kann ein Spiel gestartet werden.
        knuddelAccount.use(neededAmount, 'Dein Einsatz für das Spiel');
    }
    else
    {
        // 10 Knuddel sind erforderlich, also wird der Nutzer auf den Fehlbetrag hingewiesen
        var knuddel = knuddelAccount.getKnuddelAmount().asNumber();
        var missing = kNeededKnuddelCount - knuddel;

        sender.sendPrivateMessage('Ich habe nun ' + knuddel + ' Knuddel von dir. Zum Spielen fehlen noch ' + missing + ' Knuddel.');
    }
};

onAppEventReceived

(
  • appInstance
  • type
  • data
)

Diese Methode wird aufgerufen, wenn aus einer anderen App ein Event mit sendAppEvent versendet wurde.

Parameter:

  • appInstance AppInstance

    Instanz der App, von der das Event kam

  • type String

    Typ, der zur Erkennung mitgesendet wurde

  • data Object

    Daten, die verschickt wurden

Beispiel:

this.onAppEventReceived = function(appInstance, type, data)
{
    // ...
};

onAppStart

()

Diese Methode wird aufgerufen, sobald die App startet. Dies ist der beste Zeipunkt um Werte zu initialisieren und aus der Persistenz zu lesen.

Beispiel:

this.onAppStart = function()
{
    var botUser = KnuddelsServer.getDefaultBotUser();

    botUser.sendPublicMessage('Huiuiui... ich bin erwacht und wieder voll einsatzfähig.');
};

onBeforeKnuddelReceived

(
  • knuddelTransfer
)

Diese Methode wird aufgerufen, wenn ein User Knuddel an den BotUser gesendet hat. Es ist die Aufgabe der App in dieser Methode zu entscheiden, ob sie die Knuddel annimmt oder ablehnt. Wird diese Methode von der App nicht implementiert, so werden Knuddel automatisch akzeptiert. Ist diese Methode implementiert und es treten Fehler (Exceptions, Timeout,...) auf oder der Entwickler entscheidet nicht, was mit den Knuddel geschehen soll, so werden diese vom App-System automatisch an den Absender zurück geschickt.
Wichtig: Zum Zeitpunkt des Aufrufs dieser Methode wurden die Knuddel noch nicht an den BotUser übertragen.

Parameter:

Beispiel:

this.onBeforeKnuddelReceived = function(knuddelTransfer)
{
    if (knuddelTransfer.getSender().isAppDeveloper())
    {
         // Nimmt die Knuddel an und sendet sie an den Bot.
         // Im Anschluss wird onKnuddelReceived aufgerufen.

        knuddelTransfer.accept();
        knuddelTransfer.getSender().sendPrivateMessage('Vielen Dank!');
    }
    else
    {
        if (knuddelPot != null && knuddelTransfer.canAddToPot(knuddelPot))
        {
            // Nimmt die Knuddel an und sendet sie an den KnuddelPot.
            knuddelTransfer.addToPot(knuddelPot);
        }
        else
        {
             // Lehnt die Knuddel ab und sendet sie zurück an den absendenden
             // User oder KnuddelAccount.
            knuddelTransfer.reject('Sorry, Knuddel nehme ich von meinem Herrchen an.');
        }
    }
};

onEventReceived

(
  • user
  • type
  • data
  • appContentSession
)

Diese Methode wird aufgerufen, wenn aus dem HTML User Interface ein Event mit sendEvent() gesendet wurde.

Parameter:

  • user User

    Nutzer durch dessen User Interface das Event gesendet wurde

  • type String

    Typ, der zur Erkennung mitgesendet wurde

  • data Object

    Daten, die verschickt wurden

  • appContentSession AppContentSession

    Session, für die das Event ist (falls HTML User Interface bereits geschlossen ist, dann null)

Beispiel:

this.onEventReceived = function(user, type, data, appContentSession)
{
    if (type == 'greetMe')
    {
        var botUser = KnuddelsServer.getDefaultBotUser();

        botUser.sendPublicMessage('Hallo ' + user.getNick() + '! Willkommen in meinem Channel!');
    }
};

onKnuddelReceived

(
  • sender
  • receiver
  • knuddelAmount
  • transferReason
)

Diese Methode wird aufgerufen, sobald ein BotUser Knuddel von einem User erhalten hat.

Parameter:

  • sender User

    Nutzer, der die Knuddel verschickt hat

  • receiver BotUser

    Botnutzer, der die Knuddel erhalten hat

  • knuddelAmount KnuddelAmount

    Menge der Knuddel, die transferiert worden sind

  • transferReason String
    • GRUND aus dem App-Knuddel-Befehl: /appknuddel BOTNICK:KNUDDEL:GRUND

Beispiel:

this.onKnuddelReceived = function(sender, receiver, knuddelAmount, transferReason)
{
    receiver.sendPublicMessage('Ein großer Dank gebührt ' + sender + ', der soeben ' + knuddelAmount + '  gespendet hat.');
};

onPrepareShutdown

(
  • secondsTillShutdown
)

Diese Methode wird aufgerufen, wenn die App sich darauf vorbereiten soll heruntergefahren zu werden. Als Parameter wird die geschätzte Zeit übergeben, die die App noch hat, bis sie heruntergefahren wird und der Aufruf App/onShutdown:event folgt.

App/onPrepareShutdown:event kann dazu benutzt werden das Nutzererlebnis zu verbessern, sofern eine App heruntergefahren werden muss (bsp. für Updates). Eine Spiele-App könnte z.B. entscheiden, dass sie keine weiteren Spiele eröffnet und den Spielern offener Spiele die Information anzeigt, wie lange das Spiel noch läuft, bevor es unentschieden endet.



Achtung: Die Methode kann im Lebenszyklus einer App mehrfach aufgerufen werden.

Parameter:

  • secondsTillShutdown Number

    Anzahl der Sekunden, bis die App vorraussichtlich heruntergefahren wird

Beispiel:

this.onPrepareShutdown = function(secondsTillShutdown)
{
    var botUser = KnuddelsServer.getDefaultBotUser()

    botUser.sendPublicMessage('Die App fährt in ' + secondsTillShutdown + ' Sekunden herunter.');
};

onPrivateMessage

(
  • privateMessage
)

Diese Methode wird aufgerufen, wenn ein BotUser privat angeschrieben wird.

Parameter:

Beispiel:

this.onPrivateMessage = function(privateMessage)
{
    privateMessage.sendReply('Leider kann ich mit ' + privateMessage.getText() + ' nichts anfangen...');
};

onPublicActionMessage

(
  • publicActionMessage
)

Diese Methode wird aufgerufen, wenn im Channel der App eine öffentliche Handlung durchgeführt wird. Für Handlungen von BotUsern wird diese Methode nicht aufgerufen.

Parameter:

Beispiel:

this.onPublicActionMessage = function(publicActionMessage)
{
    if (publicActionMessage.getText().contains('schlafen'))
    {
        var botUser = KnuddelsServer.getDefaultBotUser();

        var message = publicMessage.getAuthor() + ', ich bin auch müde.';

        botUser.sendPublicMessage(message);
    }
};

onPublicEventMessage

(
  • publicEventMessage
)

Diese Methode wird aufgerufen, wenn im Channel der App eine Event-Nachricht veröffentlicht wird. Für Nachrichten von BotUsern wird diese Methode nicht aufgerufen.

Parameter:

Beispiel:

this.onPublicEventMessage = function(publicEventMessage)
{
    if (publicEventMessage.getText().contains('knuddelt'))
    {
        var botUser = KnuddelsServer.getDefaultBotUser();

        var message = 'Wow, ' + publicEventMessage.getAuthor() + ' hat jemanden geknuddelt!';

        botUser.sendPublicMessage(message);
    }
};

onPublicMessage

(
  • publicMessage
)

Diese Methode wird aufgerufen, wenn im Channel der App eine öffentliche Nachricht geschrieben wird. Für Nachrichten von BotUsern wird diese Methode nicht aufgerufen.

Parameter:

Beispiel:

this.onPublicMessage = function(publicMessage)
{
    if (publicMessage.getText().contains('Zigarette'))
    {
        var botUser = KnuddelsServer.getDefaultBotUser();

        var message = publicMessage.getAuthor() + ', hier wird nicht geraucht.';

        botUser.sendPublicMessage(message);
    }
};

onShutdown

()

Diese Methode wird aufgerufen, wenn eine App beendet wird. Sobald diese Methode aufgerufen wird, steht nur noch ein begrenzter Teil der API zur Verfügung. Die App sollte den kompletten Zustand in der Persistenz speichern, sodass der Zustand beim nächsten App/onAppStart:event wiederhergestellt werden kann.

Während des Shutdowns können asynchrone each-Methoden, wie each und eachAccessibleUser nicht zuverlässig genutzt werden.

Beispiel:

this.onShutdown = function()
{
    var botUser = KnuddelsServer.getDefaultBotUser();

    botUser.sendPublicMessage('Die App fährt jetzt herunter. Ihr könnt vorraussichtlich in Kürze wieder spielen.');
};

onUserDiced

(
  • diceEvent
)

Diese Methode wird aufgerufen, wenn ein User im Channel der App über die Systemfunktionen (/dice, /diceo) würfelt. Die App kann auf das Ergebnis zugreifen und die Daten für die Auswertung und Entscheidungen nutzen.

Parameter:

Beispiel:

this.onUserDiced = function(diceEvent)
{
    var nick = diceEvent.getUser().getNick();
    var totalSum = diceEvent.getDiceResult().totalSum();
    var message = 'Wer würfelt denn hier?... Es ist...' + nick + '... und die gewürfelte Zahl lautet... ' + totalSum + '!';

    var botUser = KnuddelsServer.getDefaultBotUser();

    botUser.sendPublicMessage(message);
};

onUserJoined

(
  • user
)

Diese Methode wird aufgerufen, wenn ein User den Channel der App betritt.

Parameter:

  • user User

    Nutzer, der den Channel betreten hat

Beispiel:

this.onUserJoined = function(user)
{
    var botUser = KnuddelsServer.getDefaultBotUser();

    botUser.sendPublicMessage('Hi ' + user.getNick() + '!');
};

onUserLeft

(
  • user
)

Diese Methode wird aufgerufen, wenn ein User den Channel der App verlässt.

Parameter:

  • user User

    Nutzer, der den Channel verlassen hat

Beispiel:

this.onUserLeft = function(user)
{
    var botUser = KnuddelsServer.getDefaultBotUser();

    botUser.sendPublicMessage(user.getNick() + ' hat uns soeben verlassen.');
};

Eigenschaften

chatCommands

Object

Ermöglicht das Registrieren eigener Chatbefehle. In einem Channel kann nur eine App laufen, die einen bestimmten Chatbefehl nutzt. Versucht eine zweite App einen Chatbefehl zu registrieren, den eine andere App bereits nutzt, so wird ein Fehler geloggt und die App startet nicht bzw. fährt herunter.

Die Struktur eines registrierten Chatbefehls ist: commandName: function (user, params, command) {}

  • commandName ist der Name der Funktion, wie sie aufgerufen wird (beispielsweise /commandname)
  • user ist der Nutzer, der die Funktion aufgerufen hat
  • params sind die Parameter, die der Nutzer hinter dem Befehl eingegeben hat (beispielsweise /commandname params)
  • command ist der Name des Befehl selbst (beispielsweise commandName)

Beispiel:

this.chatCommands =
{
   foo: function(user, params, command)
   {
      // Jemand im Chat hat /foo eingegeben.
      user.sendPrivateMessage('Foo ist etwas ganz Besonderes!');
   },
   bar: function(user, params, command)
   {
       if (params.length != 0)
       {
           // Jemand hat im Channel '/bar Getränk' eingegeben
           user.sendPrivateMessage('In der Bar trinke ich am liebsten ' + params + '!');
       }
       else
       {
           // Jemand hat im Channel '/bar' eingegeben
           user.sendPrivateMessage('In der Bar trinke ich am liebsten Coconut Kiss!');
       }
   }
};

Beispiel-Code

In diesen Beispielen wird diese Klasse verwendet: