UserApp-Entwicklung/Tutorials/Beginner

Einleitung

In diesem Tutorial lernst du Schritt für Schritt, deine erste UserApp zu programmieren.
Hier geht es darum, erstmal alles zum Laufen zu bringen und ein paar Basics zu vermitteln, sodass ab dann selbstständig weiterentwickelt werden kann.

Bevor es losgeht

Entwickler werden

Man stellt sicher, dass man ein Entwickler ist. Man gibt dazu /apps developer im Chat ein und erfüllt die Kriterien, falls man das noch nicht getan hat.

Verwende die Desktop-App

Wir empfehlen stark, zum Entwickeln die Desktop-App auf dem Computer zu verwenden. Man kann die App hier herunterladen.

Die erste UserApp

Entwicklungs-Server

Das Entwickeln beginnt auf dem Entwicklungs-Server. Man gibt /apps developer ein und wählt den Punkt Login auf Entwicklungs-Server aus. Jetzt sollte eine Desktop-Verknüpfung für den Login auf dem Entwicklungs-Server angelegt worden sein.
Wenn man Knuddels über diese Verknüpfung startet, landet man nach dem Login auf dem Entwicklungs-Server. Hier kann man später in Ruhe an der UserApp tüfteln, bevor man die Änderungen auf dem Live-Server hochlädt.

Man loggt sich jetzt mit den Zugangsdaten auf dem Entwicklungsserver ein, die James gesendet hat (Entwickler-Nick und Entwickler-Passwort).

 Tipp: Man kann die Zugangsdaten aus James' Nachricht mit Shift+Rechtsklick in das Chat-Fenster kopieren.

MyChannel

Nach dem Einloggen sollte sich automatisch das MyChannel-Edit Fenster öffnen. Ansonsten gibt man /mychannel ein.
Man legt sich jetzt einen eigenen Channel an, in dem man gleich die erste UserApp installieren wird. Eine Info zu den Einstellungen erhält man durch Klicken auf den Titel des jeweiligen Feldes. Außer über den Channel-Namen muss man sich aber erstmal keine Gedanken machen (man kann dieses Fenster jederzeit wieder mit /mychannel öffnen). Man drückt anschließend auf Speichern und Schließen und betritt den MyChannel mit /go <eigener Channel-Name>.

Installation der UserApp

Für dieses Tutorial hat man schon Dateien für eine Beispiel-UserApp namens "HeyThere" auf den Server geladen. Man installiert diese UserApp in dem MyChannel mit /apps install HeyThere. Man kann die UserApp später wieder aus dem Channel löschen.

Es müsste sich nun automatisch das Konfigurationsfenster für die UserApp geöffnet haben. Ansonsten öffnet man es eigenständig mit /apps und klickt auf den Namen der UserApp ("HeyThere").

 Hinweis: Durch einen Bug kann es sein, dass das Fenster auf dem Entwicklungs-Server nichts anzeigt. Man schließt es einfach und öffnet es gleich nochmal mit /apps. Man hofft, diesen Bug bald beheben zu können.

Im Menüpunkt "AppBot" kann man einen AppBot erstellen und an die UserApp binden. Ein AppBot ist ein bisschen wie Butler James, nur eben für die UserApp in dem jeweiligen Channel. Man drückt hierzu auf "hinzufügen" → "Nick anlegen", denkt sich einen Nicknamen aus und bestätigt.

Man startet jetzt die erste UserApp.

 Falls sich kein entsprechendes Fenster öffnet, startet man die UserApp eigenständig, indem man im App-Menü auf aktivieren klickt.

Man verlässt nun den Channel (indem man in einen anderen Channel geht) und betritt ihn dann wieder (z.B. mit /go <eigener Channel-Name>). Der AppBot sollte das Mitglied jetzt begrüßen!

Um mit dem Entwickeln zu starten, macht man mit dem nächsten Schritt weiter (FTP-Setup). Man kann auch schon mal einen Blick in die UserApps-API-Dokumentation werfen.

Bestimmt wird es auch mal eine Stelle geben, an der man nicht weiter weiß. Zögert nicht, im Forum Fragen zu stellen, wenn mal etwas nicht klar ist! Die anderen Entwickler sind freundlich, gehen fair miteinander um und helfen sich gerne gegenseitig.

FTP-Setup

Man benötigt für die UserApp-Entwicklung ein FTP-Programm, um die Dateien für die UserApp auf die Server von Knuddels hochzuladen.

Was ist eigentlich FTP?

FTP (File Transfer Protocol) ist ein Protokoll, mit dem Daten zwischen zwei Computern im Internet ausgetauscht werden können.
Zum Glück gibt es ganz einfache Programme, die hinter den Kulissen dieses Protokoll sprechen, sodass man die Dateien mit wenigen Klicks hochladen kann.

Einrichtung des FTP-Zugangs

Man wird die Dateien der UserApp auf zwei verschiedenen Servern hochladen:

1. auf dem Entwicklungs-Server, unter der URL devappupload.knuddels.de
2. auf dem Live-Server, unter der URL appupload.knuddels.de

Für beide Server muss man sich jeweils eine Verbindung einrichten. Dafür braucht man ein FTP-Programm. Man schaut sich dazu diese Erklärung an.
Diese Erklärung zeigt allerdings nur die Verbindung zum Live-Server - verwendet für den Entwicklungs-Server stattdessen die URL devappupload.knuddels.de.

Als Zugangsdaten verwendet man die Zugangsdaten, die James einem geschickt hat (FTP-Nutzer und FTP-Passwort).

 Tipp: Man kann die Zugangsdaten aus James' Nachricht mit Shift+Rechtsklick in das Chat-Fenster kopieren.
 Unter /apps developer kann man sie außerdem erneut anfordern.

Achtet außerdem jeweils darauf, eine unverschlüsselte Verbindung zu wählen.

Beispiel-Code anschauen

Wenn man weiß, wie man Dateien über den FTP-Zugang von dem Server herunter- und hochladen kann, kann man sich jetzt anschauen, wie eine UserApp aufgebaut ist.

Man loggt sich hierzu in dem FTP-Programm auf dem Entwicklungs-Server ein, navigiert in den Ordner ftp → HeyThere und lädt dort die Datei main.js herunter. Man kann diese Datei jetzt anschauen, verändern und dann wieder dort hochladen. So versteht man, wie alles funktioniert.

Die main.js kann man sogar im normalen Texteditor anschauen und bearbeiten.
Empfehlenswert ist das aber nicht.

• Auf Windows kann man sich (zum Beispiel) Notepad++ herunterladen.
• Auf macOS kann man sich (zum Beispiel) Textwrangler herunterladen.

Diese Programme können einem das Entwickeln erleichtern. (Natürlich kann man auch eine IDE verwenden, wenn man sich damit auskennt.)

Man schaut sich den Code jetzt an und nimmt einige Veränderungen vor.

 Idee: Lass den AppBot Besucher abhängig von ihrem Geschlecht begrüßen! Zum Beispiel männliche Besucher mit "Hey Prinz <Nickname>" und weibliche Besucher mit "Hey Prinzessin <Nickname>". 

→ Jetzt ist ein guter Zeitpunkt, die API-Dokumentation anzuschauen. Der Aufbau der main.js wird hier erklärt.

Man geht danach folgendermaßen vor:

1. Man verändert die Datei und speichert sie.
2. Man lädt die Datei auf den FTP-Server hoch (ersetzt die alte main.js).
3. Man öffnet das App-Menü in dem Channel mit /apps und drückt auf update/restart. Die App fährt herunter und startet nach wenigen Sekunden erneut - mit dem neuen Code.

Im nächsten Schritt wird gezeigt, wie man Besucher abhängig von ihrem Geschlecht begrüßen kann.

Begrüßt Besucher abhängig von ihrem Geschlecht

So kann man neuen Besuchern eine Begrüßungsnachricht abhängig von ihrem Geschlecht schicken:

main.js

var App = (new function() {

    this.onUserJoined = function(user) {  // diese Funktion wird aufgerufen, wenn ein Nutzer den Channel betritt

        let gender = user.getGender();
        let nick  = user.getNick();
        let title;

        if (gender == Gender.Male) {
            title = "Prinz " + nick;
        } else if (gender == Gender.Female) {
            title = "Prinzessin " + nick;
        } else {  // der Nutzer hat sich nicht als männlich oder weiblich ausgegeben
            title = nick;
        }

        let message = "Hey " + title + ", willkommen im Channel! Du bist " + user.getAge() + " Jahre alt.";
        user.sendPrivateMessage(message);  // der AppBot sendet eine private Nachricht an den Nutzer
    }
}());

Schafft man es außerdem, die Besucher sowohl abhängig von ihrem Alter, als auch von ihrem Geschlecht zu begrüßen? → Begrüße Besucher...

• unter 18 Jahren mit: "Hallo Junge <Nickname>" bzw. "Hallo Mädchen <Nickname>"
• zwischen 18 und 60 Jahren mit: "Hallo Herr <Nickname>" bzw. "Hallo Frau <Nickname>"
• über 60 Jahren mit: "Hallo Opa <Nickname>" bzw. "Hallo Oma <Nickname>"

Man schaut in die UserApps-API-Dokumentation, wenn man eine Funktion sucht. Den fertigen Code kann man sich hier herunterladen: Begrüßung nach Alter und Geschlecht

Im nächsten Schritt lernt man, wie Besucher Knuddel an den AppBot transferieren können!

Knuddel überweisen

Mitglieder können Knuddel an den AppBot überweisen. Diese Knuddel kann man sich dann später auf den eigenen Nick überweisen lassen. Hier lernt man, wie man das in der UserApp machen kann.

Der AppBot soll jedes neues Mitglied nach einem Knuddel fragen. Wenn er diesen bekommt, bedankt er sich bei dem Mitglied.

 Auf dem Entwicklungs-Server hat der Nick so viele Knuddel, dass man das einfach testen kann.

main.js

var App = (new function() {

    this.onUserJoined = function(user) {
        var appBotNick = KnuddelsServer.getDefaultBotUser().getNick();
        var message = "Gibst du mir _°BB°°>_heinen Knuddel|/appknuddel " + appBotNick.escapeKCode() + "<°°°_?";
        user.sendPrivateMessage(message);
    }

    this.onKnuddelReceived = function(sender, receiver, knuddelAmount, transferReason) {
        sender.sendPrivateMessage("Danke, " + sender.getNick() + "!");
    }
}());

Erklärung: Was ist KCode?

In App.onUserJoined wird dem Mitglied eine Nachricht mit seltsamen Zeichen gesendet:

 "Gibst du mir _°BB°°>_heinen Knuddel|/appknuddel " + appBotNick.escapeKCode() + "<°°°_?"

Das ist KCode. Dieser Code wird vor dem Anzeigen umgewandelt, sodass die Mitglieder einen Link präsentiert bekommen, auf dessen Klick hin ein Befehl ausgeführt wird: Hier ist dieser Befehl /appknuddel <Nickname des AppBots>. Mit dem Klicken auf den Link überweist das Mitglied also einen Knuddel an den AppBot.

appBotNick.escapeKCode() dient dazu, dass der Befehl auch bei Sonderzeichen im Nicknamen des AppBots richtig ausgeführt wird.

→ Hier kann man sich anschauen, wie KCode funktioniert.

 Idee für wahre Kapitalisten: Man kann den Besucher des Channels vielleicht dazu bringen, dem AppBot einen Knuddel zu schenken, wenn der AppBot dem Besucher nach einiger Zeit eine traurige Nachricht schreibt, falls er bis dahin keinen Knuddel von dem Besucher erhalten hat.

Eine mögliche Lösung dieses Problems kann man sich hier anschauen: Download Code-Beispiel (Traurige Nachricht vom AppBot)

Im nächsten Schritt lernt man, wie man dauerhaft Daten über die Besucher speichern kann.

UserPersistence: Nutzerdaten speichern

Wenn man sich beispielsweise dauerhaft merken will, wie viele Knuddel ein Mitglied jeweils schon an den AppBot überwiesen hat, braucht man eine Möglichkeit, zu jedem Mitglied eine Zahl zu speichern.

 Allerdings kann man nicht einfach eine Variable in demCode haben, worüber man alles speichert - das wäre nämlich mit jedem Neustart der App wieder weg.

In der UserApps-API gibt es genau dafür das Objekt UserPersistence.

main.js

var App = (new function() {

    this.onUserJoined = function(user) {

        let userPersistence = user.getPersistence();
        let userSpending = userPersistence.getNumber("spending", 0);

        if (userSpending > 10) {
            user.sendPrivateMessage("Willkommen, gütiger Spender!");
        }

        var appBotNick = KnuddelsServer.getDefaultBotUser().getNick();
        var message = "Gibst du mir _°BB°°>_heinen Knuddel|/appknuddel " + appBotNick.escapeKCode() + "<°°°_?";
        user.sendPrivateMessage(message);
    }

    this.onKnuddelReceived = function(sender, receiver, knuddelAmount, transferReason) {
        sender.sendPrivateMessage("Danke, " + sender.getNick() + "!");

        let userPersistence = sender.getPersistence();
        userPersistence.addNumber("spending", knuddelAmount.asNumber());
    }
}());

Die App merkt sich nun, wie viele Knuddel die Besucher bereits eingezahlt haben. Besonders gönnerische Besucher begrüßt er ehrerbietig!

Der Fortschitt

Man ist schon weit gekommen!

• Man hat gelernt, wie man sich auf dem Entwicklungs-Server anmeldet und eine App installiert.
• Man hat sich mit FTP vertraut gemacht und kann die Dateien jetzt einfach an den Knuddels-Server senden.
• Man weiß jetzt, wie man auf verschiedene Events in dem Channel reagiert.
• Man ist mit der Überweisung von Knuddel an den AppBot vertraut.
• Man kann sich Daten über die Besucher dauerhaft speichern.

Jetzt kann man die UserApp mal veröffentlichen! Dazu muss man die UserApp per FTP auf dem Live-Server hochladen - so wie schon vorher auf dem Entwicklungs-Server. Hierzu meldet man sich dann ganz normal bei Knuddels an und installiert die UserApp mit /apps install <UserApp-Name> in dem jeweiligen MyChannel.

Und wenn man jetzt noch den MyChannel unter /mychannel veröffentlicht, können auch andere Mitglieder zufällig auf den MyChannel stoßen.

Wie geht's weiter?

Vielleicht hat man nun Lust, ein grafisches Spiel zu programmieren? Oder ein textbasiertes RPG?
Ab jetzt ist man sich selbst überlassen - und man kann sich natürlich jederzeit an die Community wenden.
Auf dem Entwickler-Portal developer.knuddels.de findet man das meiste im Zusammenhang mit UserApps.

→ Übersicht: UserApp-Entwicklung