hamkadr/docs/PWA-TWA.md

Hamkadr PWA, notifications & Cafe Bazaar (TWA)

Hamkadr ships as a PWA (installable web app). The same PWA is wrapped as a TWA (Trusted Web Activity) to publish on Cafe Bazaar / Google Play as a real Android app — no separate codebase.

What's already in the app

• GET /manifest.webmanifest — name, icons (/icons/icon-192.png, -512), display: standalone, fa/RTL.
• GET /sw.js — service worker: offline shell + push + notificationclick handlers.
• Registered in _Layout + iOS apple-* meta tags + apple-touch-icon.
• /Download — install + "enable notifications" + per-OS help.
• POST /push/subscribe — stores the browser's Web Push subscription (WebPushSubscription).
• VAPID + push settings in /Admin/Settings.

Install paths: Web/Windows = browser "Install"; Android = Add to Home screen (or Bazaar TWA); iOS = Safari → Share → Add to Home Screen.

Notifications

1. On-device (works now): the "🔔 فعال‌سازی اعلان‌ها" button asks permission and shows a local confirmation notification. The service worker is ready to display server pushes.
2. Server push (to wire): generate a VAPID key pair and paste it in /Admin/Settings:

   npx web-push generate-vapid-keys   # → Public Key + Private Key
   

   Subscriptions are already captured in WebPushSubscriptions. To send, add the WebPush NuGet (through the Nexus proxy) and a small broadcaster:

   var client = new WebPush.WebPushClient();
   var vapid = new WebPush.VapidDetails(subject, publicKey, privateKey);
   foreach (var s in subs)
       client.SendNotification(new WebPush.PushSubscription(s.Endpoint, s.P256dh, s.Auth),
           JsonSerializer.Serialize(new { title, body, url }), vapid);
   

   ⚠️ Iran note: Chrome's push goes through FCM, which may be filtered. The TWA on Bazaar can instead use Bazaar's own push (Pushe/native) for reliable Android delivery.

Publishing to Cafe Bazaar (TWA)

1. Install Bubblewrap: npm i -g @bubblewrap/cli
2. Initialize from the live manifest:

   bubblewrap init --manifest https://hamkadr.ir/manifest.webmanifest
   bubblewrap build      # produces app-release-signed.apk + the signing key
   

3. Digital Asset Links — so the TWA opens full-screen with no URL bar. Get the SHA-256 fingerprint Bubblewrap printed and serve this at https://hamkadr.ir/.well-known/assetlinks.json:

   [{
     "relation": ["delegate_permission/common.handle_all_urls"],
     "target": { "namespace": "android_app", "package_name": "ir.hamkadr.twa",
       "sha256_cert_fingerprints": ["<SHA256_FROM_BUBBLEWRAP>"] }
   }]
   

   Easiest: add a tiny location = /.well-known/assetlinks.json { ... } block to the central nginx (next to the hamkadr vhost) returning that JSON, then nginx -s reload.
4. Upload the signed APK to Cafe Bazaar developer panel; for Play, upload the AAB.