Building Progressive Web Apps (PWAs) with OutSystems

In Service Studio, look at the **Application Layer Tabs** on the right side. Click the **Interface tab**. At the top of the Interface tree, right-click your **application name** (the root node, not a module) → **Properties** to open the app properties panel. Alternatively, in the main editor, double-click on the app icon in the application toolbar at the top of Service Studio. In the **Properties panel** (right side), scroll down to the **Progressive Web App** section. Find the **Distribute as PWA** toggle → set it to **Yes**. Publish the module: click the **1-Click Publish** button (top center). After publishing, the app generates a manifest.json and registers a service worker.

With the PWA toggle enabled, go back to the **app Properties panel** in Service Studio. In the **Progressive Web App** section, configure: - **Application Name**: The full name shown on the home screen (e.g., `Inventory Manager`) - **Short Name**: Used when space is limited on home screen, max 12 characters (e.g., `Inventory`) - **Description**: Shown in some PWA install prompts - **Theme Color**: Hex color for the browser/status bar when the app is open (e.g., `#2C6ECB`) - **Background Color**: Splash screen background while app is loading (e.g., `#FFFFFF`) - **Display Mode**: Standalone (no browser chrome, most native-like), Minimal UI (shows URL bar), Browser (standard), or Fullscreen - **Application Scope**: The URL path scope — usually `/` for the full app **Add icons:** Interface tab → select your app root → find **App Icon** property → click to upload 192x192 PNG (required) and 512x512 PNG (required for splash screens). OutSystems generates the manifest iconList from these.

1/* Generated manifest.json (for reference — OutSystems creates this automatically) */
2{
3  "name": "Inventory Manager",
4  "short_name": "Inventory",
5  "description": "Manage your inventory offline and online",
6  "start_url": "/YourModule/",
7  "scope": "/YourModule/",
8  "display": "standalone",
9  "theme_color": "#2C6ECB",
10  "background_color": "#FFFFFF",
11  "icons": [
12    {
13      "src": "/YourModule/img/AppIcon_192.png",
14      "sizes": "192x192",
15      "type": "image/png"
16    },
17    {
18      "src": "/YourModule/img/AppIcon_512.png",
19      "sizes": "512x512",
20      "type": "image/png",
21      "purpose": "any maskable"
22    }
23  ]
24}

To verify the PWA is installable, use Chrome on desktop or Android: **Desktop Chrome:** 1. Open your published app URL in Chrome 2. Look for the install icon in the address bar (computer screen with down arrow) 3. Click it → 'Install [App Name]' 4. The app opens in a standalone window without the browser address bar **Chrome DevTools Lighthouse test:** 1. Open DevTools (F12) → **Lighthouse** tab 2. Select **Progressive Web App** category → Generate Report 3. Review the PWA checklist — OutSystems should pass: HTTPS, manifest, service worker, icons, theme color 4. Common failure: 'Does not provide a valid apple-touch-icon' — add a 180x180 iOS icon **Android:** Open the app in Chrome for Android → three-dot menu → 'Add to Home Screen' → follow prompts

OutSystems generates a service worker that uses a **network-first with cache fallback** strategy for app resources. When the device is offline, it serves the cached version of the app shell (HTML, CSS, JS). This means the app loads offline — but data is NOT available offline unless you also use Local Storage entities (Mobile module only). To add custom caching behavior, add a JavaScript file via **Interface tab → Scripts → Add Script** → name it `sw-custom.js`. Register it as a Required Script on the main screen. For custom caching of API responses, use the Workbox library or plain Cache API in a JavaScript node: **Note**: OutSystems' service worker is generated and may be overwritten on publish. Customizations must be applied through OutSystems' extension points, not by directly editing the generated service worker file.

1/* JavaScript node in a Client Action — demonstrate cache usage check */
2/* Checks if service worker is registered and active */
3var output = false;
4if ('serviceWorker' in navigator) {
5    navigator.serviceWorker.getRegistration().then(function(reg) {
6        if (reg && reg.active) {
7            $parameters.IsServiceWorkerActive = true;
8        }
9    });
10}
11
12/* Check if app is running in standalone (installed PWA) mode */
13var isStandalone = window.matchMedia('(display-mode: standalone)').matches
14    || window.navigator.standalone === true;
15$parameters.IsInstalledPWA = isStandalone;
16
17/* Show iOS install instructions only on iOS Safari in non-standalone mode */
18var isIOS = /iPhone|iPad|iPod/.test(navigator.userAgent);
19var isSafari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
20$parameters.ShowIOSInstallHint = isIOS && isSafari && !window.navigator.standalone;

PWAs running in standalone mode behave differently from browser tabs: **Back navigation**: There is no browser back button in standalone mode. Implement in-app back navigation using a Button or Link widget → Client Action → JavaScript node with `$public.Navigation.navigateBack()` or `history.back()`. **App updates**: When you publish a new version, the service worker detects the change and installs the new version in the background. Users see the update only after they close and reopen the PWA. To prompt immediate updates: In a JavaScript node on the main screen load: ```javascript navigator.serviceWorker.addEventListener('controllerchange', function() { window.location.reload(); }); ``` **Deep links**: PWAs support URL-based navigation. Use OutSystems' standard screen input parameters in URLs — they work the same in PWA mode as in browser mode. **Splash screen**: Defined by the background_color and 512x512 icon in the manifest. No additional configuration needed — the browser generates it automatically.

1/* Client Action: GoBack — add to all screens in PWA */
2/* Triggered by a back button widget */
3Start
4→ JavaScript Node
5   /* Check if there's history to go back to */
6   var canGoBack = window.history.length > 1;
7   $parameters.HasHistory = canGoBack;
8→ If HasHistory
9   [True]
10   → Run JavaScript: $public.Navigation.navigateBack();
11   [False]
12   → Navigate to Home screen
13→ End
14
15/* Detect PWA install state — add to OnApplicationReady */
16Start
17→ JavaScript Node
18   var isStandalone = window.matchMedia('(display-mode: standalone)').matches
19       || window.navigator.standalone === true;
20   $parameters.IsInstalledPWA = isStandalone;
21→ If IsInstalledPWA
22   [True]  → SetClientVariable IsPWAMode = True
23   [False] → SetClientVariable IsPWAMode = False
24→ End