From 3118ed60128f8661c15c6cd083299955afa75d36 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Joaqu=C3=ADn=20S=C3=A1nchez?= Date: Wed, 15 Feb 2023 13:07:30 +0100 Subject: [PATCH] docs: add PWA cookbook (#1747) Co-authored-by: Michel EDIGHOFFER --- README.md | 6 +- docs/content/1.guide/3.contributing.md | 2 +- docs/content/80.pwa.md | 131 +++++++++++++++++++++ docs/content/{privacy.md => 99.privacy.md} | 0 4 files changed, 137 insertions(+), 2 deletions(-) create mode 100644 docs/content/80.pwa.md rename docs/content/{privacy.md => 99.privacy.md} (100%) diff --git a/README.md b/README.md index 82bbf1e7..05cfa79f 100644 --- a/README.md +++ b/README.md @@ -117,6 +117,10 @@ Elk uses [Vitest](https://vitest.dev). You can run the test suite with: nr test ``` +## 📲 PWA + +You can consult the [PWA documentation](https://docs.elk.zone/docs/pwa) to learn more about the PWA capabilities on Elk, how to install Elk PWA in your desktop or mobile device and some hints about PWA stuff on Elk. + ## 🦄 Stack - [Vite](https://vitejs.dev/) - Next Generation Frontend Tooling @@ -129,7 +133,7 @@ nr test - [Iconify](https://github.com/iconify/icon-sets#iconify-icon-sets-in-json-format) - Iconify icon sets in JSON format - [Masto.js](https://neet.github.io/masto.js) - Mastodon API client in TypeScript - [shiki](https://shiki.matsu.io/) - A beautiful Syntax Highlighter -- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update and push notifications +- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update, Web Push Notifications and Web Share Target API ## 👨‍💻 Contributors diff --git a/docs/content/1.guide/3.contributing.md b/docs/content/1.guide/3.contributing.md index 1fa87808..0f6f11d3 100644 --- a/docs/content/1.guide/3.contributing.md +++ b/docs/content/1.guide/3.contributing.md @@ -50,4 +50,4 @@ nr test - [Iconify](https://github.com/iconify/icon-sets#iconify-icon-sets-in-json-format) - Iconify icon sets in JSON format - [Masto.js](https://neet.github.io/masto.js) - Mastodon API client in TypeScript - [shiki](https://shiki.matsu.io/) - A beautiful Syntax Highlighter -- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update and push notifications +- [vite-plugin-pwa](https://github.com/vite-pwa/vite-plugin-pwa) - Prompt for update, Web Push Notifications and Web Share Target API diff --git a/docs/content/80.pwa.md b/docs/content/80.pwa.md new file mode 100644 index 00000000..7fcd9e76 --- /dev/null +++ b/docs/content/80.pwa.md @@ -0,0 +1,131 @@ +# PWA + +Elk provides a PWA (Progressive Web App) that can be installed on your desktop/device. This allows you to use Elk as a native app on your device, and it will work offline. + +The main goal of the PWA is to provide a native app experience on mobile devices with Web Push Notifications and Web Share Target API capabilities. + +Web Share Target will allow you to share content from other apps to Elk in mobile browsers. + +## Mobile Support + +Some mobile browsers will allow you to install the PWA as a native app, and some others will only allow you to add the PWA to your home screen. + +If you're using a mobile browser that supports the PWA installation, you will see a banner at the bottom of the screen with the option to install the PWA. + +If the browser also supports [beforeinstallprompt](https://web.dev/customize-install/) event, ElK will show a prompt (on the right aside on wide screens, or at top on small screens) to allow you to install the PWA directly. + +If the browser doesn't support the PWA installation, check following entries: + +### Safari iOS + +Right now, you cannot use Web Push Notifications on Safari mobile browsers, since it doesn't support the Web Push API yet at operating system level. + +You can check the status of the Push API on Safari mobile browsers on [this page](https://caniuse.com/notifications). + +Visit also [this site](https://firt.dev/notes/pwa-ios/) to check the status of PWA Capabilities on Safari mobile browsers. + +To install a Progressive Web App (PWA) on Safari, follow these steps: +- Tap the "Share" icon at the bottom of the screen. +- Scroll down and tap "Add to Home Screen". +- Customize the name of the app (if desired) and tap "Add". +- The PWA should now appear on your home screen. + +### Firefox + +To install a Progressive Web App (PWA) on Firefox, follow these steps: +- Look for the install button or icon, usually located in the address bar or in a prompt that appears on the screen. +- Click on the install button or icon and follow the prompts to complete the installation. +- If you don't see an install button or icon, you can look for the PWA in the Firefox menu. Click on the three horizontal lines in the top/bottom right corner of the browser window to open the menu, then click on "Install" option. + +### Chromium based browsers + +To install a Progressive Web App (PWA) on Chromium based browsers, such as Google Chrome, Microsoft Edge, or Brave, follow these steps: +- Click on the menu button (three vertical dots) at the top right corner of the screen. +- Select "Install Elk as app" or "Install Elk to Home screen". +- Customize the name of the app (if desired) and click "Install" or "Add". +- The PWA should now appear on your device's home screen or in your app drawer. + +## PWA Configuration in Elk project + +By default, Elk will enable the PWA integration, but can be disabled by setting `VITE_DEV_PWA` to `false` in your `.env` file. + +You can find the configuration options for the PWA in the [config/pwa.ts](https://github.com/elk-zone/elk/blob/main/config/pwa.ts) module. + +### PWA Web Manifest + +Right now, there is no support for web manifest internationalization and theme color in any browser, we're using a custom module to generate web manifests for theme color and language variants. + +Elk will generate 2 web manifests per locale, one for light theme and one for dark theme. + +You can check web manifest generation on [modules/pwa/i18n.ts](https://github.com/elk-zone/elk/blob/main/modules/pwa/i18n.ts) module. + +### PWA UI Components + +Elk will provide a set of UI components to allow you to customize the PWA installation prompt on browsers with [beforeinstallprompt](https://web.dev/customize-install/) support. + +You can find the PWA installation prompt in the [PwaInstallPrompt](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaInstallPrompt.client.vue) component: will be shown on the right aside on wide screens, or at top on small screens. + +Elk is using prompt for update strategy, so the PWA prompt for update will be shown only if there is a new version of Elk available. + +On small screens, the PWA prompt for update will be shown as a button on the head, you can find it in [PwaBadge](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaBadge.client.vue) component. + +On wide screens, the PWA prompt for update will be shown as a prompt on the right aside, you can find it in [PwaPrompt](https://github.com/elk-zone/elk/blob/main/components/pwa/PwaPrompt.client.vue) component. + +PWA prompt for update will take preference over PWA installation prompt, so if there is a new version of Elk available, the PWA prompt for update will be shown instead of the PWA installation prompt. + +All previous UI components don't have any logic, all them will use the logic provided by the [PWA plugin](https://github.com/elk-zone/elk/blob/main/plugins/pwa.client.ts). + +### Service Worker + +You can find Elk custom service worker in [service-worker folder](https://github.com/elk-zone/elk/blob/main/service-worker), it provides: +- [Prompt for update strategy](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L14). +- [Web Push Notifications](https://github.com/elk-zone/elk/blob/main/service-worker/web-push-notifications.ts): [push notifications](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L105) and [push notification click](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L106). +- [Web Share Target API](https://github.com/elk-zone/elk/blob/main/service-worker/share-target.ts): [share target registration](https://github.com/elk-zone/elk/blob/main/service-worker/sw.ts#L107). + +### Push Notifications Subscription Logic + +Elk will allow you to send push notifications to your users, you can find the logic for Web Push Notifications subscription [composables/push-notifications folder](https://github.com/elk-zone/elk/blob/main/composables/push-notifications). + +There is a limitation on browsers about registering multiple Web Push Notifications: you can only subscribe to one push service per browser per application: trying to register multiple push subscriptions will be treated as spam by the browser. + +If you try to register multiple push subscriptions, the browser will throw an error, and you will need to unregister the previous push subscription before registering a new one. + +### Debugging PWA in development + +To debug the PWA in development, you will need to run `dev:pwa` or `dev:mocked:pwa` script. + +Running one of previous scripts will start a development server with the PWA enabled: you can review the web manifests and debug the service worker in your browser, use any Chromium based browser, since we're registering the service worker using `type: 'module'`. + +You can debug Web Push Notifications in desktop and mobile browser and Web Share Target in your mobile device, using the same URL as the development server. + +Right now, we can only debug on Android Chrome mobile browsers: +- Web Push Notifications: you don't need to install de PWA, just enable the notifications in the browser on notifications page or web push notifications settings page. +- Web Share Target: you need to install the PWA, and then you can share content from other apps to Elk. + +### Debugging PWA in mobile browsers + +To debug the PWA service worker in your mobile browser, you will need to: +1) Enable development options in your Android device: + - Go to "Settings" on your device. + - Scroll down to "About phone" and tap it. + - Locate the "Build number" and tap it repeatedly (usually 7 times) until you see a message saying that you have enabled developer options. + - Go back to "Settings" and you should now see "Developer options" listed. + - Tap on "Developer options" and you can enable various settings such as USB debugging, mock locations, and more. +2) Connect your Android device to your computer using a USB cable. +3) Enable USB debugging in your Android device: + - Go to "Settings" on your device. + - Scroll down to "Developer options" and tap it. + - Enable "USB debugging". + - Confirm the prompt on your device to allow USB debugging. + - Open Chrome/Edge browser in your device. +4) Open Chrome on your computer and go to `chrome://inspect/#devices`. + - Elk application should be listed in the "Remote Target" section after a few seconds (navigate to any page). + - Enter `http://localhost:5314` in the open in a new tab input and click Open button. + - Click on the "Inspect" button to open the DevTools. +5) Remember to remove the service worker from your device browser using dev tools once you finish testing the service worker: + - Go to `Application > Storage`, you should check following checkboxes: + - Application: `[x]` Unregister service worker + - Storage: `[x]` Local and session storage `[x]` IndexedDB + - Cache: `[x]` Cache storage and `[x]` Application cache + - Click on Clear site data button + - Go to `Application > Service Workers` and check the current service worker is missing or has the status deleted or reduntant. diff --git a/docs/content/privacy.md b/docs/content/99.privacy.md similarity index 100% rename from docs/content/privacy.md rename to docs/content/99.privacy.md