Skip to main content

 

Delivering Mobile Apps

 

Applies only to Mobile Apps

 

OutSystems

Early Access - Distribute as a progressive web app (PWA)

  • Edit
  • This document is a work in progress and we invite you to share your feedback in the forum topic dedicated to the PWA feature.

    Progressive web apps (PWA) provide native-like experiences without having to distribute a native app. When you develop PWAs in OutSystems, you get all the benefits of the low-code development, as all you need is to build a Mobile App and enable the PWA feature.

    Prerequisites

    To distribute your app as a PWA, you need to meet the following requirements:

    • Service Studio 11.6 or later
    • Platform Server 11.7 or later
    • LifeTime Oct.2019 CP1 or later
    • Enabled the early access feature in LifeTime

    Create a Progressive Web App

    The Distribute tab is available only after you activate the feature in LifeTime.

    Create a Mobile App and turn on the toggle Distribute as PWA in the app details.

    1. Start creating a new app, and in the New Application window select Phone App or Tablet App app template. Note that the PWA feature works with Mobile Apps only.
    2. Add a Screen and some logic to it.
    3. Publish the app.
    4. In the app details, under the Distribute tab, turn on the toggle Distribute as PWA. To locate the Distribute tab, go back to the home screen of Service Studio and click your application icon.

      The PWA toggle to activate progressive web app distribution

    You don't have to republish your app after changing the value of the Distribute as PWA. This change is applied in real-time.

    When you develop a progressive web app, keep in mind that mobile best practices apply, particularly about designing a lightweight local storage.

    Try out your progressive web app

    Here is how you can run your PWA. Go to app details and click Distribute tab:

    • To open on your mobile device, scan the QR code.
    • To open in a desktop browser, click the link.

    The QR code and links to run progressive web app

    PWA in Android

    Follow these steps to install and run your PWA on an Android device.

    1. Visit the app URL in Chrome.
    2. Tap the banner Add (my app) to Home screen.

      Installing app in Android

    3. After you see a confirmation saying that the app was added to the home screen, open the app like any other app installed from a store. You can also uninstall it like any other app.

      PWA on Android home screen

    PWA in iOS

    Follow these steps to install and run your PWA on an iOS device.

    Due to a bug in iOS, PWAs are not working in the iOS versions 13.0 to 13.2. Use iOS 13.3 or later instead.

    1. Visit the app URL in Safari.
    2. Tap the Share button. The share menu opens.

      Share button in Safari iOS

    3. Tap Add to home screen. The confirmation screen opens.

      Share options on iOS

    4. In the confirmation screen, tap Add.

      Confirm adding to iPhone home screen

    5. Your app should now be on the home screen. You can also uninstall it like any other app.

      Add to home screen share option on iOS

    Customize your app

    You can customize your app by:

    • Editing the details in the app details screen
    • Overriding the settings in by using the PWA manifest in the Extensibility Configuration

    Changing the app properties

    You can edit your app name, description, color, and logo through the UI of Service Studio. Make sure you republish the app.

    The manifest values editable in Service Studio

    The manifest is generated automatically, and you don't have to use it unless you want to override some values. You can edit the following manifest options from the Service Studio UI.

    Service Studio property Manifest key
    Application Name name
    Application Description description
    App Primary Color theme_color
    Application Logo* icons

    (*) Service Studio generates the four required resolutions of the icon.

    Overriding the manifest settings

    We identified an issue that prevents LifeTime to override PWA Extensibility Configurations. We're working on the fix. Note that you can still use Extensibility Configurations in Service Studio.

    Keep in mind that the LifeTime PWA manifest overrides the manifest in Service Studio.

    Using the manifest overrides the values you set in Service Studio. You have to use the manifest in the PWAManifest section of the JSON of the Extensibility Configurations field. You can edit the manifest in two places:

    • In Service Studio, where the manifest overrides all UI settings in all environments. Edit the JSON manifest in the Extensibility Configurations field of the module properties.
    • In LifeTime, where the manifest overrides all UI settings in the current environment only. Find the Extensibility Configurations field in Applications > (app name) > Settings > Advanced > Extensibility Configurations

    Manifest resources and sample JSON

    You can use Web App Manifest Generator to generate the manifest, or experiment with the sample we provide here.

    { 
       "PWAManifest":{ 
          "name":"Name overridden",
          "short_name":"ShortName overridden",
          "description":"Description overridden",
          "theme_color":"#EDEDED",
          "background_color":"black",
          "dir":"ltr",
          "orientation": "portrait",
          "serviceworker":{ 
             "src":"/PWAServiceWorker/scripts/PWAServiceWorker.ServiceWorker.js"
          }
       }
    }
    

    You should be able to use the JSON for both PWA and plugins.

    Plugins in PWA

    During the early access, you can try out the following officially supported plugins in your PWAs:

    There are more plugins coming soon, and you can contribute with your own on the Forge.

    Debugging

    The Debugger is currently not available for PWAs. We advise you to use the debugging capabilities of your browser to troubleshoot any runtime issues with your PWA.

    Troubleshooting

    Here are some notes that can help you in troubleshooting the PWA feature.

    The toggle button has no effect

    Note that you need to republish your apps after the Platform Server upgrade for the new features to work correctly, as instructed in the Platform Server upgrade list. If you haven't done it already, republish the apps in the factory and then turn on the toggle Distribute as PWA.

    There is a potential workaround for the PWA toggle button to work without the republishing step, which is to republish the current module once and then try turning on the toggle Distribute as PWA. However, keep in mind that republishing the apps after the upgrade is a mandatory step, and skipping it can cause unintended effects.

    There are runtime errors

    Try deleting the local data of the app. Locate the settings in the browser, and clear the data for the domain from which the app was installed. In Chrome go to Settings > Site Settings > Cookies and site data > See all cookies and site data, search for the domain and clear the data.

    Extensibility Configurations override is not working when applied in LifeTime

    There's an issue with applying Extensibility Configurations from LifeTime to override the manifest. The team is working on the fix. Note that you can still use Extensibility Configurations in Service Studio.

    PWA doesn't install in iOS

    If you're using Platform Server 11.7 or earlier and iOS 13 and later, you should either:

    • Upgrade to Platform Server 11.8 or later
    • Disable Web SQL. Go to Settings > Safari > Advanced > Experimental Features > and make sure Disable Web SQL is off.

      WebSQL Settings in Safari iOS

    PWA doesn't work in iOS

    One of the reasons why your PWA is not working in iOS might be because of an iOS bug that prevents PWAs from running correctly in the iOS versions 13.0 to 13.2.

    To fix this issue, use iOS 13.3 or later instead.

    PWA is slow and queries take too long to execute

    If your PWA performs poorly and queries take too long to execute, your local storage model might be too complex or the amount of data that the app needs to handle is too high. See Design a lightweight local storage for recommendations.

    • Was this article helpful?