mittl medien | Webentwicklung in Stuttgart

miTT PWA Documentation (Progressive Web App) for Joomla

Setup and documentation of a Progressive Web App in Joomla.

Progressive Web App

Technically speaking, a Progressive Web App consists of a Service Worker who handles all requests between the server and browser. The prerequisite is that the contents are transmitted in encrypted form. Among other things, the manifest serves the purpose that when the app is installed on a mobile device, the App Icon is displayed. A detailed explanation of Progressive Web Apps (PWA) and which Optimizations for a PWA can be made, you will find in the articles. Services Worker and Manifest transforms the Joomla Website into a Progressive Web App that means Joomla to App.

Documentation miTT PWA FIRE PUSH Settings for Firebase Cloud Messaging

Documentation miTT PWA ONE PUSH Settings for sending push messages via One Signal

Table of content

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

Installation miTT PWA Progressive Web App for Joomla

Joomla miTT PWA (Progressive Web App) installieren

Joomla Global Configuration - Use Url RewriteBefore proceeding with the installation, make sure that "Use Url Rewrite" is set to "YES" in the Joomla global configuration. Before After successful installation, the settings can be made. To do so, go to the Plugins section and open miTT PWA. By activating and saving the plugin, the service worker file is created for the first time. To ensure a correct function, the Joomla PWA Plugin should be configured as follows:

Service Worker Version

Joomla App PWA Version

When the website (frontend) is called up for the first time, the service worker is installed or registered. From this point on, the Web page would be a PWA with only minimal functionality. The Service Worker Version parameter is used to version the static cache. If the version number is changed, the service worker causes the old cache in the browser to be deleted and a new one to be created when the Web page is called. Whenever the CSS or JavaScript is changed, the version number should be changed so that the user is always provided with the latest changes.

The Time interval for updating the Joomla PWA

When changes are made to the Service Worker, i.e. changes are made to the PWA at the user, the setting "Time interval for updating the Service Worker" is used. Here the Service Worker for the user is updated in the background, the cached files are deleted, and the static files are actualized if a new defined Service Worker version is set. The test mode is only for checking purposes because the time interval is set very short. The recommended setting is 3 to 23 hours.

If you plan to make several changes to the Joomla website or the static files CSS, JavaScript, the setting may be shorter. The update of the Service Worker will only be done if the Joomla Plugin with TT PWA is saved with a new Service Worker version.

Pull To Refresh

Pulling for updating is already known from native apps. Pulling down the app deletes and regenerates the app's offline memory.

Register Service Worker Async

The only thing that is determined here is how the registration is to take place. If there are problems during the registration installation, the Async registration can be set to no.


File Scope of the Service Worker

The Service Worker File is saved in the Joomla media folder. This is the standard for Joomla assets. In some cases is it difficult to set up the scope error, because there are not enough permissions. In this case, the scope can be set to the Joomla Root Folder. To set up the scope as standard try the Server setting.

App Scope

Joomla App PWA Version

Der Service Worker controls the whole Joomla Application. If this standard isn't wished, then you could choose different scope like /app. The url have to exist and the Start Url of the manifest have to be /app or /app/my-page. This feature doesn't allow handling multilanguage sites.

Unregister Service Worker - Debug Mode

Joomla App Debug Mode

The debug mode displays some information in the browser console in order to find errors more quickly.

If the PWA support is no longer desired or the service worker is faulty, it is possible to make this setting. This function should only be selected if the PWA is no longer required.

Tab Caching - Cache First or Network First

Cache First

The decision whether Cache First, Network First or Cache First / Network First depends on the Network Connection that can be made here.

Cache First means that all files in the service worker cache are read and updated with this request. If Cache First is active, changes to the content are only visible the second time the cache is called. However, there is a clear advantage in terms of speed. If there is no Internet connection and the requested page is not in the Cache, the offline page is used.

Network First

If Network First, the current contents are always retrieved and updated in the background of the offline cache. If there is no Internet connection, the system checks whether the corresponding page is in the cache. If not, the configured offline page would be displayed. Static Files will be delivered speedily from the Service Worker Cache.

Cache First - Network First depends on the network connection

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

When selecting Network First there is the possibility to choose the Cache First strategy depending on the quality of the Internet speed. This determines the effective network connection in terms of speed and latency. The value is then either "slow-2g", 2g, 3g or 4g. The miTT PWA plugin for Joomla allows you to configure the corresponding effective speeds, so that the selected value and worse the PWA network strategy Cache First would come to bear.


If files are loaded via CDN or a CDN plugin is used to receive files distributed over it, the CDN setting should be set to "Yes". If only Google fonts are transferred, the setting may be left at no. When using a CDN plugin, inline scripts must not be output via the CDN, otherwise, it is not possible to register the service worker.

Static Cache

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

The static cache is used to store the corresponding files when the page is first called up. It is recommended that the required JavaScript and CSS files are stored here in order to load them when the offline page is called up or when there is no Internet. For this purpose, all files that are or are required in the header should be entered. The content of the page itself is stored in a separate cache.

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

To enter the static cache, there are 2 possibilities, you can enter the paths one by one, or you can use the text input field to add several paths at the same time. If you choose the text area field, the paths must be separated by commas. A new line after the comma keeps the clarity.

If the files of the static cache are changed, the service worker version (setting in the Plugin tab) must be changed so that a new cache is created in the browser the next time the PWA or web page is called.

How do you update the static files of your Joomla PWA or website?

Cache exceptions

Joomla Progressive Web App Cache Ausnahmen - miTT PWA Joomla Plugin

As mentioned before, the content of the called page is put into a cache called 'pages'. If you don't want to cache certain pages and areas, you could exclude them here. To do this, select the term that appears in the URL. Then all the pages that contain the term in the URL are not cached and are loaded from there. An example would be the login page.

Offline Page

The offline page can be configured if desired. Under the following path /plugins/system/mittpwa/offline.html the offline page can be found in the Joomla installation. This is a pure HTML page and can be edited as desired. One possibility would be to copy the complete source code from the browser and then paste it into the offline.html. The content between Body can then be deleted and adjusted.

Fetch exceptions

Joomla Progressive Web App Cache Ausnahmen - miTT PWA Joomla Plugin

The service worker controls every request, so in a few cases, it is necessary to exclude certain requests so that the application can function correctly. You do not need to enter the whole path but only the word that appears in the link. If you exclude “nasa2” then will be ignored "/images/sampledata/cassiopeia/nasa2-640.jpg” and "/images/sampledata/cassiopeia/nasa2-1200.jpg”. The debug mode allows to control the action.

Console Log Fetch Request - Joomla App PWA


Joomla PWA Manifest

Among other things, the manifest is responsible for ensuring that the Progressive Web App can be installed. In this tab, the manifest could also be disabled if not desired. If you use your own manifest or customization, you could disable overwriting when saving the plugin.

App ID

The App ID is a unique string and ensures the identity of the PWA of the browser. The browser sees if the PWA is already installed. If you haven't set the App Id before, the browser match this with the Start Url. If you have a new PWA you could choose any string. If you have already published before 2021, the recommendation is to copy the ID from the manifest from the Chrome Dev Tools. In most cases is this the Start Url. Detailed information can be found on this page: "manifest id property"


Joomla PWA App ID

Decide what your app should be called and with which page the app should start. To do this, simply enter the url without the domain (e.g. /startpage). As default, the start page (/) is stored.

App Shortcuts

Joomla PWA App Shortcuts

To use App Shortcuts, activate them. Then you can define the App Shortcuts like name, description and icon. The App Shortcuts refer to a Joomla menu link. The icon should be defined as PNG in the size 192 x 192px. App Shortcuts are supported from Chrome version 84.

Joomla PWA Theme Color

Adjust the colours of your PWA and how the app should be displayed. If you should decide on "standalone" or a display without browser navigation, you should technically ensure that the navigation works smoothly without a browser.

Protocol Handler - Open your Joomla App from external resource

Joomla App Protocol Handler

The protocol handler offers to open the the App from external resource for example e-mail. You have a link in your e-mail like

<a href="web+blog://8">Joomla Blog</a>

and your installed PWA will be open after clicking. This feature works on chromium based browser for desktop and android. The 8 stands for the category id.

To set up protocol, put could put web+yourTopic. "web" means in this case the Web browser. Following safelisted-scheme are available. After the plus, choose your topic of your app.

Here you copy the desired value of the menu using %s as a placeholder. Example: '/index.php?option=com_content&view=article&id=%s' . The url is called as follows web+article://4

4 stands for the article

Another example would be the blog page. Here the value is 'index.php?option=com_content&view=category&layout=blog&id=%s' . The entire url could then look like this web+blog://8

Homepage: web+home://option=com_content&view=featured - set up for url index.php?

Test Protocol Handler - open App - PWA

To test the feature to install the Joomla PWA first on your device, then go to the Developer Tools, Tab Application - Manifest and put your url path resp. id in the input protocol handler field. After to click the "Test protocol" button and then should open your installed Joomla App with the right page.

Joomla App Protocol Handler

At there is a detailed article about Protocol Handler.

Theme Colors

Joomla PWA Theme Color

Adjust the colours of your PWA and how the app should be displayed. If you should decide on "standalone" or a display without browser navigation, you should technically ensure that the navigation works smoothly without a browser.

PWA App Icons

Joomla PWA App Icons

The different operating systems of an Android smartphone display the icons differently. To achieve the best possible result, create 4 Icons, two of there has the size 512x512 Pixel, the Apple Icon has 180x180px and the SVG is vector based.

Please use the naming as mentioned above. To create the icons, use the app of your choice or take the PWA Asset Generator. The advantage of the generator is, that you have all icons and iOS Splash Screen images in one step. The command after installation could be as follows:

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

For a better result for the Maskable Icon, use the Maskable-App-Editor . The SVG icon is not absolutely necessary, but improves the compatibility. Don't forget to upload it via FTP.

Create a folder named "pwa-assets" or "icons" where you put the icons in there. Upload the folder via FTP to your images folder. Select this folder in the plugin settings.

Legacy Icons

If you are an existing miTT PWA User and you don't want to create new icons now. There is the Icons Legacy option, if you put the setting on Yes. If you would like to use the new implementation, go to App Icons and iOS Splash Screen Images.

App Screenshots

Joomla PWA App Screenshots

App Screenshots give the user a new installation experience of a PWA. The screenshots will be displayed on the install prompt banner. Please ensure the width and height of your screenshots are the same and put them in the provided fields.

Joomla PWA App Screenshots

iOS PWA installation

Joomla PWA iOS Install experience

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

Apples Splash Images

If you would like to use the Apple Splash Images, use the PWA Asset Generator and upload to your defined icons folder. Please don't change the name of the generated files. Splash Screen will be shown if you start the app and the content could not be displayed.

iOS installation Banner

Apple iOS does not yet support a button to install the Web App on the iPhone. To install the Progressive Web App on the iOS smartphone, it must be added to the home screen. There is here an option to show a banner note, where the user gets the information on how to install the PWA under iOS. Under "iOS Banner Pop Up Click" there is a way to define a "Custom Alert Page", which describes the way to install the PWA on iOS. The other possibility is to use the standard "Alert Pop Up", which is suitable via Joomla language override.

The top bar on iOS devices, which contains the time, Wi-Fi status and battery, is called the iOS Status Bar. It can be defined with the "default" value for white background and black text. Black stands for black background, and "black-translucent" takes the background of the body HTML element. The text colour is white. To make the iOS Status Bar the same colour as the navigation, the body colour in the template must be adjusted accordingly.

Custom or own Install Button for the PWA (Android) Custom Installation Banner Joomla PWA

Depending on the app, a separate installation option of a PWA is useful. If activated, the standard banner will be blocked for the time being. This allows an own button to be integrated into the website. This button must have the CSS class "mittpwa__install__a2hs" to trigger the installation of the PWA. The installation button is hidden in the Safari browser and Firefox desktop version. If the browser does not support the installation of a PWA, the button is inactive or cannot be clicked. Here is the example code with the corresponding class:

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

The button can be integrated via a Joomla Module, a Joomla Article or the Standard Template.

Periodic Background Sync

Joomla PWA Periodic Background Sync

Under the tab Sync you can set the background synchronization for HTML and images in the mobile web app (Joomla PWA). Here, the content of the URLs is synchronized in the background at set intervals. The website visitor usually has to agree to this action. The configurable Sync Interval is a guideline value because the browser does not perform a background update in case of different criteria like low battery or high CPU load. Furthermore, miTT PWA does not allow any sync if there is no free space available on the mobile device.

The background synchronization of a PWA is very useful if the content is updated frequently, and you want to provide a high offline experience with up-to-date data to the user. Even content that the website visitor has not yet accessed can be cached.

To allow the user to do this, simply copy the url from the address line of the post or image without the web page name into the URL Path input field provided. This feature is available to all newer chrome-based browsers like Chrome and Edge.


Please check the Joomla Global Configuration, if the "Use Url Rewrite" is on "Yes".

Apache Server

If you use an Apache Server, then should write the install script during the installation written in the .htaccess file the following line that should avoid the scope error. If you have the scope error in the Browser Console, then please check if the lines exist.

  <Files "(serviceworker\.js|OneSignalSDKUpdaterWorker\.js|OneSignalSDKWorker\.js)"> 
      Header Set Service-Worker-allowed "/"

NGINX Server

If your Site is running on a NGINX server then you have to add the following below at the nginx config. The same applies it to Plesk if you are using Nginx for a proxy.

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

In Plesk you find this in "Hosting & DNS" and "Apache and Nginx Setting". At the bottom is the field to add the lines. Ngnix Config Field Ngnix Setting

LiteSpeed Server

LiteSpeed set the right header of the Service Worker as follows. Add this in your .htaccess file.

   service-worker-allowed: /

If you use Cloudflare, you have to delete the cache, if you change this kind of settings.

Testing - Find the failure

Service Worker

To check if everything works as desired, we recommend using Chrome Browser in the first test, because it provides tools. A basic condition for the correct installation of the Service Worker is an encrypted website. To test it in a local environment without encryption, the site must be accessible on localhost and the browser line must also show http://localhost.

In the Chrome Browser, open the console and switch to the tab "Application". If the Service Worker is correctly installed, a solid icon will be displayed at Status. Furthermore, it is very easy to simulate via the offline mode, simply tick the box.

Chrome Browser Console Joomla PWA


At the tab Application on the left side, click on Manifest. Check here if there are any errors and the icons can be loaded.

Joomla PWA App Manifest

A valid Manifest and Service Worker are necessary for the install prompt.

Lighthouse PWA Test

Google also provides Lighthouse with the Chrome Browser to check the website for performance, Progressive Web App, best practices, accessibility and SEO. A test shows whether the website has the functionality of a PWA.

If the error "start_url does not respond with a 200 when offline. The start_url did respond, but not via a service worker., then you should check if the start page is available offline. The easiest way is to check the Offline box under "Application" in Chrome Browser.

Alternatively, you can also add Firefox "Lighthouse" by using this Link in the bookmark list of the browser or right-click to add it to the bookmark list. Afterwards, you visit the desired page and click on this link and a Lighthouse Test is performed.

Changelog miTT PWA for Joomla

Joolmla PWA Changelog

In this tab, the changes are documented to see which new features are available and which problems have been fixed. In order to benefit from the new features, it is necessary to save the plugin in addition to updating it.

Joomla to App

It is easy to create a full Joomla App experience with the miTT PWA for Joomla. Here can you find the available Joomla PWA possibilities to create a PWA. The difference between the Joomla App (PWA) is only the Push Notifications.

Documentation miTT PWA FIRE PUSH

advanced settings for miTT PWA FIRE PUSH


Dokumentation miTT PWA ONE PUSH

advanced settings for miTT PWA ONE PUSH



Frequently Questions