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!