Spaces:
Running
Running
BattleWords PWA Installation Guide
BattleWords can now be installed as a Progressive Web App (PWA) on your mobile device or desktop, giving you a native app experience directly from your browser!
What is a PWA?
A Progressive Web App allows you to:
- ✅ Install BattleWords on your home screen (Android/iOS)
- ✅ Run in full-screen mode without browser UI
- ✅ Access the app quickly from your app drawer
- ✅ Get automatic updates (always the latest version)
- ✅ Basic offline functionality (cached assets)
Installation Instructions
Android (Chrome, Edge, Samsung Internet)
- Visit the app: Open https://surn-battlewords.hf.space in Chrome
- Look for the install prompt: A banner will appear at the bottom saying "Add BattleWords to Home screen"
- Tap "Add" or "Install"
- Alternative method (if no prompt):
- Tap the three-dot menu (⋮) in the top-right
- Select "Install app" or "Add to Home screen"
- Tap "Install"
- Launch: Find the BattleWords icon on your home screen and tap to open!
Result: The app opens full-screen without the browser address bar, just like a native app.
iOS (Safari)
Note: iOS requires using Safari browser (Chrome/Firefox won't work for PWA installation)
- Visit the app: Open https://surn-battlewords.hf.space in Safari
- Tap the Share button: The square with an arrow pointing up (at the bottom of the screen)
- Scroll down and tap "Add to Home Screen"
- Edit the name (optional): You can rename it from "BattleWords" if desired
- Tap "Add" in the top-right corner
- Launch: Find the BattleWords icon on your home screen and tap to open!
Result: The app opens in standalone mode, similar to a native iOS app.
Desktop (Chrome, Edge, Brave)
- Visit the app: Open https://surn-battlewords.hf.space
- Look for the install icon:
- Chrome/Edge: Click the install icon (⊕) in the address bar
- Or click the three-dot menu → "Install BattleWords"
- Click "Install" in the confirmation dialog
- Launch:
- Windows: Find BattleWords in Start Menu or Desktop
- Mac: Find BattleWords in Applications folder
- Linux: Find in application launcher
Result: BattleWords opens in its own window, separate from your browser.
Features of the PWA
Works Immediately ✅
- Full game functionality (reveal cells, guess words, scoring)
- Challenge Mode (create and play shared challenges)
- Sound effects and background music
- Ocean-themed animated background
- All current features preserved
Offline Support 🌐
- App shell cached for faster loading
- Icons and static assets available offline
- Note: Challenge Mode requires internet connection (needs to fetch/save from HuggingFace)
Updates 🔄
- Automatic updates when you open the app
- Always get the latest features and bug fixes
- No manual update process needed
Privacy & Security 🔒
- No new data collection (same as web version)
- Environment variables stay on server (never exposed to PWA)
- Service worker only caches public assets
- All game data in Challenge Mode handled server-side
Uninstalling the PWA
Android
- Long-press the BattleWords icon
- Tap "Uninstall" or drag to "Remove"
iOS
- Long-press the BattleWords icon
- Tap "Remove App"
- Confirm "Delete App"
Desktop
- Chrome/Edge: Go to
chrome://appsoredge://apps, right-click BattleWords, select "Uninstall" - Windows: Settings → Apps → BattleWords → Uninstall
- Mac: Delete from Applications folder
Troubleshooting
"Install" option doesn't appear
- Android: Make sure you're using Chrome, Edge, or Samsung Internet (not Firefox)
- iOS: Must use Safari browser
- Desktop: Check if you're using a supported browser (Chrome, Edge, Brave)
- Try refreshing the page (the install prompt may take a moment to appear)
App won't open after installation
- Try uninstalling and reinstalling
- Clear browser cache and try again
- Make sure you have internet connection for first launch
Service worker errors in console
- This is normal during development
- The app will still function without the service worker
- Full offline support requires the service worker to register successfully
Icons don't show up correctly
- Wait a moment after installation (icons may take time to download)
- Try force-refreshing the PWA (close and reopen)
Technical Details
Files Added for PWA Support
battlewords/
├── static/
│ ├── manifest.json # PWA configuration
│ ├── service-worker.js # Offline caching logic
│ ├── icon-192.png # App icon (small)
│ └── icon-512.png # App icon (large)
└── ui.py # Added PWA meta tags
What's Cached Offline
- App shell (HTML structure)
- Icons (192x192, 512x512)
- Manifest file
- Previous game states (if you were playing before going offline)
What Requires Internet
- Creating new challenges
- Submitting results to leaderboards
- Loading shared challenges
- Downloading word lists (first time)
- Fetching game updates
Comparison: PWA vs Native App
| Feature | PWA | Native App |
|---|---|---|
| Installation | Quick (1 tap) | Slow (app store) |
| Size | ~5-10 MB | ~15-30 MB |
| Updates | Automatic | Manual |
| Platform support | Android, iOS, Desktop | Separate builds |
| Offline mode | Partial | Full |
| Performance | 90% of native | 100% |
| App store presence | No | Yes |
| Development time | 2-4 hours ✅ | 40-60 hours per platform |
Feedback
If you encounter issues installing or using the PWA, please:
- Check the browser console for errors (F12 → Console tab)
- Report issues at: https://github.com/Oncorporation/BattleWords/issues
- Include: Device type, OS version, browser version, and error messages
For Developers
To regenerate the PWA icons:
python3 generate_pwa_icons.py
To modify PWA behavior:
- Edit
battlewords/static/manifest.json(app metadata) - Edit
battlewords/static/service-worker.js(caching logic) - Edit
battlewords/ui.py(PWA meta tags, lines 34-86)
To test PWA locally:
streamlit run app.py
# Open http://localhost:8501 in Chrome
# Chrome DevTools → Application → Manifest (verify manifest.json loads)
# Chrome DevTools → Application → Service Workers (verify registration)
Enjoy BattleWords as a native-like app experience! 🎮🌊