Hoseg Rewards — App móvil del wallet (Android + iOS) · Diseño v1
Creado: 2026-09-27 · Estado: 🟡 Diseño (pendiente confirmar 3 decisiones) · Pedido de Daniel: "una sola app, solo wallet (no admin/vendedor); quiero las dos opciones (web wallet + app wallet); las notificaciones llegan mejor en app; así ya existe app en Android e iOS".
Base técnica actual: hoseg-cash (Node/Express + SQLite en Zeta, puerto 3010) · https://hoseg-cash.disoftx.solutions
Playbook a reutilizar: wiki/manuales/publicar-app-movil-capacitor.md (Capacitor → Play + Codemagic/TestFlight). Caso ya resuelto: Hoseg Dashboard.
1. Alcance decidido
| Superficie | Hoy | Con la app |
|---|---|---|
Wallet cliente (/w/:token) |
PWA web | PWA + APP nativa (Android/iOS) ← lo nuevo |
Registro (/registro, QR de tienda) |
Web | Web (sin cambios) |
Vendedor (/vendedor) |
Web | Web (sin cambios) |
Admin (/admin) |
Web | Web (sin cambios) |
- Una sola app, solo cliente. Admin y vendedor siguen siendo web.
- La app reutiliza la misma web (Capacitor envuelve
wallet.html) → cero duplicación de lógica. - La app NO reemplaza los pases de Google/Apple Wallet: se complementan (app = saldo, historial, promos, push; pase = tarjeta a mano en el teléfono).
2. Arquitectura propuesta
Cliente ──┬─ PWA (wallet) ─┐
└─ APP (Capacitor) ─┼─► API REST hoseg-cash (Zeta, mismo backend)
Vendedor ─── web /vendedor ─┤
Admin ────── web /admin ─┘
- App = Capacitor (Android + iOS) apuntando al mismo backend. Igual patrón que Hoseg Dashboard: en nativo se parchea
fetchpara usar la URL absoluta del API. - CORS del backend debe sumar los orígenes de la app:
capacitor://localhost,http://localhost,https://localhost. - Identidad: misma que la web (token de la tarjeta). Nada nuevo en base de datos, salvo la tabla de dispositivos/tokens de push (una fila por teléfono).
3. Puntos de diseño (y mi recomendación)
3.1 Entrada a la app (lo más delicado)
Hoy el cliente entra por link mágico /w/<token> (sin contraseña). En la app hay que resolverlo:
- Deep links (universal links): si el cliente toca su link y tiene la app → abre la app con su token. (Requiere apple-app-site-association + assetlinks.json.)
- Escanear QR: botón en la app para escanear el QR de la tarjeta (que ya generamos) o el QR de la tienda (registro).
- Pegar el enlace: fallback simple.
- ✅ Recomendado v1: deep links + escáner QR + "pegar enlace". El registro sigue en la web (QR de tienda).
3.2 Notificaciones (el motivo principal)
- App: push nativo con FCM (Android) + APNs (iOS).
- PWA: seguir con el
web-pushactual (VAPID) o migrar todo a FCM. ✅ Recomendado: FCM para la app y unificar también la PWA en FCM (un solo sistema, un solo backend de envío). - Requisitos: proyecto Firebase (puede reusarse el de Hoseg Dashboard) +
google-services.json+GoogleService-Info.plist+ APNs key.p8subida a Firebase (⚠️ es el mismo pendiente que quedó abierto en Hoseg Dashboard). - Tipos de aviso ya existentes a reutilizar: saldo nuevo/cashback, broadcast de promos, cumpleaños, y a futuro "estás cerca de una tienda" (geofencing ya definido en Google Wallet).
3.3 Features nativos (valor real + lo que Apple exige, guía 4.2)
- 🔔 Push nativo · 📷 Cámara para escanear QR · 🍎🟢 Botones "Añadir a Apple/Google Wallet" (ya existen) · 📤 Compartir (share sheet) · 🔐 Biometría/PIN opcional para abrir · 🌗 Splash + ícono + status bar.
3.4 Fases
- F1 — Shell: Capacitor + wallet + entrada por QR/deep link + ambos botones de wallet. (≈2-3 días)
- F2 — Push: FCM/APNs + tabla de dispositivos + envíos (cashback/promo/cumpleaños). (≈2 días)
- F3 — Pulido: biometría, offline/refresh, íconos/splash, QA en device. (≈1-2 días)
- F4 — Publicación: Android prueba interna + iOS TestFlight (con el Playbook). (≈1 día)
Total estimado: ~1 a 1,5 semanas (reutilizando todo lo ya construido).
4. Decisiones pendientes (para cerrar el diseño)
- Push: ¿unificamos todo en FCM (app + PWA) o la PWA se queda con el web-push actual? → Recomiendo unificar en FCM.
- Nombre e ícono de la app: ¿"Hoseg Rewards" con el logo de Hösėg? ¿App ID
com.hoseg.rewards? - Biometría/PIN para abrir la app: ¿sí o no? → Recomiendo sí (opcional para el cliente).
- APNs key: hay que subir la
.p8a Firebase (mismo trámite pendiente de Hoseg Dashboard) para que iOS reciba push. - Fideliza: ¿esta app queda solo para Hoseg, o se piensa como base de Fideliza (una app por negocio)? → define si el código se hace genérico desde el inicio.
5. Requisitos ya cubiertos
- ✅ Cuentas: Google Play y Apple Developer ya pagadas (misma cuenta Apple
8L4B4YB2Q8). - ✅ Backend, base de datos, reglas, niveles, pases Google/Apple: ya funcionando.
- ✅ Pipeline de publicación documentado en el Playbook.
- ⏳ Pendiente: Firebase/APNs para push.
6. Decisiones confirmadas (2026-09-27) y build de prueba
Confirmado por Daniel:
- Una sola app, solo wallet del cliente (admin/vendedor siguen web).
- Se mantienen las dos opciones: wallet web (PWA) y app — la app se suma, no reemplaza.
- El link lo manda la vendedora (como hoy).
- El QR de la tarjeta sigue siendo para que el vendedor lo escanee (la app del cliente solo muestra el QR, no escanea).
- NO poner aún el botón "Instalar app" en la web wallet (queda para después).
- Push nativo = el motivo principal de la app.
Entrada a la app (modelo): el link de la vendedora abre la app si está instalada (deep link / App Links) → si no, la web. Fallback: pegar el enlace dentro de la app. La app guarda el token y abre directo.
🧪 Build de prueba v0.1 (Android)
- Proyecto:
proyectos/hoseg-rewards-app/(Capacitor 8 · appIdcom.hoseg.rewards· appName "Hoseg Rewards"). www/index.html: pantalla de entrada (pegar enlace) + guarda el token + redirige al wallet real; listenerappUrlOpenlisto para deep links.capacitor.config.json:server.allowNavigation: [hoseg-cash.disoftx.solutions](para que el wallet cargue dentro de la app).- APK firmado (keystore
~/keys/hoseg-rewards-upload.jks, creds encredentials/hoseg-rewards-android-keystore.json):entregables/HosegRewards-0.1.0-release.apk(3.2 MB, versionCode 1 / 1.0). - Link de descarga:
https://hoseg-cash.disoftx.solutions/descargas/hoseg-rewards-0.1.0.apk - Íconos generados a partir del logo Höseg (adaptive + legacy).
Pendiente (siguiente iteración): App Links (deep link automático: assetlinks.json + apple-app-site-association), push nativo (FCM/APNs), íconos/splash definitivos, iOS.
🔗 App Links (deep link) — v0.2
assetlinks.jsonpublicado enhttps://hoseg-cash.disoftx.solutions/.well-known/assetlinks.json(packagecom.hoseg.rewards+ SHA-256 de la upload keyF8:64:AB:19:…:BC:C9). Se sirve desdepublic/.well-known/(el server ya expone dot-dirs).AndroidManifest.xml: intent-filter App Links (https, hosthoseg-cash.disoftx.solutions, pathPrefix/w/,autoVerify=true).- APK 0.2 (versionCode 2):
entregables/HosegRewards-0.2.0-release.apk· link…/descargas/hoseg-rewards-0.2.0.apk. - ⚠️ Cuando se publique en Play (Play App Signing) hay que agregar también el fingerprint de la app signing key de Google al assetlinks.
- ✅ 2026-09-27 — VERIFICADO en el celular de Daniel: el enlace del wallet abre la app (App Link funcionando). Flujo completo: enlace → app → tarjeta.
🔔 Push nativo (FCM) — v0.3 (2026-09-27)
- Opción elegida: proyecto Firebase PROPIO →
hoseg-rewards(aislado del proyectohoseg-dashboard). - App Android registrada:
com.hoseg.rewards(App ID1:376725888690:android:2e6e09ca4b704bbeecf3ab) →google-services.jsonenmobile/android/app/. - Service account
fcm-sender@hoseg-rewards.iam.gserviceaccount.comcon rolfirebasecloudmessaging.admin; clave encredentials/firebase-rewards/service-account-fcm.jsony copiada al contenedor en/app/data/fcm-service-account.json. - Backend (
hoseg-cash): tablaapp_devices,server/fcm.js(FCM v1 sin dependencias), endpointsPOST /api/app/deviceyPOST /api/notify/client(admin, envía a UN cliente: app + web push); CORS ampliado con los orígenes de Capacitor. - App: plugin
@capacitor/push-notifications+ pantalla "Activar notificaciones" enwww/index.html. - APK 0.3 (versionCode 3, 4.5 MB):
entregables/HosegRewards-0.3.0-release.apk·…/descargas/hoseg-rewards-0.3.0.apk. - Manual completo:
wiki/manuales/push-notificaciones-app.md.