CIRCUIT

Building an Installable AEM PWA with Service Workers

A progressive web app can give an Adobe Experience Manager site the convenience of an installed app while keeping AEM as the source for content and experience. Installation adds a launcher icon, standalone display and, where the browser supports it, a more dependable repeat visit. The important component is the service worker: a JavaScript network proxy that can cache selected assets, answer requests while offline and update cached content in the background.

An AEM implementation becomes risky when “cache everything” replaces a content-by-content strategy. Published campaign pages, component JSON, images, scripts and authenticated account data have different lifetimes and security requirements. The browser cache must also coexist with Dispatcher rules, a CDN and any application cache already used by the team. A useful design states which layer owns each response, avoids duplicate stale copies and defines how a new release replaces the previous one.

Australian users add practical constraints to those decisions. A commuter in Sydney may open a transit or banking app inside a train with intermittent coverage, while a customer in regional Australia may rely on NBN fixed broadband or variable mobile service. Retail, banking and travel brands expect fast mobile journeys, and privacy obligations make cache segregation essential. The aim is a resilient PWA that improves everyday use without serving one person another person’s content.

Architecture That Fits AEM

Map the request path before writing the worker. A request for an AEM page may travel through a CDN and Dispatcher before reaching authoring or publish; the service worker then sits in the browser, outside that server chain. The talks in the CIRCUIT programme from CIRCUIT’s Chicago conferences reflect this kind of systems thinking, pairing Java and front-end concerns with AEM architecture. Record the origin, cacheability and expected freshness of every response type before choosing cache rules.

Keep the AEM infrastructure responsible for server-side caching, origin selection and content delivery. The worker should cache only responses whose URLs and headers are safe for shared storage. Personalised content, account information and responses marked no-store need particular care, as do URLs whose query parameters distinguish an individual offer or delivery location. Shared caches must never become a route around a user’s authentication or consent state.

The installable experience also needs a web app manifest containing a name, icons, a start URL, display mode and theme colours. Chromium browsers generally expect a manifest and a service worker with a fetch handler before offering installation, while Safari uses Add to Home Screen and applies its own criteria. Keep the start URL within the worker’s scope, provide suitable maskable icons and test the standalone display on mobile devices. Avoid redirecting the start URL through a login journey that makes installation appear broken.

Service Worker Patterns for AEM Content

Register the worker from a controlled AEM page after the initial view has loaded. A root-level script provides the broadest scope without requiring special response headers, while navigator.serviceWorker.register('/sw.js', { scope: '/', updateViaCache: 'none' }) prevents an old HTTP-cached script from delaying an update. The AEM Dispatcher must pass the worker script through with the correct JavaScript content type rather than applying an HTML cache rule.

The worker’s lifecycle should have three clear stages. Installation can precache the application shell, icons and an offline page. Activation can remove obsolete caches and, when appropriate, claim open clients. The fetch handler then applies a route-specific policy for navigation requests, AEM component JSON, client libraries, media and third-party calls. Calling skipWaiting() without coordinating asset versions can leave an open page using an old shell with new JavaScript, so activation should be deliberate.

A robust handler also accounts for storage limits, network timeouts, redirects and browser-specific cache behaviour. Opaque cross-origin responses can be stored but cannot be inspected reliably, making them unsuitable for critical application data. Service workers are not permanent archives, so the Cache API can be cleared by the browser under pressure. Community resources such as D'Amore Indy can help teams compare implementation details and current Adobe terminology while making those operational choices.

Cache Policies and Release Controls

Use explicit allowlists rather than a single rule for every request. Separate public, reusable assets from personalised or transactional responses:

  • Hashed JavaScript, CSS and font files should use a cache-first policy with versioned cache names.
  • Public images and media can use stale-while-revalidate, with controls for storage growth.
  • Public HTML and component JSON should prefer the network, with a defined stale fallback only where appropriate.
  • Authentication, checkout, payment and account responses should remain network-only and outside shared storage.

The policy must respect AEM response headers, including Vary, Cache-Control and cookie-based personalisation. A cached campaign landing page can be safe, while the same template displaying a customer balance is not. Review URL parameters and AEM context paths as well as response content, because an apparently minor path difference can change the meaning of a response.

Release discipline is equally important because a service worker sits between the CDN and the browser. Each production release needs a predictable update sequence:

  • Give the worker and its cache a unique release version linked to the asset manifest.
  • Delete obsolete caches during activation without removing data still needed by open clients.
  • Test installation, updates and offline behaviour on representative Android and iOS devices.
  • Provide a rollback path that can unregister the worker or activate a compatible release safely.

Analytics can also be distorted when a cached navigation restores a page and records another page view. Decide which events represent genuine navigation and which merely represent an offline recovery. A small telemetry sample, checked against network logs, will reveal duplicate events more reliably than assuming the browser behaves consistently across every device.

Australian Delivery, Privacy and Access

Australian design starts with geography and daily routines. In Sydney and Melbourne, commuters check banking, transport and retail services on trains and trams, sometimes after a signal drops in a tunnel or station. Customers in Brisbane, Adelaide and Perth may begin the same journey on mobile before moving to fixed broadband. Regional customers can have entirely different network conditions, making low-bandwidth media and an offline fallback as important as an effective install prompt.

The local commercial market rewards reliability across demanding journeys. Australian banks, supermarkets, airlines and travel businesses expect account information, branch locators, flight status and promotions to remain usable on phones bought at different price points and on connections several years old. These services benefit from a small installable shell, accessible controls and selective offline content, rather than a large download that delays the first interaction.

Broader APAC context is available through HCCH Asia Pacific Week, which is useful when comparing connectivity, privacy and commerce assumptions across markets. For Australia, the legal baseline includes the Privacy Act 1988 and the Australian Privacy Principles, alongside state and territory rules for sensitive information. The Australian Consumer Law also affects how prices, guarantees and contract terms are presented, while electronic marketing may engage the Spam Act 2000. These obligations strengthen the case for network-only personal data, deliberate consent handling and accurate offline messages.

The broader APAC context is available through HCCH Asia Pacific Week, which is useful when comparing connectivity, privacy and commerce assumptions across markets. For Australia, the legal baseline includes the Privacy Act 1988 and the Australian Privacy Principles, alongside state and territory rules for sensitive information. The Australian Consumer Law also affects how prices, guarantees and contract terms are presented, while electronic marketing may engage the Spam Act 2000. These obligations strengthen the case for network-only personal data, deliberate consent handling and accurate offline messages.

Launch, Measure and Keep the Site Useful

Begin with a development environment that mirrors production behaviour. CIRCUIT’s guidance on local development with Derby can help teams establish a lightweight local database workflow, but the service worker also needs a local origin capable of serving HTTPS or running on localhost. Keep local content and response headers close to the published environment so cache decisions do not change after deployment.

Test the complete journey rather than checking only registration. Verify that the manifest icon appears on the install prompt, the application launches without browser chrome, updates replace old assets and the offline route provides useful information. Use browser developer tools to inspect cache names and requests, then repeat the process on actual phones and tablets. Australian support teams should also account for Perth’s different working hours and for users travelling across mobile coverage boundaries.

Release to a small audience first, watch installation and update success rates, and monitor cache errors, offline-page usage and support reports. Connect service-worker versions to the AEM release so a problematic worker can be identified and replaced quickly. Choose one high-value AEM journey today, define its cache contract, build the smallest dependable offline fallback and schedule a measured staged release that the whole delivery team can own.