Builds de Android

Compila y envía apps para Android a Google Play Store con la infraestructura dedicada de Capgo.

Lo que aprenderás

• Aprenderás a subir tu app mediante Capgo Native build
• Aprenderás a configurar las credenciales para Capgo Native Build

Requisitos

• Necesitas tener una cuenta activa de Google Developer
• Debes tener instalado Android Studio
• Tu app debe compilar correctamente con Android Studio

Nota

Usaré la siguiente app para el tutorial: https://github.com/Cap-go/capgo-tutorial-native-build-app

Recomendado: onboarding automatizado

No tienes que hacer nada de esto a mano. El onboarding de Capgo crea y configura tus credenciales de firma de Android (keystore + cuenta de servicio de Google Play) por ti; este es el camino recomendado:

bunx @capgo/cli@latest build init --platform android

La siguiente guía manual es solo para quienes prefieren configurar sus propias credenciales o quieren entender exactamente qué hace Capgo internamente.

La primera build manual

Antes de empezar a compilar la app con Capgo, primero debemos configurarlo y realizar una primera build de Android manualmente. Hacer una build manual primero tiene sus ventajas:

• Prepararás las credenciales para la futura build de Capgo
• Crearás un registro en la Play Store Console

Hacer la build de la app manualmente con Android Studio

Antes de empezar a compilar la app con Capgo, necesitamos realizar una build manual con Android Studio.

1. Abrir Android Studio

   Ejecuta bunx cap open android para abrir el proyecto de Android Studio.

2. Haz clic en Build -> Generate Signed App Bundles / APKs

3. Selecciona Android App Bundle y haz clic en Next

Crear un Keystore

En este momento, te falta el archivo keystore. Este archivo se usa para firmar tu app, lo que permite que Google sepa que tú eres quien la desarrolló. Para generarlo, usaremos el método de la interfaz gráfica de Android Studio. También existe una forma de hacerlo mediante la línea de comandos, pero no la cubriremos en este tutorial.

1. Haz clic en Create new

2. Ingresa la ruta del Key Store

   Precaución

   Esto DEBE GUARDARSE - se usará más adelante

3. Configura la contraseña del Key Store

   Nota

   Recomiendo usar la misma contraseña para el Key Store y el Key Alias.

   Precaución

   Esto DEBE GUARDARSE - se usará más adelante

4. Completa el resto del formulario

   1. Mantén el Key Alias tal cual (key0)
   2. Completa los detalles del certificado. He usado datos de ejemplo, pero debes usar los tuyos.

   

5. Haz clic en OK

Finalizar la build manual

1. Asegúrate de que todos los datos del keystore sean correctos y haz clic en Next

2. Selecciona el release build variant y haz clic en Create

3. Una vez finalizado el build, verás la siguiente pantalla

   1. Este popup indica que el build fue exitoso.
   2. Haz clic en el locate botón: esto abrirá el explorador de archivos y deberías ver el build allí.

4. Asegúrate de que puedes ver el build en el explorador de archivos

Crear la app en Play Store Console

1. Ve a Google Play Console

2. Selecciona la cuenta de desarrollador correcta

3. Haz clic en Create app

4. Elige el nombre de la app y el idioma

5. Selecciona la categoría de la app y si es de pago o gratuita

6. Acepta los términos y condiciones

   Precaución

   Asegúrate de leer los términos y condiciones antes de aceptarlos.

7. Haz clic en Create

Crear el grupo de testing interno

Ahora que has creado la app, puedes crear un grupo de pruebas internas. Como no voy a publicar la app para todo el mundo en la Play Store, tendré que crear un grupo de pruebas internas.

Nota

Las pruebas internas siguen siendo la forma más rápida de hacer un smoke-test de tu build distribuido en Play antes del lanzamiento oficial.

Si tu cuenta de desarrollador es una cuenta personal creada después del 13 de noviembre de 2023, las pruebas internas necesitas sí reemplazan el requisito de closed testing para acceder a producción. Aun así, necesitarás un closed test con al menos 12 testers inscritos durante 14 días consecutivos antes de producción.

1. Ve a internal testing Haz clic en Test and release -> Testing -> Internal testing

   

2. Haz clic en Testers

3. Haz clic en Create email list

4. Nombre la lista de correos

5. Añada los correos de los testers

6. Presiona Enter y haga clic en Save

7. Haz clic en Create group

8. Asegúrese de que la nueva lista esté seleccionada y haga clic en Save

Subir la app al grupo de testing interno

Ahora que has creado el grupo de pruebas internas, puedes subir la app a dicho grupo.

1. Ve a Test and release -> Testing -> Internal testing

2. Haz clic en el Releases botón

3. Haz clic en Create new release

4. Haz clic en Upload

5. Selecciona el archivo AAB

   Precaución

   Asegúrate de seleccionar el archivo AAB que generaste manualmente con Android Studio. Si este archivo no usa el mismo keystore que usarás para el Capgo build, el Capgo Native Build fallará.

6. Espera a que se suba el archivo AAB

7. Haz clic en Next

8. Corrige los errores

   En mi caso, en esta etapa veo este error

   

   Esto es porque aún no he verificado mi número de teléfono. Lo haré y continuaré con el tutorial.

9. Haz clic en Save and publish Esto publicará la app en el grupo de pruebas internas.

10. Confirmar la publicación

11. Asegúrate de que la app esté publicada

12. Obtén el nombre temporal de tu app

Aceptar la invitación al grupo de testing interno

Ahora que has subido la app al grupo de pruebas internas, puedes aceptar la invitación a ese grupo.

1. Ve a Test and release -> Testing -> Internal testing

2. Haz clic en Testers

3. Haz clic en Copy link

4. Envía el enlace a tu móvil, ábrelo en el navegador y haz clic en Accept

5. Confirma que la invitación se aceptó y haz clic en “descargar en Play Store”

6. Instalar la app

   1. Si ya habías instalado la app antes con Android Studio, haz clic en uninstall botón
   2. Haz clic en el install botón
   3. Abre la app y confirma que se descargó correctamente

   Precaución

   Si no ves la app en la Play Store, asegúrate de haber seleccionado la cuenta correcta en la Play Store.

Configurar Capgo Native Build (Android)

¡Ya estás listo para empezar la configuración de Capgo Native Build. Felicidades 🎉!

Requisito	Flag	Descripción	Obligatorio
Archivo Keystore	--keystore <path>	Ruta de tu .jks/.keystore archivo usado para firmar el APK/AAB.	Sí
Alias del Keystore	--keystore-alias <alias>	Nombre del alias de la clave dentro del keystore.	Sí
Contraseña de la clave del keystore	--keystore-key-password <password>	Contraseña de la clave. Si la clave y el almacén coinciden, solo necesitas una.	Consulta la nota de abajo
Contraseña del almacén Keystore	--keystore-store-password <password>	Contraseña del keystore. Si las contraseñas de la clave y del almacén coinciden, puedes indicar solo una.	Consulta la nota de abajo
Cuenta de servicio de Google Play	--play-config <path>	Archivo JSON de la cuenta de servicio para subir a la Play Store.	Sí

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

Nota

Si la contraseña de la key y del store son iguales, solo proporciona una: --keystore-key-password o --keystore-store-password.

Keystore, password del keystore, password de la clave del keystore, alias del keystore

Si has seguido las instrucciones de manual build, ya deberías tener la keystore generada. Si no has seguido las instrucciones, por favor síguelas para generar la keystore.

Cuenta de servicio de Google Play

Generar la Google Play service account es un proceso manual y complejo. Sin embargo, es necesario para subir tu app a Google Play. Ten en cuenta lo siguiente:

• Usted DEBES ser el propietario de la cuenta de desarrollador. De lo contrario, no podrás configurar la cuenta de servicio.
• Tendrás que crear un nuevo proyecto en Google Cloud (independiente de tu cuenta de Google Play)

Empecemos.

1. Ve a Consola de Google Cloud

2. Haz clic en el selector de proyectos

3. Si ya tienes un proyecto, selecciónalo. Si no, crea uno nuevo:

   Nota

   Las capturas de pantalla son ilustrativas; usa un nombre adecuado para tu proyecto.

   1. Haz clic en New project
   2. Nombra tu proyecto y haz clic en Create
   3. Asegúrate de estar en el proyecto correcto

4. Haz clic en la barra de búsqueda y busca service accounts y haz clic en él

5. Haz clic en Create service account

6. Completa el formulario de la cuenta de servicio y haz clic en Done

   1. Recomiendo poner como nombre Capgo Native Build Service Account
   2. Para el Service Account ID, recomiendo usar capgo-native-build-service-acc
   3. En cuanto a la descripción, no es obligatorio, pero recomiendo poner Allows Capgo Native Build to build and submit the app to the Play Store

   

7. Haz clic en la cuenta de servicio recién creada Ahora deberías ver la cuenta de servicio en la lista. Haz clic en ella.

   Nota

   Copia también esta dirección de correo, la necesitarás más adelante.

8. Haz clic en el Keys pestaña

9. Haz clic en Add Key y Create new key

10. Haz clic en JSON y Create

    Precaución

    Al hacer clic en Create se creará una nueva clave y se descargará el archivo JSON a tu máquina local.

    Debes guardar el archivo JSON en un lugar seguro. Este FALLARÁN se usará más adelante.

11. Descargar el archivo JSON El archivo JSON debería haberse descargado automáticamente. Puedes hacer clic en close para cerrar la ventana.

Conceder a la cuenta de servicio acceso a API de Play Store

La cuenta de servicio recién creada aún no tiene acceso a API de Play Store. Para otorgarlo, ve a la Play Store Console.

1. Ve a Google Play Console
2. Selecciona la cuenta de desarrollador correcta
3. Haz clic en Users and permissions
4. Haz clic en Invite new users
5. Copia el email de la cuenta de servicio
6. Ve a Account permissions y otorga los permisos mínimos necesarios:
   • En App permissions, otorga acceso a tu app.
   • En Releases, habilita Create, edit, and roll out releases.
   • Si tu flujo de trabajo usa Play App Signing, habilita el permiso de firma correspondiente.
   • Si no estás seguro, usa Admin solo durante la configuración y luego reduce los permisos.
7. Haz clic en Invite user
8. Confirmar la invitación
9. Confirma que el usuario ha sido invitado

Guardando las credenciales

Ya puedes guardar las credenciales y ejecutar tu primer build. Usa el siguiente comando para guardarlas:

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

Configuración de CI/CD (GitHub Actions)

Si ya has completado Keystore, password del keystore, password de la clave del keystore, alias del keystore y Cuenta de servicio de Google Play, ya tienes todo lo necesario para CI/CD. Esta sección solo explica cómo pasar esos valores como secrets de GitHub Actions y variables de entorno.

1) Convertir archivos de credenciales a base64 en una sola línea

# Android keystore (.jks or .keystore)
base64 -i ./path/to/keystore.jks | tr -d '\n' > keystore_base64.txt

# Google Play service account JSON
base64 -i ./play-store-service-account.json | tr -d '\n' > play_config_base64.txt

Consejo

Los secretos de GitHub deben ser valores de una sola línea. tr -d '\n' elimina los saltos de línea de la salida base64.

2) Crear secretos del repositorio

En GitHub > Repository > Settings > Secrets and variables > Actions, añade:

Nombre del secreto	Valor
CAPGO_TOKEN	Tu token de Capgo API
APP_ID	Tu ID de app Capgo (ejemplo: com.example.app)
ANDROID_KEYSTORE_FILE	Contenido de keystore_base64.txt
KEYSTORE_KEY_ALIAS	Alias de Keystore de Keystore, password del keystore, password de la clave del keystore, alias del keystore
KEYSTORE_KEY_PASSWORD	Contraseña de la clave del keystore
KEYSTORE_STORE_PASSWORD	Contraseña del almacén Keystore
PLAY_CONFIG_JSON	Contenido de play_config_base64.txt

Nota

Si las contraseñas de key y store son iguales, puedes indicar solo una de KEYSTORE_KEY_PASSWORD o KEYSTORE_STORE_PASSWORD.

3) Usa variables de entorno en tu workflow de GitHub Actions

.github/workflows/android-build.yml

name: Android Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  android-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request Android build with Capgo
        run: bunx @capgo/cli@latest build request ${{ secrets.APP_ID }} --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

Consejo

Con esta configuración, el CI envía las credenciales únicamente mediante variables de entorno. No necesitas subir los archivos de firma ni guardarlos como artifacts del workflow.

Ejecutar el build

¡Felicidades 🎉! Ya puedes ejecutar tu primer build.

Ejecuta:

bunx @capgo/cli@latest build request com.example.app --platform android

Y esto iniciará el proceso de build 🍾🥂

Envía la versión de Play a revisión

Por defecto, los builds de release para Android se suben a Google Play y pueden permanecer inactivos hasta que completes la versión en Play Console. Si tu release de CI debe enviar la versión de Play automáticamente, pasa --submit-to-store-review con un build de release:

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --android-track production \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales"

Precaución

En Android, --submit-to-store-review por defecto es el producción rastrear con release_status: completed cuando no defines un track. Este puede lanzarse al 100% de los usuarios. Pasa --android-track internal (o alpha / beta) — o establece PLAY_STORE_TRACK en CI — para mantener el release completado en un track de no producción. Usa --android-release-status / PLAY_STORE_RELEASE_STATUS cuando necesites un estado distinto a completed.

Esto requiere la misma configuración de la cuenta de servicio de Google Play que la ruta de upload normal (PLAY_CONFIG_JSON en CI o credenciales de Android guardadas localmente). --store-release-name se usa como el Google Play version_name. --store-release-notes es el changelog de fallback de Play, y cada --store-release-notes-locale "locale=notes" entry escribe un changelog de Play localizado para ese idioma. Capgo envía el release de Play como completed a menos que lo sobrescribas --android-release-status; si la publicación gestionada está activa en Play Console, Google puede esperar a que publiques manualmente tras la aprobación.

Continuar desde Android Builds

Si estás usando Builds de Android para planificar la automatización de CI/CD, conéctalo con CI/CD de Capgo para el flujo de trabajo del producto en Capgo CI/CD, Native Builds de Capgo para el flujo de trabajo del producto en Capgo Native Builds, Integraciones de Capgo para el flujo de trabajo del producto en Capgo Integraciones, Integración CI/CD para los detalles de implementación de CI/CD Integration, y Integración con GitHub Actions para los detalles de implementación de GitHub Actions Integration.