{"id":31906439,"url":"https://github.com/5ht2b/heartbeat-pwa","last_synced_at":"2026-07-12T21:31:28.011Z","repository":{"id":318148467,"uuid":"1062581748","full_name":"5HT2B/heartbeat-pwa","owner":"5HT2B","description":"The heartbeat client PWA implementation","archived":false,"fork":false,"pushed_at":"2025-10-05T11:32:55.000Z","size":106,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-05T13:20:02.177Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/5HT2B.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-23T12:56:28.000Z","updated_at":"2025-10-05T11:32:59.000Z","dependencies_parsed_at":"2025-10-05T13:20:20.417Z","dependency_job_id":"34f9c0ca-df86-4ce8-8a87-ff641e3fbae5","html_url":"https://github.com/5HT2B/heartbeat-pwa","commit_stats":null,"previous_names":["5ht2b/heartbeat-pwa"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/5HT2B/heartbeat-pwa","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5HT2B%2Fheartbeat-pwa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5HT2B%2Fheartbeat-pwa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5HT2B%2Fheartbeat-pwa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5HT2B%2Fheartbeat-pwa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/5HT2B","download_url":"https://codeload.github.com/5HT2B/heartbeat-pwa/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/5HT2B%2Fheartbeat-pwa/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279015770,"owners_count":26085749,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-13T02:00:06.723Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-13T14:47:25.416Z","updated_at":"2025-10-13T14:47:26.692Z","avatar_url":"https://github.com/5HT2B.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# heartbeat-pwa\n\nThis is the Progressive Web App (PWA) client for [Heartbeat](https://github.com/5HT2B/heartbeat). It will ping the central server every minute, as long as the device is actively being used (optional activity detection) and the app is enabled.\n\nThe PWA can be installed on mobile devices (iOS/Android) and desktop browsers.\n\n# Jump to\n- [Installation](#installation)\n- [Configuration](#configuration)\n- [Background Operation](#background-operation)\n- [Deployment](#deployment)\n\n## Installation\n\n### Option 1: Visit the hosted version\n\n1. Open your mobile browser and navigate to your hosted Heartbeat PWA URL (example: https://pwa.heartbeat.josie.health/)\n2. For iOS: Tap the share button and select \"Add to Home Screen\"\n3. For Android: Tap the menu and select \"Install App\" or \"Add to Home Screen\"\n4. The app will install and appear on your home screen with an icon\n\n### Option 2: Self-host the PWA\n\n1. Clone or download the PWA files:\n```bash\ngit clone https://github.com/5HT2B/heartbeat-pwa.git\ncd heartbeat-pwa\n```\n\n2. Serve the files using any web server:\n```bash\n# Using Python\npython3 -m http.server 8000\n\n# Using Node.js\nnpx serve .\n```\n## Configuration\n\n1. Open the PWA in your browser or installed app\n2. Enter your Heartbeat server configuration:\n   - **Server URL**: Your Heartbeat server endpoint (e.g., `https://your.heartbeat.domain`)\n   - **Auth Token**: Your authentication token from the Heartbeat server\n   - **Device Name**: A friendly name for this device (e.g., \"iPhone\", \"Android Tablet\")\n\n![screenshot](./screenshot.jpg)\n\n3. Toggle options:\n   - **Enable Heartbeat**: Start/stop sending heartbeats\n   - **Activity Detection**: Only send heartbeats when device is actively used (within 2 minutes)\n   - **Enable Notifications**: Allow notifications for connection status changes\n\n4. Click \"Save Configuration\" to persist your settings\n\n## Background Operation\n\n### Server-Initiated Heartbeat Checks (Recommended)\n\nThe PWA supports **server-initiated heartbeat checks** via push notifications:\n\n**How it works:**\n1. PWA subscribes to push notifications when \"Enable Server Checks\" is clicked\n2. Server can send push notifications to wake up the service worker at any time\n3. Service worker automatically sends a heartbeat and shows a notification\n4. Works even when PWA is completely closed on the device\n\n**Setup Requirements:**\n1. Server must have VAPID keys configured (see [Server Setup](#server-setup-for-push-notifications) below)\n2. Enable notifications in PWA settings\n3. Click \"Enable Server Checks\" button\n4. Server admin can trigger checks via API or scheduled checkins\n\n### Traditional Background Sync (Limited)\n\nWithout server-initiated checks, background operation is limited:\n\n#### Android (Chrome/Edge)\n- **When installed as PWA**: Limited background execution with Periodic Background Sync\n- **Minimum interval**: 12 hours when app is closed (browser limitation)\n- **Best practice**: Keep app open but minimized for continuous heartbeats\n\n#### iOS (Safari)\n- **No background execution** when PWA is closed\n- **Must keep app open** (can be minimized) for heartbeats to continue\n- **Alternative**: Use Shortcuts app to periodically open the PWA\n\n#### Desktop Browsers\n- Background sync works when browser is running\n- Service worker remains active for offline queuing\n- Best results with PWA installed as desktop app\n\n## Server Setup for Push Notifications\n\nTo enable server-initiated heartbeat checks, the main heartbeat server needs to be configured with VAPID keys and the new push notification endpoints.\n\n### Prerequisites\n\nThe main heartbeat server must be updated with the push notification functionality.\n\n### 1. Generate VAPID Keys\n\n```bash\n# Install web-push CLI tool\nnpm install -g web-push\n\n# Generate VAPID keys\nweb-push generate-vapid-keys\n\n# Output will look like:\n# Public Key: BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U\n# Private Key: tUkzMcPbtl2-xZ4Z5A1OqiELPo2Pc9-SFNw6hU8_Hh0\n```\n\n### 2. Configure Server Environment\n\nAdd to your heartbeat server's `.env` file:\n\n```bash\n# VAPID Configuration for Push Notifications\nVAPID_PUBLIC_KEY=BEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U\nVAPID_PRIVATE_KEY=tUkzMcPbtl2-xZ4Z5A1OqiELPo2Pc9-SFNw6hU8_Hh0\nVAPID_SUBJECT=mailto:your-email@example.com\n```\n\n### 3. Configure PWA\n\nThe PWA now supports configuring the VAPID public key directly through the user interface - no code changes needed:\n\n1. Open the PWA configuration section\n2. Enter your VAPID public key in the \"VAPID Public Key (for Server Checks)\" field\n3. Save your configuration\n4. Click \"Enable Server Checks\" to subscribe to push notifications\n\nExample VAPID public key format:\n```\nBEl62iUYgUivxIkv69yViEuiBIa-Ib9-SkvMeAtA3LFgDzkrxZJjSgSnfckjBJuBkr3qBUYIHBQFLXYp5Nksh8U\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5ht2b%2Fheartbeat-pwa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2F5ht2b%2Fheartbeat-pwa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2F5ht2b%2Fheartbeat-pwa/lists"}