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!

• 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.

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

1. 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 HTTPS for Admidio Websites.
2. Admidio Version 5.1 or newer
3. 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.

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

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

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

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:

1. 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.
2. Scroll down through the actions and select “Add to Home Screen”.
3. Tap “Add” in the top-right corner.
4. Admidio is now installed on your iOS home screen like a native app.

1. Tap the three-dots menu (⋮) next to the address bar (at the top or bottom).
2. Select “Add to Home screen” or “Install”.
3. Tap Add to confirm.

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.

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.

In the administration area under Settings > Preferences > General:

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).

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.

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).

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:

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!

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)

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.

1. HTTPS is not active: Verify that you are accessing Admidio via https://. Browsers prohibit PWA installation over insecure HTTP connections.
2. App is already installed: If Admidio is already running in standalone app mode, install prompts are intentionally hidden.
3. Feature disabled in preferences: Check Settings > Preferences > General and verify that “Enable Progressive Web App (PWA)” is switched on.
4. Desktop Firefox: Firefox does not support PWA installation on desktop computers. Please use Chrome, Edge, or Brave.
5. 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.

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.

• 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]….