Account
mittl medien | Webentwicklung in Stuttgart

miTT PWA Dokumentation (Progressive Web App) für Joomla

Einrichtung und Dokumentation einer Progressive Web App in Joomla.

Progressive Web App

Technisch gesehen besteht eine Progressive Web App aus einem Service Worker, welcher alle Request zwischen Server und Browser kontrolliert. Voraussetzung ist, dass die Inhalte verschlüsselt übertragen werden. Das Manifest dient unter anderem, dass bei Installation der App auf einem Endgerät das App Icon dargestellt wird. Eine detailierte Erklärung über Progressive Web Apps (PWA) und welche Optimierungen bei einer PWA vorgenommen werden können, finden Sie in den Artikeln.

Dokumentation miTT PWA FIRE PUSH Einstellungen für Firebase Cloud Messaging

Dokumentation miTT PWA ONE PUSH Einstellungen für das Versenden von Push Nachrichten über One Signal

Inhaltsverzeichnis

  1. Installation
  2. Service Worker Version
  3. Caching
  4. Static Cache
  5. Manifest
  6. App ID
  7. App Shortcuts
  8. App Icons
  9. Legacy Icons
  10. App Screenshots
  11. iOS
  12. iOS Splash Screen
  13. Custom Install button
  14. Background Sync
  15. Server
  16. Testing - Fehlersuche
  17. Lighthouse
  18. Changelog

Installation miTT PWA Progressive Web App für Joomla

Joomla miTT PWA (Progressive Web App) installieren

Joomla Global Configuration - Use Url Rewrite

Bevor man die Installation durchführt, sollte man sicherstellen, dass "Url Rewrite nutzen" in der Joomla Konfiguration auf "JA" steht. Nach erfolgreicher Installation können die Einstellungen vorgenommen werden. Hierzu geht man in den Bereich Plugins und öffnet miTT PWA. Indem man das Plugin aktiviert und speichert, wird erstmals der Service Worker Datei erstellt. Um eine korrekte Funktion zu gewährleisten, sollte wie folgt das Joomla PWA Plugin konfiguriert werden.

Service Worker Version

Beim Erstaufruf der Webseite (Frontend) wird der Service Worker installiert bzw. registriert. Ab diesem Zeitpunkt wäre die Webseite eine PWA mit nur geringer Funktion. Der Parameter Service Worker Version dient dazu, um den statischen Cache zu versionieren. Bei Änderung der Versionsnummer wird der Service Worker bei Aufruf der Webseite dazu veranlasst, dass der alte Cache im Browser gelöscht, sowie ein neuer angelegt wird. Bei jeder Änderung im CSS oder Javascript sollte die Versionsnummer geändert werden, sodass der Nutzer immer mit den neuesten Änderungen versorgt wird.

Zeitintervall für die Aktualisierung der Joomla PWA

Bei Änderungen am Service Worker d.h. Änderungen an der PWA beim Benutzer einzuspielen, dient die Einstellung "Zeitintervall für die Aktualisierung des Service Workers". Hier wird im Hintergrund der Service Worker beim Benutzer auf den aktuellen Stand gebracht, die im Cache liegenden Dateien gelöscht und die statischen Files aktualisiert, sofern eine neue festgelegte Service Worker Version festgelegt wurde. Der Testmode dient nur zur Überprüfung, da das Zeitintervall sehr kurz gesetzt ist. Die empfohlene Einstellung dafür liegt bei 3 bis 23 Stunden.

Sollte man planen, an der Joomla Webseite mehrere Änderungen oder an den statischen Dateien CSS, JS vorzunehmen, dann darf die Einstellung auch kürzer sein. Die Aktualisierung des Service Worker wird nur dann vorgenommen, wenn das Joomla Plugin miTT PWA mit einer neuen Service Worker Version gespeichert wird.

Register Service Worker Async

Hier wird lediglich bestimmt, wie die Registrierung erfolgen soll. Sollte es bei der Registrierung Installation Probleme geben, kann die Async Registrierung auf nein gestellt werden.

Unregister Service Worker

Sollte man die PWA Unterstützung nicht mehr wünschen bzw. der Service Worker fehlerhaft ist, dann besteht die Möglichkeit in dieser Einstellung es vorzunehmen. Diese Funktion sollte nur dann gewählt werden, wenn die PWA nicht mehr benötigt wird.

Tab Caching - Cache First oder Network First

Joomla Progressive Web App Caching - Network First - miTT PWA

Cache First

Die Entscheidung, ob Cache First, Network First oder Cache First in Abhängigkeit von der effektiven Internetverbindung kann hier getroffen werden.

Cache First bedeutet, dass alle im Service Worker Cache befindlichen Dateien ausgelesen werden und bei diesem Request aktualisiert werden. Wenn Cache First aktiv ist, dann sind inhaltliche Änderungen erst beim zweiten Aufruf sichtbar. Jedoch spürt man einen deutlicheren Vorteil in Bezug auf die Geschwindigkeit. Sollte Internetverbindung und die aufgerufene Seite fehlen, dann wird auf die Offline Page zurückgegriffen.

Network First

Bei Network First werden immer die aktuellen Inhalte abgerufen und im Hintergrund der Offline Cache aktualisiert. Sollte keine Internetverbindung vorhanden sein, dann wird geprüft, ob die entsprechende Seite im Cache liegt. Im Falle des Nichtvorhandenseins würde die konfigurierte Offline Seite angezeigt werden. Die statischen Files werden vom Service Worker Cache geholt, so dass diese immer schnell ausgeliefert werden können.

Cache First - Network First in Abhängigkeit von der Internetgeschwindigkeit

Joomla Progressive Web App Caching - Network Network Connection - miTT PWA

Bei Auswahl von Network First besteht die Möglichkeit bei schlechter Internetverbindung die Strategie Cache First in Abhängigkeit zu der Qualität der momentanen Internetgeschwindigkeit zu wählen. Dabei wird die effektive Netzwerkverbindung bezüglich Geschwindigkeit und Latenz ermittelt. Der Wert ergibt dann entweder "slow-2g", 2g, 3g oder 4g. Das miTT PWA Plugin für Joomla ermöglicht die Konfiguration der entsprechenden effektiven Geschwindigkeiten, so dass dann der gewählte Wert und schlechter die PWA Netzwerk Strategie Cache First zum tragen kommen würde.

Wie aktualisieren Sie Ihre statischen Dateien (Browser-Cache-Benutzer) in der PWA?

CDN

Sollten Dateien über CDN geladen werden oder es wird ein CDN Plugin benutzt, um Dateien verteilt darüber zu empfangen, ist die Einstellung CDN auf "Ja" vorzunehmen. Wenn es lediglich um Google Fonts handelt, darf die Einstellung auf nein bleiben. Bei Benutzung eines CDN Plugins dürfen Inline Scripte nicht über das CDN ausgegeben werden, ansonsten ist eine Registrierung des Service Workers nicht möglich.

Statischer Cache

Joomla Progressive Web App Caching - Static Cache - miTT PWA Plugin

Der statische Cache dient dazu, beim Erstaufruf der Seite die entsprechenden Files zu hinterlegen. Hier ist empfehlenswert, dass die benötigten Javascript und CSS Dateien gespeichert werden, um diese dann zu laden, um die Offline Seite aufzurufen oder wenn kein Internet besteht. Hierzu sollte alle Dateien, die im Header sind bzw. benötigt werden eingetragen werden. Der Inhalt der Seite selbst wird in einen separaten Cache gelegt.

Wie wird der Cache des Browser aktualisiert (Video in English)?

Joomla Progressive Web App Caching - Static Cache List - miTT PWA Joomla Plugin

Um den statischen Cache einzutragen, gibt es 2 Möglichkeiten, man kann einzeln die Pfade nacheinander eintragen oder man benutzt das Texteingabefeld, um gleichzeitig mehrere Pfade hinzuzufügen. Bei Wahl des Texteingabefeldes müssen die Pfade durch Kommas getrennt sein. Eine neue Zeile nach dem Komma wahrt die Übersichtlichkeit.

Bei Änderungen der Files des statischen Cache ist die Service Worker Version (Einstellung im Tab Plugin) zu ändern, sodass ein neuer Cache im Browser beim nächsten Aufruf der PWA bzw. Webseite angelegt wird.

Cache Ausnahmen

Joomla Progressive Web App Cache Ausnahmen - miTT PWA Joomla Plugin

Wie zuvor bereits erwähnt wird der Inhalt der aufgerufenen Seite in einen Cache names 'pages" gelegt. Wenn man bestimmte Seiten und Bereiche nicht in den Cache legen will, könnte man diese hier ausschließen. Hierzu wählt man den Begriff, welcher in der URL vorkommt. Dann werden all die Seiten, die den Begriff in der URL enthalten, nicht gecached und aus diesem Cache geladen. Als Beispiel wäre es die Login Seite.

Offline Seite

Die Offlineseite kann bei Wunsch konfiguriert werden. Unter folgendem Pfad /plugins/system/mittpwa/offline.html ist die Offline Seite in der Joomla Installation zu finden. Das ist eine reine HTML Seite und kann beliebig editiert werden. Eine Möglichkeit wäre, den kompletten Quelltext aus dem Browser zu kopieren und dann in die offline.html einzufügen. Der Inhalt zwischen Body kann dann gelöscht und angepasst werden.

Manifest

Joomla PWA Manifest

Das Manifest ist unter anderem dafür verantwortlich, dass die Progressive Web App installiert werden kann. In diesem Tab könnte das Manifest auch deaktiviert werden, falls es nicht gewünscht wird. Bei Verwendung eines eigenen Manifests oder Anpassung könnte man das Überschreiben beim Speichern des Plugins deaktivieren.

App ID

Die App-ID ist eine eindeutige ID und stellt die Identität der PWA des Browsers sicher. Der Browser erkennt daran, ob die PWA bereits installiert ist. Wenn Sie die App-ID nicht vorher festgelegt haben, gleicht der Browser diese mit der Start-Url ab. Wenn Sie eine neue PWA haben, können Sie eine beliebige Zeichenfolge wählen. Wenn Sie bereits vor 2021 veröffentlicht haben, empfiehlt es sich, die ID aus dem Manifest in den Chrome Dev Tools zu kopieren. In den meisten Fällen ist dies die Start Url. Detailierte Informationen findet man unter dieser Seite: "manifest id property"

.

Joomla PWA App ID

Entscheiden Sie wie Ihre App heißen soll und mit welcher Seite die App starten soll. Dazu geben Sie einfach die URL ohne die Domain an (z.B. /startseite). Als Default ist die Startseite (/) hinterlegt.

App Kurzbefehle (App Shortcuts)

Joomla PWA App Shortcuts

Um App Kurzbefehle bzw. Schnell-Navigation zu nutzen aktivieren man diese. Danach können die App Kurzbefehle wie der Name, Beschreibung und Icon definiert werden. Die Schnell-Verknüpfungen verweisen auf einen Joomla Menülink. Das Icon sollte in der Größe 192 x 192px als PNG definiert sein. App Kurzbefehle (App Shortcuts) wird ab Chrome Version 84 unterstützt.

Joomla PWA Theme Color

Passen Sie noch die Farben Ihrer PWA an und wie die App dargestellt werden soll. Sollten Sie sich für "standalone" (empfohlene Einstellung) oder eine Darstellung ohne Browser-Navigation entscheiden, sollte man technisch sicherstellen, dass die Navigation reibungslos ohne Browser funktioniert.

PWA App Icons

Joomla PWA App Icons

Die verschiedenen Betriebssysteme eines Android-Smartphones zeigen die Icons unterschiedlich an. Um das bestmögliche Ergebnis zu erzielen, erstellen Sie 4 Icons, zwei davon haben die Größe 512x512 Pixel, das Apple Icon hat 180x180px und das SVG ist vektorbasiert.

Bitte verwenden Sie die oben erwähnte Namensgebung. Um die Icons zu erstellen, verwenden Sie die App Ihrer Wahl oder nehmen Sie den PWA Asset Generator. The advantage of the generator is, that you have all icons and iOS Splash ScreenBildern ein einem Schritt definieren können. Der Befehl nach der Installation könnte wie folgt lauten:

pwa-asset-generator /yourFolder/mitt_pwa_blank.png ~/yourFolder/assets -b "#323232"

Um ein besseres Ergebnis für dasMaskable Icon zu bekommen, empfehle ich den Maskable-App-Editor zu verwenden.. Das SVG-Symbol ist nicht unbedingt erforderlich, verbessert aber die Kompatibilität. Vergessen Sie nicht, es per FTP hochzuladen.

Erstellen Sie einen Ordner mit dem Namen "pwa-assets" oder "icons", in dem Sie die Icons ablegen. Laden Sie den Ordner per FTP in Ihren Bilderordner hoch. Wählen Sie diesen Ordner in den Plugin-Einstellungen aus.

Legacy Icons

Wenn Sie ein bestehender miTT PWA-Benutzer sind und keine neuen Icons erstellen möchten. Es gibt die Option Icons Legacy, wenn du die Einstellung auf Yes setzt. Wenn Sie die neue Implementierung verwenden möchten, gehen Sie zu App Icons undiOS Splash Screen Bilder.

App Screenshots

Joomla PWA App Screenshots

App-Screenshots bieten dem Benutzer ein neues Installationserlebnis für eine PWA. Die Screenshots werden im Banner der Installationsaufforderung angezeigt. Bitte stellen Sie sicher, dass die Breite und Höhe Ihrer Screenshots gleich sind und fügen Sie sie in die vorgesehenen Felder ein.

Joomla PWA App Screenshots

iOS PWA Installation

Joomla PWA iOS Install experience

The Apple Icon needs an image sized 180x180px. You have to upload it to your icons folder, where you defined before at App Icons, if you haven't done it before.

Apples Splash Images

Wenn Sie die Apple Splash Images verwenden möchten, benutzen Sie den PWA Asset Generator und in den von Ihnen definierten Icon-Ordner hochgeladen. Bitte ändern Sie den Namen der generierten Dateien nicht. Der Splash Screen wird angezeigt, wenn Sie die App starten und der Inhalt nicht angezeigt werden kann.

iOS Installation Banner

Apple iOS unterstützt noch keine Funktion zur Installation der Web-App auf dem iPhone. Um die Progressive Web App auf dem iOS-Smartphone zu installieren, muss sie zum Startbildschirm hinzugefügt werden. Hier gibt es die Möglichkeit, einen Banner-Hinweis einzublenden, der den Nutzer darüber informiert, wie er die PWA unter iOS installieren kann. Unter "iOS Banner Pop Up Click" gibt es eine Möglichkeit, eine "Custom Alert Page" zu definieren, die den Weg zur Installation der PWA unter iOS beschreibt. Die andere Möglichkeit ist, das Standard "Alert Pop Up" zu verwenden, das über die Joomla Language Override anpassbar ist.

Die obere Leiste auf dem iOS-Geräte, welche Uhrzeit, WLAN Status und Batterie enthält, nennt sich iOS Status Bar. Die kann mit dem "default" Wert für weißer Hintergrund und schwarzer Text definiert werden. Black steht für schwarzer Hintergrund und "black-translucent" nimmt den Hintergrund des Body HTML Elements an. Die Textfarbe ist weiß. Um die iOS Status Bar in gleicher Farbe wie die Navigation zu gestalten, muss die Body Farbe im Template dementsprechend angepasst werden.

Custom bzw. eigener Install Button für die PWA

Custom Installation Banner Joomla PWA

Je nach App ist eine eigene Installationsmöglichkeit einer PWA sinnvoll. Bei Aktivierung wird die der Standard Banner vorerst blockiert. Dadurch kann ein eigener Button in die Webseite eingebunden werden. Dieser Button muss die CSS Klasse "mittpwa__install__a2hs" haben, um den Trigger der Installation der PWA auslösen zu können. Der Installations-Button wird im Safari Browser und Firefox Desktop Version ausgeblendet. Sollte der Browser die Installation einer PWA nicht unterstützen, ist der Button inaktiv bzw. nicht anklickbar. Hier der Beispielcode mit der zugehörigen Klasse:

<button class=" mittpwa__install__a2hs">Install</button>

Der Button kann über ein Joomla Modul, über einen Joomla Beitrag oder das Standard Template eingebunden werden. Sollte kein Installationshinweis gewünscht werden, kann der "Install Prompt" der PWA auch unterdrückt werden.

Periodic Background Sync

Joomla PWA Periodic Background Sync

Unter dem Tab Sync kann in der mobilen Web App (Joomla PWA), die Hingrund-Synchronisation für HTML und Images eingestellt werden. Hier werden im Hintergrund die Inhalte der Urls jeweils in den eingestellten Intervallen synchronisiert. Der Webseitenbesucher muss meist dieser Aktion zustimmen. Die konfigurierbare Sync Intervall ist ein Richtwert, da der Browser bei verschiedenen Kriterien wie geringer Akku oder hoher CPU Auslastung keine Hintergrund Aktualisierung durchgeführt wird. Zudem lässt miTT PWA keinen Sync zu, falls kein freier Speicherplatz auf dem mobilen Endgerät verfügbar ist.

Die Hintergrund Synchronisation einer PWA ist dann sehr sinnvoll, wenn die Inhalte oft aktualisiert werden und man eine hohe Offline Experience mit aktuellen Daten dem Benutzer zur Verfügung stellen möchte. Auch Inhalte, die der Webseitenbesucher noch nicht aufgerufen hat, können so in den Cache wandern.

Um dem Nutzer dies zu ermöglichen kopieren Sie einfach die URL aus der Adresszeile der Beitrage oder des Bildes ohne den Webseiten Namen in die dafür vorgesehenes Eingabefeld URL-Pfad. Dieses Feature steht allen neueren chrome-basierten Browsern wie Chrome und Edge zur Verfügung.

Server

Bitte prüfen Sie in der Joomla Global Konfiguration, ob die Option "Use Url Rewrite" auf "Ja" steht.

Apache Server:
Wenn Sie einen Apache Server verwenden, dann werden während der Installation folgende Zeile in die .htaccess-Datei geschrieben, die den Scope-Fehler verhindern. Wenn Sie den Geltungsbereich haben, dann überprüfen Sie bitte, ob die Zeilen existieren.
 <Files "(serviceworker\.js|OneSignalSDKUpdaterWorker\.js|OneSignalSDKWorker\.js)"> 
      Header Set Service-Worker-allowed "/"
 </Files>

Wenn Ihre Website auf einem NGINX-Server läuft, müssen Sie in der Nginx-Konfiguration Folgendes hinzufügen. Dasselbe gilt für Plesk Configuration, z.B. wenn Sie Nginx als Proxy verwenden.

 location ~* /(serviceworker\.js|OneSignalSDKUpdaterWorker\.js|OneSignalSDKWorker\.js) {
        add_header 'Service-Worker-Allowed' '/';
 }

In Plesk finden Sie dies unter "Hosting & DNS" und "Apache und Nginx Einstellung". Ganz unten befindet sich das Feld zum Hinzufügen der Zeilen. Ngnix Config Field Ngnix Setting

Wenn Sie Cloudflare verwenden, müssen Sie den Cache löschen, wenn Sie diese Art von Einstellungen ändern.

Testing - Finde den Fehler

Service Worker

TUm zu prüfen, ob alles wie gewünscht funktioniert, empfehlen wir, für den ersten Test den Chrome-Browser zu verwenden, da dieser Tools bereitstellt. Eine Grundvoraussetzung für die korrekte Installation des Service Workers ist eine verschlüsselte Website. Um ihn in einer lokalen Umgebung ohne Verschlüsselung zu testen, muss die Seite auf localhost erreichbar sein und die Browserzeile muss ebenfalls http://localhost anzeigen.

Öffnen Sie im Chrome-Browser die Konsole und wechseln Sie auf die Registerkarte "Anwendung". Wenn der Service Worker korrekt installiert ist, wird unter Status ein solides Symbol angezeigt. Außerdem ist es sehr einfach, über den Offline-Modus zu simulieren, indem Sie einfach das Kästchen anklicken.

Chrome Browser Console Joomla PWA

Manifest

Klicken Sie auf der Registerkarte App auf der linken Seite auf Manifest. Prüfen Sie hier, ob es Fehler gibt und die Symbole geladen werden können.

Joomla PWA App Manifest

Für die Installationsaufforderung sind ein gültiges Manifest und ein Service Worker erforderlich.

Lighthouse PWA Test

Google stellt mit dem Chrome Browser auch Lighthouse zur Verfügung, um die Webseite nach Performance, Progressive Web App, Best Practices, Accessibility und SEO zu prüfen. Ein Test zeigt, ob die Webseite die Funktionalitäten einer PWA besitzt.

Falls der Fehler "start_url does not respond with a 200 when offlineThe start_url did respond, but not via a service worker., dann sollte man überprüfen ob die Startseite Offline verfügbar ist. Am einfachsten ist in Chrome Browser unter "Application" das Offline Häckchen zu setzen.

Alternativ kann auch Firefox "Lighthouse" hinzufügen, indem man diesen Link in die Bookmark Liste des Browsers zieht oder mit Rechtsklick in die Bookmark Liste aufnimmt. Danach besucht man die gewünschte Seite und klickt auf diesen Link und ein Lighthouse Test wird durchgeführt.

Changelog miTT PWA für Joomla

Joolmla PWA Changelog

In diesem Tab werden die Änderungen dokumentiert, um zu sehen, welche neue Features vorhanden sind, sowie welche auftretende Probleme behoben wurden. Um von den neuen Funktionen zu profitieren neben der Aktualisierung ist auch die Speicherung des Plugins nötig.

Dokumentation miTT PWA FIRE PUSH

erweiterte Einstellungen für miTT PWA FIRE PUSH

Lesen Sie mehr...

Dokumentation miTT PWA ONE PUSH

erweiterte Einstellungen für miTT PWA ONE PUSH

Lesen Sie mehr...

FAQ

Häufig gestellte Fragen

Lesen Sie mehr...