Enabling Progressive Web App Features

Through a simple configuration, a content author can now enable progressive web app (PWA) features for experiences created in AEM Sites.

Introduction

Progressive web apps (PWAs) enable immersive app-like experiences for AEM sites by allowing them to be stored locally on a user’s machine and be accessible offline. A user could browse a site while on-the-go even if losing an internet connection. PWAs allow seamless experiences even if the network is lost or unstable.

Instead of requiring any re-coding of the site, a content author is able to configure PWA properties as an additional tab in the page properties of a site.

• When saved or published, this configuration triggers an event handler that writes out the manifest files and service worker that enable PWA features on the site.
• Sling mappings are also maintained to ensure that service worker is served from the root of the application to enable proxying content allowing offline capabilities within the app.

With PWA, the user has a local copy of the site, giving an app-like experience even without an internet connection.

Prerequisites

To be able to use PWA features for your site, there are two requirements for your project environment:

1. Use Core Components to take advantage of this feature
2. Adjust your dispatcher rules to expose the required files

These are technical steps that the author will need to coordinate with the development team. These steps are only required once per site.

Use Core Components

Core Components release 2.15.0 and later fully support the PWA features of AEM sites. Since AEMaaCS always includes the latest version of the Core Components, you can leverage PWA features out-of-the-box. Your AEMaaCS project automatically fulfills this requirement.

Adjust Your Dispatcher

The PWA feature generates and uses /content/<sitename>/manifest.webmanifest files. By default, the dispatcher doesn’t expose such files. To expose these files, the developer must add the following configuration to your site project.

File location: [project directory]/dispatcher/src/conf.dispatcher.d/filters/filters.any >

# Allow webmanifest files
/0102 { /type "allow" /extension "webmanifest" /path "/content/*/manifest" }

Depending on your project you may want to include different types of extensions to the rewrite rules. The webmanifest extension can be useful to include in the rewrite conditions when you introduced a rule that hides and redirects requests to /content/<projectName>.

RewriteCond %{REQUEST_URI} (.html|.jpe?g|.png|.svg|.webmanifest)$

Enabling PWA for Your Site

With the prerequisites met, it is very easy for a content author to enable PWA features to a site. The following is a basic outline of how to do this. Individual options are detailed in section Detailed Options.

1. Log into AEM.

2. From the main menu, tap or click Navigation -> Sites.

3. Select your sites project and tap or click Properties or use the hotkey p.

4. Select the Progressive Web App tab and configure the applicable properties. At a minimum you will want to:

   1. Select the option Enable PWA.

   2. Define the Startup URL.

      

   3. Upload a 512x512 png icon to the DAM and reference that as the icon for the app.

      

   4. Configure the paths you want the service worker to take offline. Typical paths are:

      • /content/<sitename>
      • /content/experiencefragements/<sitename>
      • /content/dam/<sitename>
      • Any third party font references
      • /etc/clientlibs/<sitename>

      

5. Tap or click Save & Close.

Your site is now configured and you can install it as a local app.

Using Your PWA-Enabled Site

Now that you have configured your site to support PWA, you can experience it for yourself.

1. Access the site in a supported browser.
2. You will see a new icon in the address bar of the browser, indicating that the site can be installed as a local app.
   • Depending on the browser, the icon may vary, and the browser may also display a notification (such as a banner or dialog box) indicating that it’s possible to install as a local app.
3. Install the app.
4. The app will be installed on the home screen of your device.
5. Open the app, browse a bit, and see that pages are available offline.

Detailed Options

The following section provides more detail on the options available when configuring your site for PWA.

Configure Installable Experience

These settings allow your site behave like a native app by making it installable on the visitor’s home screen and available offline.

• Enable PWA - This is the main toggle to enable PWA for the site.
• Startup URL - This is the preferred start URL that the app will open when the user loads the locally-installed app.
  • This can be any path in your content structure.
  • This does not have to be the root and is often a dedicated welcome page for the app.
  • If this URL is relative, the manifest URL is used as the base URL to resolve it.
  • When left empty, the feature uses the address of the web page from which the we app got installed.
  • It is recommended to set a value.
• Display mode - A PWA-enabled app is still an AEM site delivered through a browser. These display options define how the browser should be hidden or otherwise presented to the user on the local device.
  • Standalone - The browser is completely hidden from the user and it appears like a native app. This is the default value.
    • With this option, app navigation must be possible entirely through your content using links and components on the site’s pages without using the browser’s navigation controls.
  • Browser - The browser appears as it normally would when visiting the site.
  • Minimal UI - The browser is mostly hidden, like a native app, but basic navigation controls are exposed.
  • Full Screen - The browser is completely hidden, like a native app, but is rendered in full screen mode.
    • With this option, app navigation must be possible entirely through your content using links and components on the site’s pages without using the browser’s navigation controls.
• Screen orientation - As a local app, the PWA needs to know how to handle device orientations.
  • Any - The app adjusts to the orientation of the user’s device. This is the default value.
  • Portrait - This forces the app to open in portrait layout regardless of the orientation of the user’s device.
  • Landscape - This forces the app to open in landscape layout regardless of the orientation of the user’s device.
• Theme color - This defines the color of the app that affects how the local user’s operating system displays the native UI toolbar and navigation controls. Depending on the browser, it can affect other app presentation elements.
  • Use the color well pop-up to select a color.
  • The color can also be defined by hex or RGB value.
• Background color - This defines the background color of the app, which is shown as the app loads.
  • Use the color well pop-up to select a color.
  • The color can also be defined by hex or RGB value.
  • Certain browsers build a splash screen automatically from the app name, background color, and icon.
• Icon - This defines the icon that represents the app on the user’s device.
  • The icon must be a png file of size 512x512 pixels.
  • The icon must be stored in DAM.

Cache Management (Advanced)

These settings make parts of this site available offline and available locally on your visitor’s device. This allows controlling the cache of the web app to optimize network requests and support offline experiences.

• Caching strategy and frequency of content refresh - This setting defines the caching model for your PWA.
  • Moderately - This setting is the case for most sites and is the default value.
    • With this setting, the content first viewed by the user will be loaded from the cache and while the user is consuming that content, the rest of the content in the cache will be revalidated.
  • Frequently - This is the case for sites that need updates to be very fast such as auction houses.
    • With this setting, the app will look for the most recent content via the network first, and if it is not available will fall back to the local cache.
  • Rarely - This is the case for sites that are nearly static such as reference pages.
    • With this setting, the app will look for the content in the cache first, and if not available will fall back to the network to retrieve it.
• File pre-caching - These files hosted on AEM will be saved to the local browser cache when the service worker is installing and before it is used. This guarantees that the web app is full functional when offline.
• Paths inclusions - Network requests for the defined paths are intercepted and cached content is return in accordance with the configured Caching strategy and frequency of content refresh.
• Cache exclusions - These files will never be cached regardless of the settings under File pre-caching and Path inclusions.

Limitations and Recommendations

Not all PWA features are available for AEM Sites. These are a few notable limitations.

• Pages are not automatically synched or updated if the user is not using the app.

Adobe also makes the following recommendations when you implement PWA.

Minimize the number of resources to pre-cache.

Adobe advises you to limit the number of pages to pre-cache.

• Embed libraries to reduce the number of entries to manage when pre-caching.
• Limit the number of image variations to pre-cache.

Enable PWA after the project scripts and stylesheets are stabilized.

Client libraries are delivered with the addition of a cache selector observing the following pattern lc-<checksumHash>-lc. Every time one of the files (and dependencies) that compose a library change, this selector changes. If you listed a client-library to be pre-cached by the service-worker and you want to refer to a new version, you manually retrieve and update the entry. As a result, we advise you to configure your site to be a PWA after the project scripts and stylesheets are stabilized.

Minimize the number of image variations.

The Image Component of the AEM Core Components determines one the front end the best rendition to fetch. This mechanism also includes a timestamp that corresponds to the last modified time of that resource. This mechanism complicates the configuration of the PWA pre-cache.

When configuring the pre-cache, the user needs to list all the path variations that can be fetched. These variations are composed of parameters like quality and width. It is strongly advised to reduce the number of these variations to a maximum of three - small, medium, large. You can do that via the content-policy dialog of the Image Component.

If not configured carefully, memory and network consumption can severely impact the performance of your PWA. Also if you intend to precache, say, 50 images, and have 3 widths per image, the user maintaining the site will have to maintain a list of up to 150 entries in the PWA pre-cache section of the page properties.

Adobe also advises you to configure your site to be a PWA after the project use of images has stabilized.

Business.Adobe.com resources