Knuddels User Apps - API Dokumentation

  • Dokumentation für Version 20240415-122902 (ChatServer: 20240415-122902)

    • Knuddels
    User App Entwicklung
    API Dokumentation
    Client

    Client Klasse

    Modul: HTMLUI

    Klasse, die es ermöglicht den Client innerhalb des HTML User Interface zu steuern und Daten an den Server zu senden.

    Methoden

    addConnectionTypeChangeListener

    (
    • callback
    )
    static

    Registriert eine Callback die aufgerufen wird wenn sich zur Laufzeit der App der Verbindungstyp ändert. Unterstützt der Server von vorneherein keinen anderen Verbindungstype als "DEFAULT" wird diese Callback nie aufgerufen da diese Verbindung immer besteht und nie geschlossen wird. Ist aber bspw. eine DirectConnection verfügbar und wird erfolgreich etabliert dann wird diese Callback aufgerufen und der entsprechende Verbindungstyp übergeben. Sollte zur Laufzeit die DirectConnection abbrechen oder geschlossen werden dann wird diese Callback ebenfalls mit dem entsprechenden neuen Verbindungstyp aufgerufen.

    Verbindungstypen können sein: "DEFAULT", "DIRECT_CONNECTION"

    Parameter:

    Beispiel:

       Client.addConnectionTypeChangeListener(function (type) {
       console.log('new connection type is: ' + type)
   });

    addEventListener

    (
    • type
    • callback
    )
    static

    Mit dieser Methode kann man einen Event-Listener für ein bestimmtes Event registrieren, das vom Server via AppContentSession.sendEvent() versendet oder vom Client via Client.dispatchEvent() ausgelöst wurde.

    Parameter:

    • type String

      Name des Events. Gibt man als Name das Zeichen Sternchen '*' an, so registriert man sich für alle Events.

    • callback Function

    Beispiel:

    // Server
appContentSession.sendEvent('gameEnded', { x: 1, y: 2 });

// Client
Client.addEventListener('gameEnded', function(event) {
        var type = event.type;    // 'gameEnded'
        var data = event.data;  // { x: 1, y: 2 }
});

    close

    () static

    Schließt das HTML User Interface.

    Beispiel:

    // mit purem JavaScript //
document.getElementById('buttonClose').onclick = function() 
{
    Client.close();
}

// oder mit jQuery //
$('#buttonClose').click(function ()
{
    Client.close();
});

    dispatchEvent

    (
    • event
    )
    static

    Mit dieser Methode löst man ein bestimmtes Event aus, so dass alle via Client.addEventListener() registrierten Event-Listener für den entsprechenden Event-Type aufgerufen werden.

    Parameter:

    Beispiel:

    var event = new Client.Event('gameEnded', { x: 1, y: 2 });
Client.dispatchEvent(event);

    executeSlashCommand

    (
    • command
    )
    static

    Sagt dem Chatserver, dass dieser Befehl für den Nutzer, der das HTML User Interface sieht, ausgeführt werden soll. Ist der Befehl auf einer Whitelist vom Server, so wird er sofort ausgeführt. Im anderen Falle sieht der Nutzer einen Link zum Bestätigen, mit dem er die Aktion starten kann.

    Derzeit sind diese Befehle auf der Whitelist: w, info, wc, top, h, dice, d, diceo, w2, serverpp, knuddelaccount, /tf-insert, /tf-inserts, /tf-insertb, /tf-insertsb, /tf-override, /tf-overrides, /tf-overrideb, /tf-overridesb, /autotype

    Parameter:

    • command String

      Befehl, der ausgeführt werden soll

    Beispiel:

    Client.executeSlashCommand('/dice 10w2');

    freeSound

    (
    • fileName
    )
    static

    Gibt einen Sound wieder frei, der in nächster Zeit vom Client nicht mehr gebraucht wird. (Android only) Der angegebene Dateiname kann hierbei entweder absolut oder relativ zur angezeigten HTML-Datei sein.

    Parameter:

    Beispiel:

    Client.freeSound('testSound.wav');

    getCacheInvalidationId

    () String static

    Liefert die Id, die beim Laden von Skripten und Stylesheets an die URL angehängt wird, um sicherzustellen, dass eine neue Version der Datei vom Server geholt wird, statt die Datei aus dem Cache zu laden.

    Diese Id kann beim Einbinden eigener Ressourcen zum selben Zweck genutzt werden.

    Rückgabewert:

    String:

    Beispiel:

    var cacheInvalidationId = Client.getCacheInvalidationId();

    getClientType

    () ClientType static

    Liefert den aktuellen ClientType des Nutzers, der gerade dieses HTML User Interface angezeigt bekommt.

    Rückgabewert:

    ClientType:

    Beispiel:

    var clientType = Client.getClientType();

    getDirectConnection

    () Promise static

    Diese Methode gibt ein Promise zurück.

    Das Promise wird aufgelöst ("resolved") wenn die DirectConnection erfolgreich und vollständig aufgebaut ist. Dann wird die erste Callback (die "onFullfilled"-Callback) die via ".then(...)" registriert wurde aufgerufen.

    Das Promise wird verworfen ("rejected") wenn der Versuch eine DirectConnection aufzubauen gescheitert ist. Dann wird die zweite Callback (die "onRejected"-Callback) die via ".then(...)" registriert wurde aufgerufen. Es wird ebenso die "onRejected"-Callback aufgerufen die man via ".catch(...)" registriert hat.

    Gründe für das scheitern eines Aufbauversuchs für eine DirectConnection können z.B. sein, dass der Client den der User benutzt keinen WebSocket unterstützt (der wird intern verwendet) oder weil z.B. der Server von vorne herein keine DirectConnection unterstützt (das ist vermutlich vor allem in der Übergangsphase so).

    Rückgabewert:

    Promise:

    Beispiel:

    Client.getDirectConnection()
.then(function() {
    console.log('DirectConnection works!!');
})
.catch(function(problem) {
    console.log('DirectConnection failed', problem);
});

    getHostFrame

    () Client.HostFrame static

    Liefert den HostFrame des aktuellen Inhalts.

    Rückgabewert:

    Client.HostFrame:

    Beispiel:

    var hostFrame = Client.getHostFrame();

    getNick

    () String static

    Liefert den Nicknamen des Users, der gerade dieses HTML User Interface angezeigt bekommt.

    Rückgabewert:

    String:

    Nickname des Betrachters

    Beispiel:

    var nick = Client.getNick();

    includeCSS

    (
    • files
    )
    static

    Bindet eine CSS-Datei ein und sorgt dafür, dass immer die aktuellste Version vom Server geladen wird.

    Parameter:

    Beispiel:

    Client.includeCSS('test.css', 'test2.css');

    includeJS

    (
    • files
    )
    static

    Bindet eine Javascript-Datei ein und sorgt dafür, dass immer die aktuellste Version vom Server geladen wird.

    Parameter:

    Beispiel:

    Client.includeJS('test.js', 'test2.js');

    isK3Client

    () Boolean static

    Liefert, ob der Nutzer aktuell mit einem K3-Client verbunden ist.

    Rückgabewert:

    Boolean:

    Beispiel:

    var isK3Client = Client.isK3Client();

    playSound

    (
    • fileName
    )
    static

    Spielt einen Sound ab. Der angegebene Dateiname kann hierbei entweder absolut oder relativ zur angezeigten HTML-Datei sein. Bisher können nur Dateien mit Wave-Format zuverlässig abgespielt werden.

    Parameter:

    Beispiel:

    Client.playSound('testSound.wav');

    prefetchSound

    (
    • fileName
    )
    static

    Lädt einen Sound herunter, damit die Datei später ohne Wartezeit abgespielt werden kann. (Android only) Der angegebene Dateiname kann hierbei entweder absolut oder relativ zur angezeigten HTML-Datei sein.

    Parameter:

    Beispiel:

    Client.prefetchSound('testSound.wav');

    removeConnectionTypeChangeListener

    (
    • callback
    )
    static

    Entfernt einen bestimmten Listener den man zuvor registiert hat.

    Parameter:

    Beispiel:

       function myAwesomeConnectionTypeChangeListener(type) {
       console.log('new connection type is: ' + type)
   }
   Client.addConnectionTypeChangeListener(myAwesomeConnectionTypeChangeListener);
Client.removeConnectionTypeChangeListener(myAwesomeConnectionTypeChangeListener);

    removeEventListener

    (
    • type
    )
    static

    Entfernt alle Event-Listener für einen bestimmten Event-Type.

    Parameter:

    Beispiel:

    Client.removeEventListener('awesomeEvent');

    removeEventListener

    (
    • type
    • callback
    )
    static

    Entfernt einen bestimmten Event-Listener für einen bestimmten Event-Type.

    Parameter:

    Beispiel:

       function myAwesomeListener() {
       console.log('event received!')
   }
   Client.addEventListener('awesomeEvent', myAwesomeListener);
Client.removeEventListener('awesomeEvent', myAwesomeListener);

    sendEvent

    (
    • type
    • data?
    )
    static

    Sendet ein Event eines bestimmten Typs mit Nutzdaten zum Server. Auf Server-Seite kann das Event im AppHook App/onEventReceived:method verarbeitet werden.

    Die Nutzdaten können ein String, ein Objekt, oder ein Array von Strings und/oder Objekten sein. Das Objekt muss via JSON.stringify() zu einem String konvertierbar sein. Nach der Konvertierung zu einem JSON-String wird auf Einhaltung der Limits geprüft.

    Parameter:

    • type String

      darf maximal 100 Zeichen lang sein. Das einzelne Zeichen '*' kann nicht als type verwendet werden.

    • data? Json

      Nutzdaten die übermittelt werden sollen. Sie werden als JSON-String übermittelt und dürfen als solcher maximal 10.000 Zeichen lang sein.

    Beispiel:

    var gamePoints = 1;

var data = {
    points: gamePoints
};

Client.sendEvent('gameEnded', data);

    Eigenschaften

    pageData

    Json static

    Beinhaltet die JSON-Daten, die beim Erstellen des HTMLFile übergeben wurden.

    Beispiel:

    // Server code //
var pageData = {
    userAge: user.getAge();
}

var htmlFile = new HTMLFile('test.html', pageData);

var appContent = AppContent.overlayContent(htmlFile);

user.sendAppContent(appContent);

// Client code //
var userAge = Client.pageData['userAge'];