Progressive Web App (PWA) [Admidio-Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Progressive Web App (PWA) ======

Starting with version 5.1, Admidio provides native support for **Progressive Web Apps (PWA)**. This feature allows members and administrators to install your Admidio installation directly from their web browser onto smartphones, tablets (Android, iOS/iPadOS), and desktop operating systems (Windows, macOS, Linux) as a standalone application – without requiring an app store!

{{:en:2.0:pwa:pwa_overview_banner.png?direct&600|Admidio as a Progressive Web App (PWA)}}

===== Key Benefits =====

  * **Native App Experience Without App Stores**: No downloads from Google Play or Apple App Store needed. Installation takes just a couple of clicks directly from your website.
  * **Fullscreen & Standalone Window**: The installed app launches in standalone mode without browser toolbars, address bars, or forward/back navigation chrome.
  * **Quick Access**: Dedicated app icon on smartphone home screens, Windows Start menu, macOS Launchpad, or the taskbar.
  * **Custom Organization Branding**: App name, startup theme colors, and icons automatically reflect your organization's identity.
  * **Offline Fallback & Performance**: Static assets (stylesheets, fonts, icons, JavaScript) are precached by a built-in Service Worker. If the network drops, a clean offline page is displayed.

===== Requirements =====

For modern browsers to enable and offer PWA installation, the following requirements must be met:

  - **HTTPS Encryption (SSL)**: Modern browsers restrict Service Workers and Web App Manifests strictly to secure HTTPS connections (or locally via ''localhost'' for development). If your installation does not yet use HTTPS, see [[en:2.0:https|HTTPS for Admidio Websites]].
  - **Admidio Version 5.1 or newer**
  - **A Modern Web Browser**:
    * **Android**: Google Chrome, Microsoft Edge, Samsung Internet, Firefox Mobile, Brave
    * **iOS / iPadOS (iPhone & iPad)**: Safari (iOS 11.3+, optimal support on iOS 16.4+)
    * **Desktop**: Windows 10/11 (Chrome, Edge), macOS (Chrome, Edge, Safari on macOS Sonoma+), Linux (Chrome, Chromium, Brave)
    * //Note on Desktop Firefox//: Mozilla Firefox currently does not support PWA installation on desktop operating systems. For a standalone desktop app window, using a Chromium-based browser is recommended.

===== User Installation Guide =====

Admidio automatically detects the user's operating system and browser, providing the most straightforward installation path.

==== 1. Android & Desktop (Google Chrome, Microsoft Edge, Brave) ====

On Chromium-based browsers, Admidio offers a convenient **one-click installation**:

  - When you visit Admidio, an **"Install app"** button (with a download icon) automatically appears in the top navigation bar.
  - On mobile devices, an unobtrusive installation banner with your organization logo appears near the bottom of the screen after a brief moment.
  - Click or tap **"Install app"** or **"Install"**.
  - Confirm the browser prompt by clicking **Install**.
  - That's it! The app shortcut is placed on your home screen or desktop application menu, ready to launch Admidio in a dedicated window.

{{:en:2.0:pwa:pwa_install_prompt.png?direct&400|Install Button and Mobile Banner}}

==== 2. Apple iOS & iPadOS (Safari on iPhone & iPad) ====

Apple Safari does not support automated 1-click web prompts. When tapping "Install app" on an iOS device, Admidio presents an illustrated step-by-step modal guide:

  - Tap the **Share button** (square with an arrow pointing upward) in Safari:
    * On **iPhone**: Toolbar at the bottom of the screen.
    * On **iPad**: Toolbar at the top of the screen.
  - Scroll down through the actions and select **"Add to Home Screen"**.
  - Tap **"Add"** in the top-right corner.
  - Admidio is now installed on your iOS home screen like a native app.

==== 3. Firefox Mobile (Android) ====

  - Tap the **three-dots menu** (⋮) next to the address bar (at the top or bottom).
  - Select **"Add to Home screen"** or **"Install"**.
  - Tap **Add** to confirm.

==== Where do I find the install option if I closed the banner? ====

If you previously dismissed the banner or navbar button by clicking the cross icon (''×''), you can still install the app at any time:
  * In the **User Profile Menu**: Click your name in the top right – you will find an **"Install app"** menu item.
  * In the **Footer**: At the bottom of every page, there is a permanent **"Install app"** link.
  * Via the **Browser Menu**: You can also use the browser's native three-dots menu (⋮) -> **"Install Admidio..."**.

Once Admidio is launched as an installed app in standalone mode, all install banners, buttons, and prompts are automatically suppressed.

===== Administrator Configuration =====

PWA support is active and preconfigured out of the box in Admidio 5.1. Administrators have full control over enabling/disabling the feature, branding, and app icons.

==== Enabling or Disabling PWA Support ====

In the administration area under //Settings > Preferences > General//:
^ Preference ^ Description ^ Default Value ^
| **Enable Progressive Web App (PWA)** | Controls the web app manifest, service worker registration, and installation prompts. | **Enabled** (Yes) |

When disabled:
  * No install buttons, banners, or guide modals are rendered.
  * The Service Worker is not registered.
  * Direct requests to ''system/manifest.json.php'' return HTTP 404 (Not Found).

==== Customizing the App Name ====

The name and short name of the installed app are derived automatically from your organization settings:
  * **Full App Name**: Taken from your organization's **Long name** (field ''org_longname'').
  * **Short App Name (Homescreen label)**: Taken from your organization's **Short name** (field ''org_shortname'').
  * You can update these at any time under //Organization > Basic Data//.

==== Customizing App Colors ====

The theme colors for the app's title bar and initial splash screen are inherited directly from your theme preferences:
  * **Theme Color (Title Bar & Window Frame)**: Uses the **Primary color** configured under //Settings > Preferences > Design// (Default: Admidio teal ''#349aaa'').
  * **Background Color (Splash Screen)**: Uses the **Background color** configured under //Settings > Preferences > Design// (Default: White ''#ffffff'').

===== Custom App Icons (Branding) =====

To display your organization's crest, coat of arms, or logo on member home screens, Admidio provides an automated multi-tier icon resolution system. You can supply custom icons **without modifying any core files**:

^ Priority ^ File Location & Name ^ Recommended Dimensions ^ Purpose ^
| **1 (Recommended)** | ''adm_my_files/app_icon_512.png'' | 512 × 512 px (PNG) | High-resolution master icon for home screens and app launchers. |
| **1b** | ''adm_my_files/app_icon_192.png'' | 192 × 192 px (PNG) | Standard icon for mobile home screens and taskbars. |
| **1c** | ''adm_my_files/app_icon.png'' | min. 512 × 512 px (PNG) | Universal icon (automatically scaled for all required resolutions). |
| **2** | ''adm_my_files/admidio_logo_512.png'' | 512 × 512 px (PNG) | Alternative organization logo in the data directory. |
| **3** | ''themes/<YourTheme>/images/admidio_logo_512.png'' | 512 × 512 px (PNG) | Theme-specific icon within the active theme folder. |
| **4** | Custom PNG favicon in //Settings > Preferences > Design// | Any (PNG) | Fallback from configured favicon. |
| **5 (Fallback)** | ''system/logo/admidio_logo_512.png'' | 512 × 512 px (PNG) | Default Admidio logo. |

> **Tip**: Simply upload your organization logo as a square PNG file (at least 512×512 pixels) named ''app_icon_512.png'' (or ''app_icon.png'') into the ''adm_my_files/'' folder. Because ''adm_my_files/'' is preserved during Admidio upgrades, your custom app icon will remain completely update-safe!

==== Maskable Icons for Android (Adaptive Icons) ====

Modern Android devices crop application icons dynamically according to the device manufacturer's style (circles, squircle, rounded rectangles).

  * **Preventing Color Clashes**: Transparent PNG logos are declared by Admidio as standard icons (''purpose: any''). This prevents Android from automatically filling the transparent background with the theme color (which could otherwise cause matching foreground logos to blend into the background).
  * **Full-Bleed Maskable Icon (Optional)**: If you want your app icon to span edge-to-edge across the entire mask shape, create an icon with a solid background (keeping the logo centered within the safe 80% inner circle) and upload it as:
    ''adm_my_files/app_icon_maskable_512.png'' (or ''adm_my_files/app_icon_maskable.png'')

===== Technical Architecture & Caching Strategy =====

For developers and administrators interested in internal workings:

  * **Dynamic Web App Manifest (''system/manifest.json.php'')**:
    * Dynamically rendered at runtime with header ''Content-Type: application/manifest+json''.
    * Start URL and scope are generated dynamically from ''ADMIDIO_URL''. As a result, the PWA works seamlessly on root domains (e.g. ''https://example.org/'') as well as arbitrary subdirectories (e.g. ''https://example.org/admidio/'').
  * **Service Worker (''sw.js'')**:
    * Manages asset caching and offline resilience.
    * **Pre-Caching**: Precaches vital core assets on initial visit.
    * **Network-First Strategy** for navigation and dynamic data: Admidio modules, database views, and forms are always requested directly from the server to guarantee data freshness.
    * **Cache-First Strategy** for static assets: Stylesheets, JavaScript libraries, web fonts, and images are cached locally, boosting page speed and decreasing server load.
    * **Offline Fallback**: If the network connection is lost during navigation, a clean bilingual offline page is shown with an instant reload button.
  * **Security & Privacy**:
    * No personal user records or database contents are cached in the Service Worker cache.
    * Browser storage calls (e.g. tracking dismissed banners in ''localStorage'') are wrapped in exception handlers (''try/catch''), ensuring error-free execution in strict private/incognito browsing environments.

===== Frequently Asked Questions (FAQ) =====

==== Why is the install button not showing up? ====
  - **HTTPS is not active**: Verify that you are accessing Admidio via ''https://''. Browsers prohibit PWA installation over insecure HTTP connections.
  - **App is already installed**: If Admidio is already running in standalone app mode, install prompts are intentionally hidden.
  - **Feature disabled in preferences**: Check //Settings > Preferences > General// and verify that "Enable Progressive Web App (PWA)" is switched on.
  - **Desktop Firefox**: Firefox does not support PWA installation on desktop computers. Please use Chrome, Edge, or Brave.
  - **Previously dismissed**: If you clicked "Do not show again", the prompt is hidden. You can still install the app via the user profile menu in the top right or the link in the footer.

==== How do updates work for installed apps? ====
Updates are completely automatic. Whenever you update Admidio on your web server or deploy new assets, the Service Worker detects the changes in the background and refreshes cached assets seamlessly (via ''skipWaiting'' and ''clients.claim''). Users do not need to reinstall the app.

==== How do I uninstall the app? ====
  * **Android**: Long-press the app icon on your home screen and select **Uninstall** (or drag it to the trash icon).
  * **iOS / iPadOS**: Long-press the icon on your home screen and select **Delete Bookmark** / **Delete App**.
  * **Windows / macOS**: Open the app window, click the three-dots menu (⋮) in the window title bar, and select **Uninstall [App Name]...**.