Progressive Web Apps (PWA) with Oracle APEX
Introduction
Progressive Web Apps bridge the gap between traditional web applications and native mobile apps. Instead of maintaining separate iOS, Android, and desktop codebases, Oracle APEX lets you transform any responsive web application into an installable, fast-loading PWA using declarative settings, native Web APIs, and custom Service Workers.
1. What Makes an Oracle APEX App a PWA?
A Progressive Web App uses modern browser capabilities to deliver an app-like experience from a single codebase:
Installable: Users can add the app directly to their iOS/Android home screen or Windows/macOS desktop without visiting an App Store.
Standalone Experience: Launches in its own dedicated window without browser address bars or navigation chrome.
Fast & Resilient: Uses a Service Worker to cache static assets (
#APP_FILES#, Universal Theme CSS/JS) and provide graceful offline fallback screens.Native Device Integration: Accesses device cameras, geolocation, push notifications, and the OS share sheet directly from browser JavaScript.
2. Core Architectural Components of an APEX PWA
When Progressive Web App (PWA) support is enabled in Oracle APEX, the platform automatically generates and connects three essential client-side artifacts that allow a standard web application to behave like an installable native app. First, manifest.json supplies the device operating system with installation metadata—including the application name, home-screen icons, theme colors, and standalone display mode—so the app launches cleanly without browser chrome. Second, a Service Worker (sw.js) runs as a background proxy inside the browser, intercepting outgoing network requests and caching static assets (such as APEX core JavaScript, CSS, and theme files) for instant loading. Finally, an Offline Fallback page provides a lightweight, self-contained HTML screen that renders automatically whenever the user loses network connectivity, ensuring a graceful user experience instead of a generic browser error.
3. Mandatory Prerequisites
Before enabling PWA features in your workspace, verify two strict browser and APEX requirements:
HTTPS Context: Browsers block Service Worker registration over plain HTTP (except
localhostduring local testing). Your ORDS/web server must serve valid TLS/HTTPS certificates.Friendly URLs Enabled: Navigate to Shared Components >
Application Definition >
Properties and ensure Friendly URLs is toggled On.
4. Step 1: Declarative PWA Activation in APEX
Turning a standard APEX application into a PWA takes less than two minutes:
Open your application in App Builder.
Go to Shared Components > User Interface > Progressive Web App.
Toggle Enable Progressive Web App to On.
Toggle Installable to On (this automatically adds an "Install App" navigation bar entry when opened in a supported browser).
5. Step 2: Configuring the Web App Manifest (manifest.json)
Under Progressive Web App > Manifest Configuration, customize how your app appears on the user's home screen and task switcher:
Display Mode: Select Standalone (hides browser UI) or Minimal UI.
Screen Orientation: Choose Any, Portrait, or Landscape depending on your layout.
Theme Color & Background Color: Match your Universal Theme header color (e.g.,
#0572CE) so the mobile status bar blends seamlessly into your app header.Custom App Icons: Upload high-resolution PNG icons (
192x192and512x512maskable icons) under Application Icon so devices display crisp launcher icons instead of generic browser shortcuts.
6. Customizing the Built-in "Install App" Button
APEX automatically injects an install link into the Navigation Bar, but you can also trigger the installation prompt programmatically from any custom hero banner or button using the apex.pwa JavaScript API:
7. Customizing the Offline Fallback Page
When a user opens your installed PWA with zero network connection, APEX serves a branded offline fallback screen. Customize its message without external CSS or image dependencies using Text Messages:
Navigate to Shared Components > Globalization > Text Messages.
Create a message named
APEX.PWA.OFFLINE.BODY.Provide self-contained HTML markup:
8. Extending the Service Worker with Custom Caching Hooks
APEX’s default Service Worker caches static APEX framework files, but you can extend it with custom hooks to cache your own application assets (#APP_FILES#):
Upload a JavaScript file (e.g.,
pwa-hooks.js) to Shared Components > Static Application Files.Reference
#APP_FILES#pwa-hooks.jsin Progressive Web App > Service Worker Configuration > File URLs.
9. Adding Native App Shortcuts (shortcuts in Manifest)
App Shortcuts allow mobile and desktop users to long-press your PWA icon on their home screen and jump directly to high-frequency APEX pages (such as "New Expense" or "Scan Asset"):
Go to Shared Components > User Interface > Progressive Web App > Shortcuts.
Add shortcut entries pointing to target APEX pages:
Name:
New Field ReportShort Name:
New ReportTarget URL:
f?p=&APP_ID.:15:&SESSION.Icon:
#APP_FILES#icons/shortcut-add.png
10. Integrating Device Geolocation in a PWA
Installed PWAs can request GPS coordinates directly from the device using the standard navigator.geolocation API inside a Dynamic Action:
11. Using the Native OS Share Sheet (Web Share API)
Instead of building custom "Email Link" or "Copy URL" modals, invoke the native Android, iOS, or Windows Share sheet directly from your APEX page:
12. Sending Push Notifications with APEX_PWA
Oracle APEX includes the built-in APEX_PWA PL/SQL package to send native push notifications to subscribed devices—even when the browser tab is closed:
Enable Push Notifications in Shared Components > User Interface > Progressive Web App.
Generate VAPID keys directly inside the APEX builder settings.
Prompt the user to subscribe on the client side:
Send notifications from any PL/SQL process, trigger, or automation using
APEX_PWA.SEND_PUSH_NOTIFICATION:
13. Mobile UX Best Practices for Standalone PWAs
Because a standalone PWA removes the browser's built-in Back and Refresh buttons, you must design navigation intentionally:
Bottom Navigation Bar: In Shared Components > User Interface > User Interface Details, switch the Navigation Menu position from Side to Top or use a Mobile Bottom Tab Bar template for thumb-friendly navigation on phones.
Explicit Back Buttons: Always include a clear breadcrumb or header Back button on modal and detail pages so iOS users aren't trapped without a browser back button.
Touch Targets: Ensure interactive buttons and list rows have at least
44px x 44pxtap targets.
14. Handling PWA Cache Updates & Versioning
Service Workers aggressively cache assets, which can cause users to run stale JavaScript after a new release. Manage updates cleanly:
Bump Cache Keys: Increment version strings (e.g.,
apex-pwa-assets-v3) in your custom Service Worker whenever deploying static file changes.Listen for Update Events: Notify users when a new version of the PWA is downloaded in the background so they can reload to activate it immediately:
15. Auditing and Verifying Your PWA with Lighthouse
Before rolling out your PWA to production users, run an audit in Chrome or Edge DevTools:
Open your APEX application in an Incognito window.
Open DevTools (F12) > Application tab:
Check Manifest to verify icons,
start_url, anddisplay: standaloneload with zero warnings.Check Service Workers to confirm status is Activated and is running.
Open DevTools > Lighthouse tab and run an audit to validate installability, HTTPS configuration, viewport responsiveness, and offline readiness.
With declarative manifest configuration, custom Service Worker hooks, and the APEX_PWA PL/SQL API, Oracle APEX turns existing enterprise web apps into fast, installable cross-platform applications with minimal overhead.















Hello Harsha, Many thanks for your blog and providing the valuable information in regards the PWA and mobile developement. This is really useful. Do you have any sample app on this? I'm planning to volunterily develop simple Member's management mobile app for one of the charitable organisation. This would give more understanding of how mobile app is rendering. Your help and support would be appreciated.
ReplyDelete