StaffMagic

Mobile App Guide

Install StaffMagic on your phone or tablet as a Progressive Web App for quick access and offline support.

StaffMagic is a Progressive Web App (PWA), which means you can install it on your phone or tablet and use it like a native app - no app store required.

Benefits of Installing StaffMagic

  • Quick Access: Launch from your home screen with one tap
  • Offline Support: View your schedule even without internet connection
  • Faster Loading: App loads instantly after installation
  • Push Notifications: Get notified about schedule changes (coming soon)
  • Full Screen: No browser address bar for a cleaner experience

Installation Instructions

Android (Chrome)

  1. Open StaffMagic in Chrome on your Android device
  2. You'll see an "Add to Home Screen" banner at the bottom, or:
    • Tap the three-dot menu (⋮) in the top right
    • Select "Add to Home screen" or "Install app"
  3. Tap "Install" in the confirmation dialog
  4. StaffMagic will appear on your home screen

iPhone / iPad (Safari)

iOS requires a few extra steps since Safari doesn't show automatic install prompts:

  1. Open StaffMagic in Safari (not Chrome or other browsers)
  2. Tap the Share button (square with arrow pointing up) at the bottom
  3. Scroll down and tap "Add to Home Screen"
  4. Optionally edit the name, then tap "Add" in the top right
  5. StaffMagic will appear on your home screen

Note: On iOS, you must use Safari. Other browsers like Chrome don't support PWA installation on iOS.

Desktop (Chrome, Edge)

  1. Open StaffMagic in Chrome or Edge
  2. Look for the install icon (⊕) in the address bar, or:
    • Click the three-dot menu
    • Select "Install StaffMagic"
  3. Click "Install" in the dialog
  4. StaffMagic will open in its own window and appear in your apps

Using StaffMagic Offline

Once installed, StaffMagic caches your schedule data so you can view it even without internet:

What Works Offline

  • Viewing your current and upcoming schedule
  • Viewing shift details
  • Navigating between weeks

What Requires Internet

  • Submitting time-off requests
  • Requesting shift swaps
  • Updating your availability
  • Receiving real-time schedule updates

Offline Indicator

When you lose internet connection, a yellow banner appears at the top of the screen:

⚠️ You're offline. Showing cached schedule.

The banner disappears automatically when your connection is restored.

Updating the App

StaffMagic updates automatically in the background. When a new version is available:

  1. A banner appears: "A new version is available"
  2. Tap "Update" to reload with the latest version
  3. Your data and login session are preserved

If you dismiss the update, it will apply the next time you open the app.

Troubleshooting

App won't install on iPhone

  • Make sure you're using Safari, not Chrome or another browser
  • Check that you're on iOS 11.3 or later
  • Try clearing Safari cache: Settings > Safari > Clear History and Website Data

App shows old schedule data

  • Pull down to refresh the page
  • Check your internet connection
  • If using the installed app, try the "Update" banner if shown
  • As a last resort, uninstall and reinstall the app

Notifications aren't working

Push notifications require:

  • The app to be installed (not just bookmarked)
  • Notification permissions granted in your device settings
  • An active internet connection to receive new notifications

To enable notifications:

  1. Open StaffMagic
  2. Go to Settings > Notifications
  3. Toggle on Push Notifications
  4. Accept the browser permission prompt

App disappeared from home screen

This can happen after iOS updates. Simply reinstall following the instructions above.

Device Requirements

| Platform | Minimum Version | Browser | |----------|-----------------|---------| | Android | Android 5.0+ | Chrome 57+ | | iOS | iOS 11.3+ | Safari only | | Windows | Windows 10+ | Chrome 73+ or Edge 79+ | | macOS | macOS 10.13+ | Chrome 73+ or Safari 11.1+ |

Privacy & Data

  • Storage: The app stores schedule data locally for offline access
  • Cache Size: Typically under 5MB
  • Data Sync: Local data syncs with the server when online
  • Uninstalling: Removes all cached data from your device

Frequently Asked Questions

Q: Is this a real app or just a website? A: It's both! StaffMagic is a Progressive Web App - a website that can be installed and used like a native app, with offline support and home screen access.

Q: Do I need to download anything from the App Store? A: No. PWAs are installed directly from the browser without going through an app store.

Q: Will it use a lot of storage on my phone? A: No, StaffMagic uses minimal storage (typically under 5MB) compared to native apps.

Q: Can I use StaffMagic on multiple devices? A: Yes! Your account syncs across all devices. Install on as many devices as you like.

Q: What if I prefer the website version? A: You can always use StaffMagic in your browser at your organization's URL. The installed app and website are identical in functionality.

For Administrators

Encouraging App Installation

To help your team adopt the mobile app:

  1. Share this guide with employees during onboarding
  2. Demonstrate the installation process in team meetings
  3. Highlight offline access as a key benefit
  4. Remind staff that no app store download is required

Technical Details

The PWA includes:

  • Service Worker: Handles offline caching and background sync
  • Web App Manifest: Defines app name, icons, and display mode
  • Runtime Caching: Caches API responses for offline schedule viewing

Customizing App Icons

App icons are located in /frontend/public/icons/. To customize:

  1. Replace the PNG files with your branded icons
  2. Maintain the same file names and dimensions
  3. Rebuild and redeploy the frontend

Icon sizes required:

  • 72x72, 96x96, 128x128, 144x144
  • 152x152, 192x192, 384x384, 512x512