| # Wrdler PWA Installation Guide | |
| 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! 🎮🌊** | |