Menu
Menu Sheet Overlay
Search
Search Sheet

Add to Home Screen

    Feature Overview #

    Add to Homescreen is a feature of Progressive Web Apps and is part of Google’s requirements for a PWA to be considered compliant.

    Prerequisites #

    See the full list of prerequisites.

    Configuration #

    Add to Homescreen is enabled out of the box for all projects. By default, it will use the icon and theme color from Merlin’s Potions, our demo site.

    To update the theme color, find the theme_color property in web/app/static/manifest.json and update it to match the color of your brand.

    This setting only affects the PWA when launched from the home screen. To update the theme color shown when the app is used in browser, open web/app/loader.js and find this function call:

    loadAsset('meta', {
        name: 'theme-color',
        content: '#4e439b'
    })
    

    Update content to match your brand’s theme color.

    To update the icon, you can either update the icon file at web/app/img/global/app-icon.png, or you can change the src for the icon inside web/app/static/manifest.json to point to a different file.

    Note: At this time, if you update the icon file, you will only see this icon once the project has been published.

    Testing #

    On an Android device #

    Custom prompt or mini-infobar

    1. Ensure that all prerequisites for Add to Home Screen have been met.

    2. Tap the Add to Home Screen prompt. In this example, it is implemented as a button in the main nav. The mini-infobar is also present.

      Screenshot of Install App button on Merlin's Potions

    3. In the official confirmation modal, choose Cancel. Verify that the confirmation modal is dismissed.

      Screenshot of Add to Home Screen confirmation modal with Cancel and Add options

    4. On the custom prompt, verify that it shows a message informing the user to refresh the page and try again.

      Screenshot of Merlin's Potions main navigation. The Install App button now tells the user to refresh the page to retry.

    5. Refresh the page

    6. Tap the Add to Home Screen prompt again

    7. In the official confirmation modal, choose Add

    8. Minimize Chrome and verify that the app has been installed to the home screen. Launch the app from the home screen.

    9. Open Chrome again and refresh the page. Verify that the Add to Home Screen prompt is no longer present.

    Chrome menu option

    When testing, you may not meet all the criteria for the prompt. The following instructions explain how to force the prompt to appear.

    1. Preview to the site you are testing in regular browsing mode (incognito will not work)

    2. Tap the … menu button in Chrome

    3. Tap Add to Home screen

    4. Confirm the icon and default name and tap Add

      Screenshot of a Chrome dialog to confirm the icon and default name for the app

    5. Verify icon is on the home screen

      Screenshot of home screen with Merlin's Potions app icon

    6. Tap on the app and verify the PWA opens in standalone mode. The browser URL bar and other web-like chrome should be removed from the UI.

      Screenshot of Merlin's Potions home page when launched from the home screen. There is no URL bar.

    In Chrome Dev Tools #

    1. Preview to the site you are testing in regular browsing mode (incognito will not work)
    2. In the Applications tab, click on Manifest
    3. Tap Add to Homescreen
    4. There will be a browser permission prompt to add to applications launcher. Choose yes.
    5. Open a new tab and browse to chrome://apps/. Verify that the app is listed.

    Debugging #

    The best way to debug issues with Add to Home Screen is to use Chrome Dev Tools and follow the testing instructions. If the prompt doesn’t appear after you tap Add to Homescreen, look in your console. On current versions of Android, an error will be logged explaining why the prompt didn’t appear. On older versions like Android 5, the console will not include any error messages.

    Common issues include:

    Insecure resources #

    If any resources on the page are loaded over HTTP instead of HTTPS, the browser will not show the Add to Home Screen prompt. This is often caused by images on the page.

    Delayed loading of manifest.json #

    If manifest.json is loaded too late, the browser may ignore it entirely. If this happens, try adding manifest.json to the beginning of the PWA initialization process. In most PWA projects, the following code loads manifest.json:

    // in loader.js
    
    loadAsset('link', {
        href: getAssetUrl('static/manifest.json'),
        rel: 'manifest'
    })
    

    Try moving this code earlier in the loadPWA or equivalent function.

    Missing manifest.json error #

    When you click on Manifest, you may see an error stating “No manifest detected”. If you see this error, close and reopen Chrome Dev Tools.

    Screenshot of an error message stating that no Manifest was detected

    Standalone mode showing desktop #

    This can occur when you are using Mobify Preview. Mobify Preview sets certain cookies that cause the Mobify Tag to load a specific bundle. Preview uses these cookies to create a Preview session. The Preview session also takes into account information about your browser like the user agent. While in a Preview session, you will see the PWA loaded from your bundle.

    If you then open the standalone version of the app, you will have the Preview cookies but other properties about your browser have changed. This invalidates the Preview session. When the Preview session is invalidated, the desktop site will load instead of the PWA.

    This is specific to Mobify Preview and will not occur on the production version of the site.

    FAQ #

    Q: Does this work on iOS? #

    A: No, this is an Android-only feature

    Q: What if the service worker loader is not yet installed? #

    A: Follow the steps for Developing without the Mobify Requirements