| # Wrdler PWA Installation Guide |
|
|
| Version 0.3.5 |
|
|
| **Last Updated:** 2026-08-21 |
|
|
| Wrdler 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 Wrdler 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) |
|
|
| 1. **Visit the app**: Open https://[YourUsername]-wrdler.hf.space in Chrome |
| 2. **Look for the install prompt**: A banner will appear at the bottom saying "Add Wrdler to Home screen" |
| 3. **Tap "Add"** or **"Install"** |
| 4. **Alternative method** (if no prompt): |
| - Tap the **three-dot menu** (⋮) in the top-right |
| - Select **"Install app"** or **"Add to Home screen"** |
| - Tap **"Install"** |
| 5. **Launch**: Find the Wrdler 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) |
|
|
| 1. **Visit the app**: Open https://[YourUsername]-wrdler.hf.space in Safari |
| 2. **Tap the Share button**: The square with an arrow pointing up (at the bottom of the screen) |
| 3. **Scroll down** and tap **"Add to Home Screen"** |
| 4. **Edit the name** (optional): You can rename it from "Wrdler" if desired |
| 5. **Tap "Add"** in the top-right corner |
| 6. **Launch**: Find the Wrdler 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) |
|
|
| 1. **Visit the app**: Open https://[YourUsername]-wrdler.hf.space |
| 2. **Look for the install icon**: |
| - Chrome/Edge: Click the **install icon** (⊕) in the address bar |
| - Or click the **three-dot menu** → **"Install Wrdler"** |
| 3. **Click "Install"** in the confirmation dialog |
| 4. **Launch**: |
| - Windows: Find Wrdler in Start Menu or Desktop |
| - Mac: Find Wrdler in Applications folder |
| - Linux: Find in application launcher |
|
|
| **Result**: Wrdler 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 |
| 1. Long-press the Wrdler icon |
| 2. Tap "Uninstall" or drag to "Remove" |
|
|
| ### iOS |
| 1. Long-press the Wrdler icon |
| 2. Tap "Remove App" |
| 3. Confirm "Delete App" |
|
|
| ### Desktop |
| - **Chrome/Edge**: Go to `chrome://apps` or `edge://apps`, right-click Wrdler, select "Uninstall" |
| - **Windows**: Settings → Apps → Wrdler → 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 |
|
|
| ``` |
| wrdler/ |
| ├── 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: |
| 1. Check the browser console for errors (F12 → Console tab) |
| 2. Report issues at: https://github.com/Oncorporation/Wrdler/issues |
| 3. Include: Device type, OS version, browser version, and error messages |
|
|
| --- |
| |
| ## For Developers |
|
|
| To regenerate the PWA icons: |
| ```bash |
| python3 generate_pwa_icons.py |
| ``` |
|
|
| To modify PWA behavior: |
| - Edit `wrdler/static/manifest.json` (app metadata) |
| - Edit `wrdler/static/service-worker.js` (caching logic) |
| - Edit `wrdler/ui.py` (PWA meta tags, lines 34-86) |
|
|
| To test PWA locally: |
| ```bash |
| 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 Wrdler as a native-like app experience! 🎮🌊** |
|
|
