🔗 Nexus

← Volver a notas
12 KB 10/10/2026 14:11
🔗

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


1. Preparar el proyecto Capacitor (una vez por app)

  1. mobile/ con @capacitor/core|android|ios + plugins (filesystem, share, push-notifications, preferences, splash-screen, status-bar, app).
  2. API en nativo: dentro del WebView el origen es capacitor://localhost (iOS) o https://localhost (Android), así que los /api/... relativos no resuelven. Solución usada: un config.js que parchea fetch una sola vez apuntando al backend real (solo cuando isNative).
  3. CORS del backend debe permitir capacitor://localhost, http://localhost, https://localhost (+ el dominio propio).
  4. capacitor.config.json: appId, appName, webDir: "../frontend/dist".
  5. Í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

  1. https://play.google.com/console → Crear app (nombre, idioma, tipo Aplicación, Gratis).
  2. 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).
  3. 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).
  4. Pruebas → Prueba interna → Crear versión → subir el AAB → notas → Guardar → Revisar → Publicar.
  5. 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 ""

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

  1. El build aparece en TestFlight (tarda unos minutos en procesar).
  2. 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.
  3. Para no repetirlo: ITSAppUsesNonExemptEncryption = NO en el Info.plist.
  4. 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).
  5. ⚠️ 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.