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

Werde Entwickler

Stelle sicher, dass du ein Entwickler bist. Gib dazu /apps developer im Chat ein und erfülle die Kriterien, falls du das noch nicht getan hast.

Verwende die Desktop-App

Wir empfehlen dir stark, zum Entwickeln die Desktop-App auf deinem Computer zu verwenden. Du kannst die App hier herunterladen.

Die erste UserApp

Entwicklungs-Server

Das Entwickeln beginnt auf dem Entwicklungs-Server. Gib /apps developer ein und wähle 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 du Knuddels über diese Verknüpfung startest, landest du nach dem Login auf dem Entwicklungs-Server. Hier kannst du später in Ruhe an deiner UserApp tüfteln, bevor du deine Änderungen auf dem Live-Server hochlädst.

Logge dich jetzt mit den Zugangsdaten auf dem Entwicklungsserver ein, die dir James gesendet hat (Entwickler-Nick und Entwickler-Passwort).

 Tipp: Du kannst 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 gib /mychannel ein.
Du legst dir jetzt einen eigenen Channel an, in dem du gleich deine erste UserApp installieren wirst. Eine Info zu den Einstellungen erhältst du durch Klicken auf den Titel des jeweiligen Feldes. Außer über deinen Channel-Namen musst du dir aber erstmal keine Gedanken machen (du kannst dieses Fenster jederzeit wieder mit /mychannel öffnen). Drücke anschließend auf Speichern und Schließen und betritt deinen MyChannel mit /go <dein eigener Channel-Name>.

Installation der UserApp

Für dieses Tutorial haben wir dir schon Dateien für eine Beispiel-UserApp namens "HeyThere" auf den Server geladen. Installiere diese UserApp in deinem MyChannel mit /apps install HeyThere. Du kannst die UserApp später wieder aus deinem Channel löschen.

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

 Hinweis: Durch einen Bug kann es sein, dass das Fenster auf dem Entwicklungs-Server nichts anzeigt. Schließe es einfach und öffne es gleich nochmal mit /apps. Wir hoffen, diesen Bug bald beheben zu können.

Im Menüpunkt "AppBot" kannst du einen AppBot erstellen und an deine UserApp binden. Ein AppBot ist ein bisschen wie Butler James, nur eben für deine UserApp in deinem Channel. Drücke hierzu auf "hinzufügen" → "Nick anlegen", denk dir einen Nicknamen aus und bestätige.

Starte jetzt deine erste UserApp.

 Falls sich kein entsprechendes Fenster öffnet, starte die UserApp selbst, indem du im App-Menü auf aktivieren klickst.

Verlasse nun deinen Channel (indem du in einen anderen Channel gehst) und betritt ihn dann wieder (z.B. mit /go <dein eigener Channel-Name>). Dein AppBot sollte dich jetzt begrüßen!

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

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

FTP-Setup

Du benötigst für die UserApp-Entwicklung ein FTP-Programm, um die Dateien für deine 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 du die Dateien mit wenigen Klicks hochladen kannst.

Einrichtung des FTP-Zugangs

Du wirst die Dateien deiner 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 musst du dir jeweils eine Verbindung einrichten. Dafür brauchst du ein FTP-Programm. Schau dir dazu diese Erklärung an.
Diese Erklärung zeigt allerdings nur die Verbindung zum Live-Server - verwende für den Entwicklungs-Server stattdessen die URL devappupload.knuddels.de.

Als Zugangsdaten verwendest du die Zugangsdaten, die James dir geschickt hat (FTP-Nutzer und FTP-Passwort).

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

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

Beispiel-Code anschauen

Wenn du weißt, wie du Dateien über den FTP-Zugang von dem Server herunter- und hochladen kannst, kannst du dir jetzt anschauen, wie eine UserApp aufgebaut ist.

Logge dich in deinem FTP-Programm auf dem Entwicklungs-Server ein, navigiere in den Ordner ftp → HeyThere und lade dort die Datei main.js herunter. Du kannst diese Datei jetzt anschauen, verändern und dann wieder dort hochladen. So verstehst du, wie alles funktioniert.

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

• Auf Windows kannst du dir (zum Beispiel) Notepad++ herunterladen.
• Auf macOS kannst du dir (zum Beispiel) Textwrangler herunterladen.

Diese Programme können dir das Entwickeln erleichtern. (Natürlich kannst du auch eine IDE verwenden, wenn du dich damit auskennst.)

Schau dir den Code jetzt an und nimm einige Veränderungen vor.

 Idee: Lass deinen 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>". Findest du heraus, wie das geht?

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

Gehe danach folgendermaßen vor:

1. Verändere die Datei und speichere sie.
2. Lade die Datei auf den FTP-Server hoch (ersetze die alte main.js).
3. Öffne das App-Menü in deinem Channel mit /apps und drücke auf update/restart. Deine App fährt herunter und startet nach wenigen Sekunden erneut - mit deinem neuen Code.

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

Begrüße Besucher abhängig von ihrem Geschlecht

So kannst du 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
    }
}());

Schaffst du 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>"

Schau in die UserApps-API-Dokumentation, wenn du eine Funktion suchst. Den fertigen Code kannst du dir hier herunterladen: Begrüßung nach Alter und Geschlecht

Im nächsten Schritt lernst du, wie Besucher Knuddel an deinen AppBot transferieren können!

Knuddel überweisen

Nutzer können Knuddel an deinen AppBot überweisen. Diese Knuddel kannst du dir dann später auf deinen eigenen Nick überweisen lassen. Hier lernst du, wie du das in deiner UserApp machen kannst.

Der AppBot soll jeden neuen Nutzer nach einem Knuddel fragen. Wenn er diesen bekommt, bedankt er sich bei dem Nutzer.

 Auf dem Entwicklungs-Server hat dein Nick so viele Knuddel, dass du das einfach testen kannst.

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 Nutzer 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 Nutzer 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 der Nutzer also einen Knuddel an den AppBot.

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

→ Hier kannst du dir anschauen, wie KCode funktioniert.

 Idee für wahre Kapitalisten: Du kannst den Besucher deines 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 kannst du dir hier anschauen: Download Code-Beispiel (Traurige Nachricht vom AppBot)

Im nächsten Schritt lernst du, wie du dauerhaft Daten über deine Besucher speichern kannst.

UserPersistence: Nutzerdaten speichern

Wenn du dir beispielsweise dauerhaft merken willst, wie viele Knuddel ein Nutzer jeweils schon deinem AppBot überwiesen hat, brauchst du eine Möglichkeit, zu jedem Nutzer eine Zahl zu speichern.

 Allerdings kannst du nicht einfach eine Variable in deinem Code haben, worüber du alles speicherst - 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 deine Besucher bereits eingezahlt haben. Besonders gönnerische Besucher begrüßt er ehrerbietig!

Dein Fortschitt

Du bist schon weit gekommen!

• Du hast gelernt, wie man sich auf dem Entwicklungs-Server anmeldet und eine App installiert.
• Du hast dich mit FTP vertraut gemacht und kannst deine Dateien jetzt einfach an den Knuddels-Server senden.
• Du weißt jetzt, wie man auf verschiedene Events in deinem Channel reagiert.
• Du bist mit der Überweisung von Knuddel an deinen AppBot vertraut.
• Du kannst Daten über deine Besucher dauerhaft speichern.

Jetzt kannst du deine UserApp mal veröffentlichen! Dazu musst du deine UserApp per FTP auf dem Live-Server hochladen - so wie schon vorher auf dem Entwicklungs-Server. Melde dich dann ganz normal bei Knuddels an und installiere deine UserApp mit /apps install <UserApp-Name> in deinem MyChannel.

Und wenn du jetzt noch deinen MyChannel unter /mychannel veröffentlichst, können auch andere Nutzer zufällig auf deinen MyChannel stoßen.

Wie geht's weiter?

Vielleicht hast du Lust, ein grafisches Spiel zu programmieren? Oder ein textbasiertes RPG?
Ab jetzt bist du dir selbst überlassen - und kannst dich natürlich jederzeit an die Community wenden.
Auf dem Entwickler-Portal developer.knuddels.de findest du das meiste im Zusammenhang mit UserApps.

→ Übersicht: UserApp-Entwicklung