Playbook — Publicar una web como app móvil (Android + iOS) con Capacitor
Creado: 2026-09-27 · Caso base: Hoseg Dashboard (web React/Vite → app Android + iOS)
Reutilizable para cualquier web nuestra (Fideliza, Hoseg Cash, etc.). Si vas a crear otra app, empieza por aquí.
0. Arquitectura y decisiones previas
- Enfoque: envolver la web existente con Capacitor (una sola base de código; reusa toda la UI y el backend). Descartamos React Native / reescritura nativa.
- Distribución privada (no pública):
- Android: Play Console → Prueba interna o Cerrada. No aparece en búsquedas; link de opt-in + correos whitelist.
- iOS: TestFlight (lo más cercano; builds caducan cada 90 días) o Unlisted (pasa revisión, permanente, no descubrible).
- Cuentas necesarias: Google Play ($25, única vez) · Apple Developer ($99/año).
1. Preparar el proyecto Capacitor (una vez por app)
mobile/con@capacitor/core|android|ios+ plugins (filesystem,share,push-notifications,preferences,splash-screen,status-bar,app).- API en nativo: dentro del WebView el origen es
capacitor://localhost(iOS) ohttps://localhost(Android), así que los/api/...relativos no resuelven. Solución usada: unconfig.jsque parcheafetchuna sola vez apuntando al backend real (solo cuandoisNative). - CORS del backend debe permitir
capacitor://localhost,http://localhost,https://localhost(+ el dominio propio). capacitor.config.json:appId,appName,webDir: "../frontend/dist".- Íconos/splash:
@capacitor/assets→mobile/assets/icon.png+splash.png.
2. Android — build de release (local en el VPS)
Entorno (Omni):
- Android SDK: /home/admin/android-sdk (build-tools 35/36, platform android-36, licencias aceptadas) · mobile/android/local.properties → sdk.dir=...
- JDK 21 obligatorio (Capacitor 8; el java del sistema es 17): /home/admin/jdk21/jdk-21.0.12.1+1
- Keystore de upload: ~/keys/hoseg-dashboard-upload.jks (⚠️ no perderlo) · passwords en credentials/*-android-keystore.json
Pasos:
cd frontend && npm run build # la app embebe frontend/dist
cd ../mobile && npx cap sync android # copia dist → android/app/src/main/assets/public
cd android
export JAVA_HOME=/home/admin/jdk21/jdk-21.0.12.1+1 && export PATH="$JAVA_HOME/bin:$PATH"
./gradlew bundleRelease assembleRelease
Salidas:
- AAB → mobile/android/app/build/outputs/bundle/release/app-release.aab
- APK → mobile/android/app/build/outputs/apk/release/app-release.apk
Antes de compilar: subir versionCode (+1) y versionName en mobile/android/app/build.gradle.
Verificar: jarsigner -verify <aab> → jar verified; aapt dump badging <apk> | head → versionCode/versionName correctos.
Descarga pública (opcional): dejar el APK en frontend/public/descargas/ (gitignored) → se sirve en https://dominio/descargas/<archivo>.apk con content-type application/vnd.android.package-archive.
3. Android — Play Console
- https://play.google.com/console → Crear app (nombre, idioma, tipo Aplicación, Gratis).
- Contenido de la app: política de privacidad (URL), acceso a la app (si requiere login → dar usuario/contraseña demo), anuncios (No), clasificación de contenido (cuestionario), público objetivo (18+), seguridad de datos (correo/nombre, actividad, identificadores; cifrado en tránsito; no se comparten), apps gubernamentales (No), funciones financieras (No).
- Ficha: nombre, descripción corta (≤80), descripción larga (≤4000), ícono 512×512, gráfico destacado 1024×500, capturas de teléfono (mín. 2, 9:16).
- Pruebas → Prueba interna → Crear versión → subir el AAB → notas → Guardar → Revisar → Publicar.
- Testers: agregar correos → copiar link de opt-in → el tester abre el link en el celular → "Convertirme en tester" → Instalar.
Datos clave:
- Prueba interna: máx 100 testers, corre inmediata, no expira.
- El requisito 12 testers × 14 días aplica solo para pasar a Producción (cuenta personal nueva) y se cuenta en prueba cerrada, no en la interna.
- Actualizar = subir versionCode mayor al mismo track (les llega como actualización normal).
- Advertencias normales (no bloquean): "no hay archivo de desofuscación" (si no usas R8/ProGuard) y "faltan símbolos de depuración nativos" (se puede añadir ndk { debugSymbolLevel "FULL" }).
4. iOS — Codemagic (build en la nube, sin Mac)
Cuenta: https://codemagic.io/signup (entrar con GitHub para conectar el repo directo).
Al agregar la app: repo GitHub + branch master + project type = iOS + root folder vacío (el codemagic.yaml vive en la raíz y él entra a frontend/ y mobile/).
Requisitos en Apple (una vez):
1. App ID com.<dominio>.<app> en https://developer.apple.com/account/resources/identifiers (Explicit; marcar Push Notifications si se usa FCM).
2. App en https://appstoreconnect.apple.com → Apps → + → Nueva app (nombre, bundle id, SKU, idioma).
3. App Store Connect API Key: ASC → Usuarios y acceso → Integraciones → App Store Connect API → + → nombre codemagic, rol App Manager → Generar → descargar el .p8 (¡una sola vez!) + anotar Key ID e Issuer ID.
4. En Codemagic: Settings → Integrations → Developer Portal → Connect → pegar nombre + Issuer ID + Key ID + .p8.
Variables de firma (clave del asunto):
- Codemagic no crea el certificado si no le das una clave privada. Generar una:
ssh-keygen -t rsa -b 2048 -m PEM -f ios_distribution_private_key -q -N ""
- En Codemagic → App settings → Environment variables → crear grupo
code-signing→ variableCERTIFICATE_PRIVATE_KEY(secret) = contenido del archivo.
codemagic.yaml (patrón que funciona):
workflows:
ios-testflight:
name: iOS · TestFlight
instance_type: mac_mini_m2
max_build_duration: 60
integrations:
app_store_connect: <nombre de la integración> # OJO: única clave válida
environment:
node: 22.14.0
xcode: latest
cocoapods: default
groups: [code-signing]
vars: { BUNDLE_ID: com.dominio.app }
scripts:
- name: Frontend — instalar y compilar
script: |
cd frontend && npm ci && npm run build
- name: Móvil — sync iOS
script: |
cd mobile && npm ci && npx cap sync ios
- name: Firma (keychain + certificado/perfil)
script: |
keychain initialize
app-store-connect fetch-signing-files "$BUNDLE_ID" --type IOS_APP_STORE --create
keychain add-certificates
xcode-project use-profiles
- name: Compilar IPA
script: |
xcode-project build-ipa --project "mobile/ios/App/App.xcodeproj" --scheme "App"
artifacts: [build/ios/ipa/*.ipa]
publishing:
app_store_connect:
auth: integration
submit_to_testflight: true
API de Codemagic (útil para lanzar/monitorear sin UI): header x-auth-token.
- GET /apps · GET /team/{teamId} · GET /builds?appId=…
- POST /builds {appId, workflowId, branch} → {buildId}
- Logs por paso: GET /builds/{id} → buildActions[].subactions[].logUrl
- ⚠️ Responde 401 intermitente → reintentar.
5. iOS — App Store Connect / TestFlight
- El build aparece en TestFlight (tarda unos minutos en procesar).
- Responder "Falta información de exportación": la app usa solo cifrado estándar (HTTPS/TLS) → marcar «Algoritmos de encriptación estándar en lugar de, o además de, la utilización del sistema operativo de Apple» → queda exenta.
- Para no repetirlo:
ITSAppUsesNonExemptEncryption = NOen elInfo.plist. - Testers: internos (usuarios en ASC con rol; máx 100) o externos (por correo/link; hasta 10.000; el build pasa beta review de Apple).
- ⚠️ Los builds de TestFlight caducan a los 90 días → re-subir periódicamente.
6. ❗ Errores comunes y su solución (los que nos pasaron)
| Error | Causa | Solución |
|---|---|---|
No matching profiles found for bundle identifier … app_store |
El bloque ios_signing no crea certificados: solo usa los subidos a Code Signing Identities. Y/o el App ID no existe. |
Crear el App ID en Apple y usar la firma por CLI (fetch-signing-files --create) en vez de ios_signing. |
Command CodeSign failed … errSecInternalComponent |
Faltaba preparar/desbloquear el keychain. | Agregar keychain initialize antes de fetch-signing-files. |
integrations -> apple_developer_portal: extra fields not permitted |
El YAML solo acepta app_store_connect. |
Referenciar la integración como app_store_connect: <nombre>. |
| La tarjeta "App Store Connect" no aparece en Settings → Integrations | En esta versión la API key se agrega en la tarjeta "Developer Portal". | Usar Developer Portal → Connect (pide nombre + Issuer ID + Key ID + .p8). |
| "Global variables… removed from personal accounts" | Las variables globales están en solo lectura en cuentas personales. | Crear las variables dentro de la app (App settings → Environment variables), en un grupo. |
El build no ve el codemagic.yaml |
Project path mal puesto. | Root folder vacío (o .) y branch correcto. |
| "The repository doesn't seem to contain a mobile application" | Codemagic no detecta Capacitor. | Set project type manually → iOS. |
El link /descargas/*.apk devolvía HTML |
El catch-all del SPA capturaba la ruta. | Servir el binario desde frontend/public/descargas/ (lo sirve express.static). |
| Cambios de frontend no se ven en prod | El SPA va dentro de la imagen Docker. | docker compose build && up -d (no basta up -d). |
7. Checklist reutilizable (copiar por cada app nueva)
Preparación
- [ ] mobile/ con Capacitor + plugins + webDir
- [ ] config.js con parche de fetch para nativo + CORS del backend con los orígenes Capacitor
- [ ] Ícono + splash + appId/appName
Android
- [ ] Keystore de upload generado y respaldado (credenciales en credentials/)
- [ ] versionCode incrementado
- [ ] AAB + APK firmados y verificados (jarsigner -verify)
- [ ] APK en frontend/public/descargas/ (link público) si se quiere side-load
- [ ] Play Console: app creada + "Contenido de la app" + ficha + AAB en prueba interna + testers
iOS
- [ ] Cuenta Codemagic (con GitHub) + app agregada (type iOS, root vacío)
- [ ] App ID + app en App Store Connect
- [ ] ASC API Key (rol App Manager) → integración Developer Portal en Codemagic
- [ ] Grupo code-signing con CERTIFICATE_PRIVATE_KEY
- [ ] codemagic.yaml (patrón de arriba)
- [ ] Build verde → TestFlight
- [ ] Export compliance (cifrado estándar) / ITSAppUsesNonExemptEncryption=NO
- [ ] Testers (internos o externos)
Entregables y registro
- [ ] AAB/APK/IPA copiados a entregables/ con sha256
- [ ] Documentar credenciales en credentials/ y el proyecto en wiki/proyectos/<proyecto>-app-movil.md
8. Rutas y credenciales (referencia)
| Qué | Dónde |
|---|---|
| Proyecto móvil | proyectos/<app>/mobile/ |
| Build Android local | SDK /home/admin/android-sdk · JDK21 /home/admin/jdk21/jdk-21.0.12.1+1 |
| Keystore Android | ~/keys/<app>-upload.jks + credentials/<app>-android-keystore.json |
| Clave privada iOS | credentials/<app>-ios-dist-key (contenido en Codemagic como CERTIFICATE_PRIVATE_KEY) |
| API token Codemagic | credentials/codemagic-token.txt |
| Deploy web (Zeta) | ssh -i ~/.ssh/zeta_nexus opsmgr@100.83.7.25 · /home/opsmgr/proyectos/<app> |
Caso de referencia completo: wiki/proyectos/hoseg-dashboard-app-movil.md.
3-bis. Android — subir el AAB por API (sin entrar a la consola)
Script listo: ~/.openclaw/workspace/scripts/play_upload.js (usa googleapis, ya instalado en scripts/node_modules).
Requisitos (una sola vez — Daniel):
1. Google Cloud Console → habilitar Google Play Android Developer API.
2. Crear una cuenta de servicio y descargar su clave JSON.
3. Play Console → Configuración → Usuarios y permisos → Invitar usuarios: pegar el email de la cuenta de servicio (...@....iam.gserviceaccount.com), darle acceso a la app y el permiso de "Administrar versiones de prueba" (Releases).
4. Dejar la clave en credentials/google-play.json.
Uso:
node scripts/play_upload.js \
--aab entregables/HosegDashboard-1.4.0-release.aab \
--track internal \
--notes "Sesión persistente + Promociones."
# opciones: --track internal|alpha|beta|production · --package com.hoseg.dashboard
# --key credentials/google-play.json · --status completed|draft · --lang es-419
Crea un edit, sube el AAB, lo asigna a la pista y hace commit. Play lo procesa en minutos.
Si da 403/permission: faltó habilitar la API o dar el permiso de Releases a la cuenta de servicio.