Skip to content

Erste Schritte

Jump to bottom
Marc Staebler edited this page Mar 25, 2026 · 6 revisions

Erste Schritte

Diese Anleitung führt dich Schritt für Schritt von der Registrierung als Entwickler bis zu deiner ersten laufenden UserApp.

Voraussetzungen

Bevor du loslegen kannst, brauchst du:

  1. Knuddels Desktop App – Download
  2. Knuddels-Account mit mindestens Status "Family Mitglied"
  3. Gültige Handynummer (zur Verifizierung)
  4. Gültige E-Mail-Adresse
  5. Akzeptierte Entwickler-AGB
  6. FTP-Programm – z.B. FileZilla
  7. Texteditor / IDE – z.B. Visual Studio Code

Entwicklerzugang aktivieren

  1. Logge dich in die Knuddels Desktop App ein
  2. Gib in einem beliebigen Channel den Befehl /apps developer ein
  3. Bestätige deine E-Mail-Adresse, Handynummer und die AGB
  4. Deine FTP-Zugangsdaten werden dir von James (dem Knuddels-Bot) zugeschickt

Tipp: Bewahre deine FTP-Zugangsdaten sicher auf. Bei Problemen mit den Zugangsdaten wende dich an hilfe.knuddels.de.

Deine erste App erstellen

1. Projektordner anlegen

Erstelle auf deinem Computer folgende Dateistruktur:

meine-erste-app/
├── main.js          # Server-Logik
├── app.config       # App-Konfiguration
└── www/
    └── index.html   # Frontend (HTML-UI)

2. app.config anlegen

Die app.config enthält die Metadaten deiner App:

appName = MeineErsteApp
appVersion = 1.0
autoUpdate = true
appDeveloper.knuddelsDEV = DeinNickname
appDeveloper.knuddelsDE = DeinNickname
mayBeInstalledBy.1 = DeinNickname.knuddelsDEV
mayBeInstalledBy.2 = DeinNickname.knuddelsDE

Hinweis: Ersetze DeinNickname durch deinen tatsächlichen Knuddels-Nicknamen.

3. main.js – Dein erster Server-Code

var App = {

    // Wird aufgerufen, wenn die App gestartet wird
    onAppStart: function() {
        KnuddelsServer.getDefaultLogger().info('App wurde gestartet!');
    },

    // Wird aufgerufen, wenn ein Nutzer den Channel betritt
    onUserJoined: function(user) {
        user.sendPrivateMessage('Willkommen! Gib °>/meineApp|Klick hier<° ein, um die App zu öffnen.');
    },

    // Events vom Frontend empfangen
    onEventReceived: function(user, type, data, appContentSession) {
        if (type === "ping") {
            if (appContentSession) {
                appContentSession.sendEvent('pong', { success: true });
            }
        }
    },

    // Chat-Befehle
    chatCommands: {
        meineApp: function(user, params, command) {
            var htmlFile = new HTMLFile("index.html", {});
            var popup = AppContent.popupContent(htmlFile, 400, 300);
            popup.setResponsive(true);

            if (user.canShowAppViewMode(AppViewMode.Popup)) {
                user.sendAppContent(popup);
            } else {
                user.sendPrivateMessage("Die App kann auf deinem Gerät leider nicht angezeigt werden.");
            }
        }
    }
};

Wichtig: Alle Hooks und Chat-Befehle werden als Eigenschaften des App-Objekts definiert. Beachte die Kommas zwischen den Eigenschaften. Mehr dazu unter App-Lifecycle.

4. www/index.html – Dein erstes Frontend

<!DOCTYPE html>
<html>
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <style>
        body {
            font-family: Arial, sans-serif;
            display: flex;
            justify-content: center;
            align-items: center;
            height: 100vh;
            margin: 0;
            background: #f0f0f0;
        }
        .container {
            text-align: center;
            padding: 20px;
        }
        button {
            padding: 10px 20px;
            font-size: 16px;
            cursor: pointer;
            border: none;
            background: #4CAF50;
            color: white;
            border-radius: 5px;
        }
    </style>
</head>
<body>
    <div class="container">
        <h1>Meine erste App!</h1>
        <p id="status">Verbindung zum Server...</p>
        <button onclick="ping()">Ping senden</button>
    </div>
    <script>
        // pageData enthält die Daten, die der Server beim Öffnen mitgeschickt hat
        var pageData = {};
        if (typeof Client !== 'undefined') {
            pageData = Client.pageData;
        }

        document.getElementById('status').textContent = 'Verbunden!';

        function ping() {
            if (typeof Client !== 'undefined' && Client.sendEvent) {
                Client.sendEvent('ping', {});
            }
        }

        // Events vom Server empfangen
        if (typeof Client !== 'undefined') {
            Client.addEventListener("pong", function(event) {
                document.getElementById('status').textContent = 'Pong erhalten!';
            });
        }
    </script>
</body>
</html>

5. Fertig!

Der onEventReceived-Hook in der main.js reagiert bereits auf den Ping vom Frontend und sendet ein Pong zurück. Du musst nichts weiter hinzufügen.

App hochladen und installieren

Per FTP hochladen

  1. Öffne FileZilla und verbinde dich mit den erhaltenen FTP-Zugangsdaten
  2. Lade den gesamten Projektordner auf den Server hoch

App installieren

  1. Gehe in deinen eigenen MyChannel (oder erstelle einen)
  2. Gib /apps ein
  3. Klicke auf "App installieren"
  4. Beim ersten Installieren musst du einen AppBot anlegen – gib ihm einen beliebigen Namen
  5. Fertig! Deine App läuft

IDE-Einrichtung: Autovervollständigung für die Knuddels-API

Um in deiner IDE (z.B. Visual Studio Code) Autovervollständigung, Typ-Informationen und Inline-Dokumentation für die Knuddels-API zu bekommen, kannst du die offiziellen TypeScript-Typdefinitionen einbinden. Das funktioniert auch, wenn du deinen Server-Code in normalem JavaScript schreibst.

Knuddels stellt die sogenannte User App Library bereit – Typdefinitionen für Server- und Client-API. Es gibt zwei Wege, diese einzubinden.

Variante 1: Typdefinitionen per npm (empfohlen)

Initialisiere in deinem App-Ordner ein npm-Projekt und installiere die Typdefinitionen für Server und Client:

cd meine-app
npm init -y
npm install --save-dev @types/knuddels-userapp-backend-api
npm install --save-dev @types/knuddels-webapp-frontend-api

Das erste Paket liefert Typen für den Server-Code (main.js) – also Klassen wie KnuddelsServer, User, AppContent, Channel usw. Das zweite Paket liefert Typen für den Client-Code (www/) – also das Client-Objekt mit sendEvent, addEventListener etc.

Erstelle dann eine Datei jsconfig.json (für JavaScript) oder tsconfig.json (für TypeScript) im App-Ordner:

{
    "compilerOptions": {
        "target": "ES5",
        "checkJs": true,
        "noEmit": true,
        "typeRoots": ["./node_modules/@types"]
    },
    "include": ["*.js", "www/**/*.js"],
    "exclude": ["node_modules"]
}

Tipp: Mit "checkJs": true prüft VS Code deinen JavaScript-Code auch auf Typ-Fehler – das hilft, Bugs früh zu erkennen.

Danach erkennt VS Code automatisch Klassen wie KnuddelsServer, User, Client usw. und bietet Autovervollständigung an.

Variante 2: Library-Dateien manuell einbinden

Falls du npm nicht verwenden möchtest, kannst du die Library-Dateien direkt vom Knuddels Developer Portal herunterladen. Dort findest du unter "Unterstützung für Entwicklungsumgebungen" vier Dateien:

  • TypeScript (Server) – .d.ts-Datei für die Server-API
  • JavaScript (Server) – .js-Datei mit JSDoc-Annotationen für die Server-API
  • TypeScript (Client) – .d.ts-Datei für die Client-API
  • JavaScript (Client) – .js-Datei mit JSDoc-Annotationen für die Client-API

Lade die passenden Dateien herunter und lege sie in deinem Projektordner ab. In den meisten IDEs (VS Code, WebStorm, IntelliJ) reicht es, die Dateien im Projekt zu haben – die IDE erkennt die Typdefinitionen automatisch. Falls nicht, kannst du sie in deiner IDE manuell als Library registrieren (z.B. in WebStorm unter Settings → Languages & Frameworks → JavaScript → Libraries).

Tipp: Die .js-Varianten mit JSDoc-Annotationen eignen sich, wenn du eine IDE nutzt, die keine TypeScript-Definitionen unterstützt.

Variante 3: TypeScript mit Kompilierung

Wenn du deinen Server-Code direkt in TypeScript schreiben möchtest, bietet Knuddels ein Beispiel-Projekt auf GitHub:

git clone https://github.com/Knuddels/TypeScript-UserApp-Server.git
cd TypeScript-UserApp-Server
npm install
npm run build

Der Build-Prozess kompiliert dein TypeScript zu einer main.js, die du wie gewohnt per FTP hochladen kannst.

Wichtig: Auch bei TypeScript muss das kompilierte JavaScript ES5-kompatibel sein, da der Knuddels-Server die Rhino Engine nutzt. Das Beispiel-Projekt ist bereits entsprechend konfiguriert ("target": "ES5" in der tsconfig.json).

Was bringt das konkret?

  • Autovervollständigung – Tippe KnuddelsServer. oder Client. und sieh alle verfügbaren Methoden
  • Parameter-Info – Erfahre direkt in der IDE, welche Parameter eine Methode erwartet
  • Fehlerprüfung – Tippfehler in API-Aufrufen werden sofort markiert
  • Inline-Dokumentation – Hover über eine Methode, um ihre Beschreibung zu lesen

Ordnerstruktur mit IDE-Unterstützung

meine-app/
├── main.js              # Server-Logik
├── app.config           # App-Konfiguration
├── jsconfig.json        # IDE-Konfiguration
├── package.json         # npm-Abhängigkeiten
├── node_modules/        # (wird NICHT hochgeladen!)
│   └── @types/
│       ├── knuddels-userapp-backend-api/
│       └── knuddels-webapp-frontend-api/
└── www/
    └── index.html

Wichtig: Lade den node_modules-Ordner, package.json und jsconfig.json nicht per FTP hoch. Diese Dateien dienen nur der lokalen Entwicklung. Auf dem Knuddels-Server werden nur main.js, app.config und der www/-Ordner benötigt.

Entwicklungsworkflow

Der empfohlene Ablauf für die Entwicklung:

  1. Lokal entwickeln – Ändere deine Dateien in deinem Editor
  2. Per FTP hochladen – Lade die geänderten Dateien auf den Server
  3. App aktualisieren – Gib /apps ein und klicke auf "update/restart"
  4. Testen – Teste die Änderungen im Channel

Wichtig: Nutze den Dev-Server zum Entwickeln und Testen. Auf dem Live-Server (DE) solltest du nur stabile Versionen installieren. Mehr dazu unter Dev-Server.

Nächste Schritte

← Zurück zur Übersicht

Navigation

Einstieg

Kernkonzepte

Features

Tutorials

Referenz & Hilfe

Clone this wiki locally