PWA like installation

[PeterMarkuson]

Hi guys,

I have been working on PWA support for NiceGUI and found #246 which is already closed. So, let me share my achievements in addition to that old thread also here.

Disclaimer: I am not a professional programmer and have only minor knowledge in JavaScript. If anybody has come up with a better solution or can improve my approach, I would be happy to see that :)

You can achieve the "pwa" look with that neat install button by providing a manifest file and a service_worker.js. If a user visits your page, he will see a notification to install the app. And of cause you can use the APIs from the browser (like notifications) to make your app look even more native.

However, this will not lead to a pure offline experience, because the backend needs to be there. But, it leads to a nice setup for new users and a better experience with a startup logo and full-screen instead of browser tab.

You need these four ingredients:

1. A manifest.json file
2. A service_worker.js file
3. One static binding for each of these files in your application
4. Add them to your page in the head-html section

This is manifest.json. Please replace the values in capital to your liking

{
    "name": "APP_NAME",
    "short_name": "APP_NAME",
    "theme_color": "#2196f3",
    "background_color": "#2196f3",
    "display": "standalone",
    "orientation": "portrait",
    "scope": "/",
    "start_url": "/home",
    "id": "YOUR_UNIQUE_APP_ID",
    "display_override": [],
    "icons": [
        {
            "src": "icon-192.png",
            "sizes": "192x192",
            "type": "image/png"
        },
        {
            "src": "icon-512.png",
            "sizes": "512x512",
            "type": "image/png"
        }
    ]
}

This is an optimized service-worker who caches static files (e.g. media), but does nothing on web-socket-connections:

const CACHE_NAME = 'APP_NAME-vYOUR_VERSION_NUMER';
const CACHE_URLS = [
    '/media/'
];

// WebSocket connections to be excluded from the fetch handler
const WEBSOCKET_URLS = [
    'wss://',
    'ws://'
];

self.addEventListener('install', (event) => {
    event.waitUntil(
        caches.open(CACHE_NAME).then((cache) => {

            return Promise.all(
                CACHE_URLS.map(url => {
                    return cache.add(url).catch(error => {
                        console.error('Failed to cache:', url, error);
                    });
                })
            );
        })
    );
});

self.addEventListener('fetch', (event) => {
    // Check if the request is for a WebSocket
    if (WEBSOCKET_URLS.some(wsUrl => event.request.url.startsWith(wsUrl))) {
        // Don't interfere with WebSocket connections
        return;
    }

    event.respondWith(
        caches.match(event.request).then((response) => {
            return response || fetch(event.request);
        })
    );
});

self.addEventListener('activate', (event) => {
    const cacheWhitelist = [CACHE_NAME];
    event.waitUntil(
        caches.keys().then((cacheNames) => {
            return Promise.all(
                cacheNames.map((cacheName) => {
                    if (cacheWhitelist.indexOf(cacheName) === -1) {
                        return caches.delete(cacheName);
                    }
                })
            );
        })
    );
});

// Handle WebSocket keep-alive
self.addEventListener('message', (event) => {
    if (event.data === 'keepalive') {
        // Respond to keep-alive messages
        event.ports[0].postMessage('alive');
    }
});

You need to bind these to files with the app.add_static_file command and then the following in your page where it should appear:

ui.add_head_html('<link rel="manifest" href="/manifest.json">')
ui.add_head_html('<script>if("serviceWorker" in navigator) { navigator.serviceWorker.register("/service_worker.js"); };</script>')

BR/Peter

[daya0576]

@PeterMarkuson Thanks for sharing! with the server worker to cache all static files, will your web app reload after opening from iPhone Home Screen

[daya0576]

Tested locally, it works like a charm:

• Page will not reload after reopening from home screen
• The whole experience is more native, for example, the browser bar disappears when jumping to another page with the same endpoint.

[PeterMarkuson]

Thank you for sharing your results. I don't have a chance to test on iPhone, so I appreciate any feedback on that.

On Android I don't see a reload if the app is send to background and later coming back to foreground either by restarting it from home screen or from the list of open apps.

However, if the period of time where the app is in background is too long, it starts with "server connection lost". I assume this is because the websocket connection is cut.

[rodja]

if the period of time where the app is in background is too long, it starts with "server connection lost".

Yes, that is known behaviour which we track (and hopefully fix some day) here: #2410