Skip to content

Conversation

@Bharatt16
Copy link

This PR adds missing documentation explaining how to install/add-to-home-screen the Kiwix JS PWA in browsers that do not support the beforeinstallprompt install event, or where the install prompt is intentionally suppressed (e.g., Safari on iOS, Firefox for Android, Vivaldi).
This documentation was requested as the outcome of issue #626.

🔍 Before (Problem / Missing Content)

Previously, the README only explained how to install the PWA when the install event is supported (mainly Chromium browsers).
However:

-> Safari on iOS never fires the install event

-> Firefox for Android does not trigger the event

-> Vivaldi (Chromium-based) suppresses the event for security reasons

-> Some browsers partially support PWA install UI but not the event

-> Users in these browsers did not receive clear guidance on how to install the PWA manually

As a result, users could still install the PWA, but no documentation explained how to do it when the install prompt does not appear.

🛠️ What This PR Adds (Solution)

✔ A new file:
readme/PWA_FALLBACK_INSTALL.md

This file provides:

-> A clear explanation of why the install event may not fire

-> Platform-specific installation instructions for:

    -> Android (Chrome/Edge/Brave/Samsung Internet/Firefox/Vivaldi)

    -> iOS/iPadOS (Safari)

    -> Desktop (Windows/macOS/Linux in Chrome/Edge/Brave)

    -> Firefox (where PWA install support varies)

-> Steps for manually adding the PWA to Home Screen or installing via browser UI

-> Ensures users know how to install the PWA even without automatic prompts

✔ A link in README.md under the PWA section, pointing to this new documentation so users can easily find it.

📈 After (What It Is Now / Impact)

-> The PWA documentation is now complete and covers the full range of browsers.

-> Users who do not see an install prompt now have a clear, official guide.

-> Browsers that suppress or lack PWA install events are now properly documented.

-> Prevents confusion for new users and improves accessibility across all platforms.

Resolves the request in Issue #626.

🔗 Related Issue

This PR fixes: #626

@Jaifroid
Copy link
Member

Great, thanks, I'll take a look!

@Bharatt16
Copy link
Author

@Jaifroid do tell me if any changes is needed.

Copy link
Member

@Jaifroid Jaifroid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is very useful information! However, the formatting could be better. Please use some markdown like adding # before the title in line 1, and ## before subtitiles lower down. It would make it much more readable.

Additionally, I don't think this is the best place (AppPackages) to add the installation guide. It would probably be better just placed in root of repository, not inside any folder. It would make it much more visible.

Finally, it should be linked from README.md. Find an appropriate spot. Check the syntax on GitHub for linking to other markdown documents.

@Jaifroid Jaifroid added the info label Nov 19, 2025
@Jaifroid Jaifroid added this to the Release 3.8.0 milestone Nov 19, 2025
@Bharatt16
Copy link
Author

@Jaifroid
Thanks for the feedback!
I've updated the PR with the requested changes:

  • Moved the fallback installation guide to the root directory
  • Fixed the relative link in README.md
  • Improved the markdown formatting as suggested

Please let me know if you'd like any more adjustments.

Copy link
Member

@Jaifroid Jaifroid left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, that's much better. Could you also link to this guide from screenshots/Install-PWA.md? That's what's linked from the main README.md (in root directory), so it would be good to have the alternative installation method linked from the paragraph about how to install underneath the video.

@Bharatt16
Copy link
Author

Done! I’ve linked the fallback installation guide in screenshots/Install-PWA.md as requested. Let me know if you'd like any adjustments.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add documentation explaining how to install the PWA if onBeforeInstall() event is not supported by the browser

2 participants