Allgemeines

Es gibt bei der HTML-UI ein paar Besonderheiten und Anpassungen, die bei einer unveränderten Browser-Umgebung nicht vorhanden wären. Diese Besonderheiten werden in diesem Artikel erläutert.

UserApps Client-API

Die Client-API (alle APIs mit Client.<xxx>) sind zusätzlich verfügbar. Diese stellen einige 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 System-Apps - 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 App-Loader

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

Polyfills

Es liegt leider in der Natur der Browser, dass nicht alle das gleiche Set an Features und APIs unterstützen. Manchmal haben bestimmte Implementierungen auch Bugs. Daher wird durch Knuddels der Browser gepatcht, bevor die erste Zeile des User App-Codes ausgführt wird. Es werden folgende APIs gepatcht:

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

Falls diese Polyfills genutzt werden sollen, müssen diese nicht mehr selbst eingebunden werden.

Sandbox <iframe>

Die HTML-UI wird innerhalb eines <iframe>, welches in einer Sandbox (siehe "sandbox"-Attribute), ausgeführt und geladen wird. Das bringt ein paar Einschränkungen mit sich, die in der verlinkten Dokumentation zum sandbox-Attribut nachgelesen werden können. 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

Es wurden auch einige, wenige normale Web-APIs verändert. Dies wurde vor allem deswegen getan, um technische Probleme vermeiden zu können oder weil sie das Nutzererlebnis 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 App-Loader wurden kleine Anpassungen an bestehenden APIs vorgenommen, die technische Probleme oder Lücken fixen/verhindern sollen.

• 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 App-Loader gab es aus historischen Gründen noch einige APIs die seit Jahren nicht mehr zur offiziellen Dokumentation und damit API gehört haben. Diese wurden mittlerweile entweder entfernt (da sie sowieso nur für interne Verwendung gedacht waren) oder wurden mit Warnungen versehen, zu denen auch Migrations-Hinweise veröffentlicht wurden. Auf diese gehen wir nun etwas näher ein.

Zu beachten: Die APIs werden zu einem späteren Zeitpunkt entfernt. Dies wird mit ausreichender Vorlaufzeit angekündigt. Die Apps sollten zeitnah angepasst und die veralteten APIs mit aktuellen ausgetauscht werden.

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. Diese alte API wurde nach wenigen Monaten als "Deprecated" markiert, sie war auch niemals offiziell dokumentiert. Durch das Versäumnis, die HTML-UI-Demo-App an die neuen APIs anzupassen, hat sich die Verwendung dieser stark verbreitet. Die Demo-Apps mit HTML-ZU wurden mittlerweile auf die aktuellsten APIs aktualisiert.

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 konnte sie nicht ohne Weiteres entfernen werden. 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!