WATranslate v4.7 — Background Web Push

THIS FIXES THE IPHONE-CLOSED-APP PROBLEM.

v4.6:
New-message detection depended on the WATranslate JavaScript polling loop.
If iOS suspended/closed the PWA, that JavaScript was no longer running.

v4.7:
A new incoming WhatsApp webhook now causes THE SERVER to send a standards-based
Web Push message directly to every subscribed agent device.

The installed iPhone Home Screen web app does not need to be open.

FLOW

Customer
  ↓
WhatsApp / Meta webhook
  ↓
public/webhook.php
  ↓
message saved + translated
  ↓
PushService.php
  ↓
Apple/Browser Web Push service
  ↓
iPhone wakes WATranslate service worker
  ↓
Lock Screen / Notification Center notification

WHEN WATRANSLATE IS OPEN
The service worker detects a visible WATranslate client and passes the event to
the page instead of showing a second OS notification.

Result:
- in-app notification card
- existing custom WATranslate sound
- unread counter
- no duplicate system notification

WHEN WATRANSLATE IS CLOSED / SUSPENDED
The service worker is awakened by Web Push.

Result:
- iOS / browser system notification
- current app icon
- customer/contact name
- translated message preview
- iOS/system notification sound if Sound is enabled for WATranslate in device
  notification settings
- tapping the notification opens WATranslate and attempts to open that contact

IMPORTANT ABOUT SOUND
A closed PWA cannot play the custom notification.wav itself.
When the app is closed, iOS controls notification audio and uses the system
notification sound/settings.

The custom WATranslate WAV continues to be used while the app is open.

NO APPLE DEVELOPER ACCOUNT REQUIRED
This uses standards-based Web Push.

IPHONE/IPAD REQUIREMENT
For iOS/iPadOS:
- iOS/iPadOS 16.4 or later
- WATranslate must be installed/added to the Home Screen
- notification permission must be granted from the installed Home Screen app

SETUP AFTER INSTALLING v4.7

1. Open the INSTALLED WATranslate Home Screen app.
2. Log in.
3. Open:
   ... → Settings
4. Find:
   Browser / system notifications
5. Tap:
   Enable notifications
6. Accept the iOS permission prompt if shown.

IMPORTANT:
Even if notification permission was already granted in v4.6, tap Enable
notifications once in v4.7. v4.7 must create and register the Web Push
subscription with the server.

TEST
After Enable notifications is complete:

... → Settings → Test notification

The Test notification button now sends a REAL server-side Web Push request.
It is not a local simulation.

Then test the actual closed-app case:

1. Fully close WATranslate / leave it unopened.
2. Send a new WhatsApp message to the connected test/business number.
3. iPhone should receive a WATranslate notification without opening WATranslate.

SERVER STORAGE

Generated VAPID keys:
storage/push/vapid.json

Registered agent devices:
storage/push/subscriptions.json

Both are protected by:
storage/push/.htaccess

IMPORTANT:
Do NOT delete vapid.json after devices subscribe.
Changing/deleting the VAPID key means existing devices need to subscribe again.

NO SQL REQUIRED.
No Composer installation required.
No third-party PHP library required.

The implementation uses PHP OpenSSL and cURL already available on the
WATranslate server.

FILES TO OVERWRITE

public/index.php
public/api.php
public/webhook.php
assets/app.js
public/assets/app.js
service-worker.js

FILES TO ADD

src/PushService.php
storage/push/.htaccess

FILES NOT CHANGED

root api.php wrapper
root webhook.php wrapper
config.php
database
Google Translation configuration
Meta token/configuration
WhatsApp send logic
branding settings

NETWORK NOTE FOR IPHONE PUSH
The server must be able to make outbound HTTPS requests to the push endpoint
issued by the browser. Apple Web Push endpoints may use *.push.apple.com.

If Enable notifications succeeds but server-side Test notification fails with a
network error, check the hosting/server outbound firewall.

SECURITY
Push endpoints and encryption keys are stored in storage/push, which is denied
from public HTTP access.

Push payloads are encrypted using RFC 8291 aes128gcm and authenticated with
VAPID (RFC 8292).
