User App:Frontend/Environment

Es gibt bei der HTML-UI ein paar Besonderheiten bzw. Anpassungen die ihr bei einer unveränderten Browser-Umgebung nicht hättet. Hier werden diese näher erleutert.

UserApps Client-API

Die Client-API (alle APIs dort mit `Client.<xxx>`) sind zusätzlich verfügbar. diese stellen euch ein paar Hilfs-Methoden zur Verfügung und sind die Schnittstelle um Events an den Server zu schicken und von diesem zu empfangen.

Erzwungene Client-Updates

Öffnet sich beim Nutzer eine HTML-UI (auch von SystemApps - also von Knuddels selbst veröffentlichen Features) und wir erkennen dass der Nutzer einen veralteten Chat-Client verwendet der für die zu öffnende HTML-UI nicht geeignet ist, dann wird dem Nutzer statt der HTML-UI ein Migrations/Update-Hinweis angezeigt. Dies betrifft vor allem Nutzer mit einer veralteten PC-App von Knuddels.

Neuer AppLoader

Seit dem 17.07.2018 gibt es für HTML-UIs eine neue Loader Architektur, der neue "AppLoader". Dieser bringt einige neue Möglichkeiten, Features und Änderungen an APIs mit sich. Auf diese wird in den folgenden Abschnitten eingegangen.

Polyfills (API-Patches die wir automatisch einspielen)

Es liegt leider in der Natur der Browser, dass nicht alle (Firefox, Chrome, Edge, Safari, Chrome for Android, jxBrowser [Desktop App], Internet Explorer) das gleiche Set an Features und API unterstützen. Manchmal haben bestimmte Implementierungen auch Bugs. Daher patchen wir den Browser bevor die erste Zeile eures Codes ausgeführt wird. Wir patchen folgende APIs:

• Promise (API für asynchrone Programmierung)
• Object.assign (Manipulation von Javascript-Objekten)
• Symbol (hier benutzen wir das NPM Package 'core-js/modules/es6.symbol')
• Symbol.interator (hier benutzen wir das NPM Package 'core-js/fn/symbol/iterator.js')
• String.prototype.startsWith

Ihr müsst diese Patches/Polyfills also nicht mehr selbst einbinden, falls ihr diese API/Features benutzen wollt.

Sandbox <iframe>

Eure HTML-UI wird innerhalb eines <iframe> das in einer Sandbox (siehe "sandbox"-Attribute) ausgeführt wird geladen. Das bringt ein paar Einschränkungen mit sich, die ihr in der verlinkten Dokumentation zum sandbox-Attribut nachlesen könnt. Auch Zugriff zu Kamera und Mikrofon sind nicht möglich. Es sind folgendes allow-* Flags gesetzt: allow-forms, allow-orientation-lock, allow-pointer-lock, allow-same-origin, allow-scripts

Veränderungen von Web-APIs

Wir haben auch einige wenige normale Web-APIs verändert. Das haben wir vor allem getan da diese technische Probleme provozieren können oder konnten oder weil sie die User-Experience stark negativ beeinflussen können.

• alert() erzeugt jetzt ein Warning und wird sonst ersetzt durch console.log()
• prompt() erzeugt jetzt ein Warning und macht sonst nichts
• confirm() erzeugt jetzt ein Warning und macht sonst nichts
• window.history ist komplett deaktiviert

Änderungen an bestehenden APIs

Mit dem neuen AppLoader haben wir kleine Anpassungen an bestehenden APIs vorgenommen die vor allem der Natur sind, dass sie technische Probleme oder Lücken fixen oder verhindern.

• Client.addEventListener(type, callback): `type` muss nun vom Typ `string` sein
• Client.removeEventListener(type): Funktioniert jetzt wieder und entfernt alle Listener des entsprechenden Typs (durch einen Fehler wurde der Listener nie entfernt)
• (NEU) Client.removeEventListener(type, callback): entfernt einen bestimmten Listener für ein bestimmtes Event
• Nutzeraktivitätsmessung: Der Mechanismus der die Aktivät des Nutzers in der HTML-UI misst wurde überarbeitet und funktioniert jetzt wie gewollt (das heißt der "/dice"-Hack ist nicht mehr nötig)

Deprecation Notice (veraltete APIs)

Im alten AppLoader gab es aus historischen Gründen noch einige APIs die seit Jahren nicht mehr zur offiziellen Dokumentation und damit API gehört haben. Diese haben wir nun entweder entfernt (da sie sowieso nur für interne Verwendung gedacht waren). Andere APIs, die aktuell noch immer von vielen Apps genutzt werden, haben wir mit Warnungen versehen und dazu Migrations-Hinweise veröffentlicht. Auf diese gehen wir nun etwas näher ein.

Wir werden diese APIs zu einem noch nicht definierten Zeitpunkt in der Zukunft entfernen. Wir kündigen das dann rechtzeitig an.

Für euch heißt das: Bitte passt eure Apps an und tauscht die veralteten APIs mit der entsprechenden aktuellen API aus! (siehe Warnings)

document.addEventListener("eventReceived", function() {...})

Warning: You are using a deprecated API (document event listener for "eventReceived"). Please use "Client.addEventListener()" instead. See: https://developer.knuddels.de/docs/classes/Client.html#method_addEventListener

Es gab in den Anfangszeiten wie hier erwähnt kurzzeitig diese Variante um Events vom Server zu empfangen. In dieser Zeit ist auch die Ziegenphobie-Demo-App entstanden. Wir haben nach wenigen Monaten die alte API als "Deprecated" markiert, und sie war auch niemals offiziell dokumentiert. Da wir aber versäumt haben die HTML-UI-Demo-App (Ziegenphobie) an die neuen APIs anzupassen hat sich die Verwendung dieser API stark verbreitet. Die Demo-Apps mit HTML-UI sind jetzt auf die aktuellsten APIs aktualisiert worden.

Client.onSendEventReceived()

Warning: You are using "Client.onSendEventReceived()" which is an internal API. Please use "Client.dispatchEvent()" instead. See: https://developer.knuddels.de/docs/classes/Client.html#method_dispatchEvent

Diese API war nie öffentlich oder offiziell. Allerdings hat sie mindestens den Weg in ein beliebtes Framework geschafft und sich dadurch weit verbreitet. Aus diesem Grund können wir sie nicht ohne Weiteres entfernen. Es ist generell immer der empfohlene und richtige Weg ausschließlich APIs zu verwenden die in der offiziellen Dokumentation auch entsprechend dokumentiert sind.

Weiterführende Informationen

Wir haben für die Entwicklung von Webseiten und vor allem Apps mit Web-Technologien einen Web-Client Coding Guide geschrieben. Dort findet ihr sehr viele weitere Infos und Guidelines für erfolgreiches Entwickeln im Web Frontend. Hinweis: Dieser Guide ist für Fortgeschrittene!