Oskar Austegard

🦄 Unicorn Spotter PWA - Mobile Installation Guide

A magical Progressive Web App for tracking unicorn sightings! Fully installable on iOS and Android devices.

Features

Quick Deploy

Option 1: Static Hosting (Easiest)

Upload unicorn-spotter.html to any static host:

Option 2: Single File Server

# Using Python
python3 -m http.server 8000

# Using Node.js
npx serve .

# Access at http://localhost:8000/unicorn-spotter.html

Mobile Installation

iPhone/iPad (iOS/iPadOS)

  1. Open Safari and navigate to your deployed URL
  2. Tap the Share button (⬆️) at the bottom
  3. Scroll down and tap “Add to Home Screen”
  4. Edit the name if desired, tap “Add”
  5. App appears on home screen with icon

Important for iOS:

Android (Chrome/Edge/Samsung Internet)

  1. Open browser and navigate to your URL
  2. Tap the menu (⋮) button
  3. Select “Add to Home Screen” or “Install App”
  4. Confirm installation
  5. App appears in app drawer and home screen

Alternatively: Look for the install prompt banner that appears automatically.

Permission Requests

On first launch, the app requests:

  1. 📍 Location - Required to:
    • Show your position on map
    • Calculate distances to sightings
    • Subscribe to nearby unicorn reports
  2. 🔔 Notifications - Required to:
    • Alert you of new sightings nearby
    • Work even when app is closed

Both permissions are required for full functionality!

Using the App

Viewing Sightings

On Map:

Sightings List:

Reporting Sightings

  1. Tap “🦄 Spotted a Unicorn!” button
  2. Tap the location on the map where you saw it
  3. Optionally add details (color, horn sparkle level, etc.)
  4. Submit!

Rate Limiting: You can only report once every 5 minutes to prevent spam.

Configuration

Edit the CONFIG object in the HTML file:

const CONFIG = {
    WS_URL: 'wss://api.unicornspotter.app/ws',  // Your WebSocket server
    API_URL: 'https://api.unicornspotter.app',  // Your REST API
    DEMO_MODE: true  // Set to false when backend is ready
};

Demo Mode

Production Mode

Set DEMO_MODE: false and provide backend URLs:

WebSocket Messages (Server → Client):

{
  "type": "sighting_new",
  "sighting": {
    "id": "string",
    "latitude": 37.7749,
    "longitude": -122.4194,
    "details": "Shimmering purple horn!",
    "created_at": "2025-10-03T12:00:00Z",
    "expires_at": "2025-10-03T16:00:00Z"
  }
}

REST API Endpoints:

POST /sightings
Body: { latitude, longitude, details? }

GET /sightings/nearby?lat={lat}&lng={lng}&radius={meters}
Returns: array of sightings

Mobile-Specific Features

Haptic Feedback

Adaptive UI

Background Notifications

Browser Support

Feature iOS Safari Chrome Android Samsung Internet
Install ✅ 11.3+ ✅ 76+ ✅ 4.0+
Geolocation ✅ ✅ ✅
Notifications ✅ 16.4+ ✅ ✅
Service Worker ✅ 11.3+ ✅ 40+ ✅ 4.0+
WebSocket ✅ ✅ ✅

Troubleshooting

Location not working

Notifications not showing

Can’t install on iOS

Map not loading

WebSocket connection fails (Production)

Addresses not loading in list

Development Tips

Testing Locally

  1. Use HTTPS for full PWA features: 
    # Using mkcert
mkcert -install
mkcert localhost
python3 -m http.server --bind 0.0.0.0 8000
  2. Or use ngrok for HTTPS: 
    ngrok http 8000

Mobile Debugging

iOS Safari:

  1. Connect iPhone to Mac
  2. Safari → Develop → [Your iPhone] → [Page]
  3. Use Web Inspector console

Android Chrome:

  1. Connect phone via USB
  2. Chrome → chrome://inspect
  3. Click “Inspect” on your device

Force PWA Update

// In service worker
self.addEventListener('activate', (event) => {
    event.waitUntil(
        caches.keys().then(keys => 
            Promise.all(keys.map(key => caches.delete(key)))
        )
    );
});

Backend Architecture

For production deployment, you’ll need:

  1. WebSocket Server (Node.js/Go/Python)
    • Handle client connections
    • Broadcast new sightings to subscribers
    • Manage geographic subscriptions
  2. REST API (Express/FastAPI/Gin)
    • Create new sightings
    • Query nearby sightings
    • Handle expiration (4 hours)
  3. Database (PostgreSQL + PostGIS)
    • Store sighting locations
    • Efficient geographic queries
    • Auto-delete expired sightings
  4. Rate Limiting (Redis)
    • Prevent spam (5 min cooldown)
    • IP-based or session-based

Security Considerations

Performance

License

Do whatever you want with it! 🦄✨

Credits

Remember: Unicorns are magical creatures. Treat them with respect! 🦄🌈✨

This site is open source. Improve this page.