Compilaciones de Android

Desarrolla y envía aplicaciones Android a Google Play Store utilizando la infraestructura dedicada de Capgo.

Lo que aprenderás

• Aprenderás a subir tu aplicación a través de Capgo Native build
• Aprenderás a configurar las credenciales para Capgo Native Build

Requisitos previos

• Necesitas tener una cuenta de desarrollador de Google activa
• Necesitas tener instalado Android Studio
• Tu aplicación debe poder compilar con éxito con Android Studio

Nota

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

Recomendado: onboarding automatizado

No necesita hacer nada de esto a mano. El onboarding de Capgo crea y configura sus credenciales de firma de Android (keystore + cuenta de servicio de Google Play) por usted — este es el camino recomendado:

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

La guía manual a continuación solo es para aquellos que prefieren configurar las credenciales ellos mismos, o quieren entender exactamente qué hace Capgo debajo de la cubierta.

La primera construcción manual

Antes de que podamos empezar a pensar en construir la aplicación con Capgo, debemos configurarla primero, y hacer una primera construcción de Android a mano. Hay algunas ventajas en hacer una construcción manual primero:

• Preparará las credenciales para la posterior construcción de Capgo
• Crear un registro en la Consola de Tienda de Juegos

Construir la aplicación manualmente con Android Studio

Antes de poder empezar a construir la aplicación con Capgo, necesitamos construir la aplicación manualmente con Android Studio.

1. Abrir Android Studio

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

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

3. Seleccionar Android App Bundle y haga clic en Next

Crear un Keystore

Actualmente, te falta el archivo de keystore. Este archivo se utiliza para firmar tu aplicación, lo que le permite a Google saber que es tú quien construyó la aplicación.

1. Para generar este archivo, utilizaremos el método GUI proporcionado por Android Studio. Create new

2. Haz clic en

   Rellena la ruta del Key Store en Android Studio

   Cuidado Cuidado Esto

3. DEBE SER GUARDADO

   Nota

   Recomiendo usar la misma contraseña para el Almacen de Claves y el Alias de Clave.

   Cuidado

   Esta DEBE SER GUARDADO - se utilizará más tarde

4. Rellene el resto del formulario

   1. Mantenga el Alias de Clave tal como está (key0)
   2. Rellene los detalles del certificado. He llenado los detalles con información falsa, pero debe llenarlos con sus propios detalles.

   

5. Haz clic en OK

Finalizar la construcción manual

1. Asegúrate de que todos los detalles del keystore estén rellenados correctamente y haz clic en Next

2. Selecciona el release variant de construcción y haz clic en Create

3. Después de que la construcción tenga éxito, deberías ver la siguiente pantalla

   1. Este popup indica que la construcción tuvo éxito.
   2. Haga clic en el locate botón - esto abrirá el explorador de archivos y deberías ver el build allí.

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

Crear la aplicación en la Consola de Play Store

1. Vaya a Consola de Google Play

2. Seleccione la cuenta de desarrollador correcta

3. Haga clic en Create app

4. Elige el nombre de la aplicación y el idioma

5. Selecciona la categoría de la aplicación y si es gratuita o de pago

6. Aceptar los términos y condiciones

   Cuidado

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

7. Haz clic en Create

Está creando el grupo de pruebas internas

Ahora que has creado la aplicación, puedes crear un grupo de pruebas internas. Dado que no publicaré la aplicación para todos en la Tienda de Juegos de Google, necesitaré crear un grupo de pruebas internas.

Nota

La prueba interna sigue siendo la forma más rápida de probar tu build distribuido en Play antes de una lanzamiento real.

Si tu cuenta de desarrollador es una cuenta personal creada después del 13 de noviembre de 2023, la prueba interna no reemplaza el requisito de prueba cerrada para acceso a producción. Aún necesitarás una prueba cerrada con al menos 12 participantes que hayan optado por participar durante 14 días consecutivos antes de la producción. Vaya a Haga clic en

1. Consola de pruebas interna de Google Play internal testing Haga clic en Test and release -> Testing -> Internal testing

   

2. Crear un grupo de pruebas internas Testers

3. Haga clic en Create email list

4. Denomine a la lista de correos electrónicos

5. Agregar direcciones de correo electrónico de las pruebas

6. Pulsar Enter y haga clic en Save

7. Haga clic en Create group

8. Verifique que la nueva lista esté seleccionada y haga clic en Save

Subir la aplicación al grupo de pruebas internas

Ahora que ha creado el grupo de pruebas internas, puede subir la aplicación al grupo de pruebas internas.

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

2. Haga clic en el Releases botón

3. Haga clic en Create new release

4. Haga clic en Upload

5. Seleccione el archivo AAB

   Cuidado

   Asegúrese de seleccionar el archivo AAB que creó manualmente con Android Studio. Si este archivo no utiliza el mismo keystore que el que utilizará para la compilación Capgo, la compilación Capgo Nativa fallará.

6. Espere a que se suba el archivo AAB

7. Haga clic en Next

8. Corrija los errores

   Personalmente, 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. Haga clic en Save and publish Esto publicará la aplicación en el grupo de pruebas internas.

10. Confirmar la publicación

11. Asegúrese de que la aplicación esté publicada

12. Obtenga el nombre temporal de la aplicación

Aceptar la invitación al grupo de pruebas internas

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

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

2. Hacer clic en Testers

3. Hacer clic en Copy link

4. Enviar el enlace a tu teléfono, abrirlo en el navegador y hacer clic en Accept

5. Confirmar que la invitación ha sido aceptada y hacer clic en “descargarlo en Play Store”

6. Instale la aplicación

   1. Si había instalado la aplicación antes de usar Android Studio, haga clic en el uninstall botón
   2. Haga clic en el install botón
   3. Abra la aplicación y confirme que se ha descargado correctamente

   Cuidado

   If no ves la aplicación en la Tienda de Juegos, asegúrese de que ha seleccionado la cuenta correcta en la Tienda de Juegos.

Configuración de Capgo Compilación Nativa (Android)

Ahora, está listo para iniciar la configuración de Capgo Compilación Nativa. ¡Felicidades!

Requisito	Bandera	Descripción	Requerido
Archivo de llave de keystore	--keystore <path>	Ruta a su .jks/.keystore archivo utilizado para firmar el APK/AAB.	Sí
Alias del keystore	--keystore-alias <alias>	Nombre del alias del key dentro del keystore.	Sí
Contraseña de la clave del keystore	--keystore-key-password <password>	Contraseña de la clave. Si las contraseñas de la clave y el almacén coinciden, solo necesita proporcionar una.	Mire la nota debajo
Contraseña del almacén del keystore	--keystore-store-password <password>	Contraseña del keystore. Si las contraseñas de la clave y el almacén coinciden, solo necesita proporcionar una.	Mire la nota debajo
Cuenta de servicio de Google Play	--play-config <path>	Archivo de servicio JSON para subidas a 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 las contraseñas de la clave y el almacén son idénticas, proporciona solo una de ellas --keystore-key-password o --keystore-store-password.

Keystore, contraseña del keystore, contraseña de la clave del keystore, alias del keystore

Si has seguido las instrucciones de compilación manual, deberías tener el keystore ya generado. Si no has seguido las instrucciones, por favor sigue las instrucciones para generar el keystore. Cuenta de servicio de Google PlaySi la clave y el almacén de contraseñas tienen la misma contraseña, proporciona solo una de ellas

Keystore, contraseña del keystore, contraseña de la clave del keystore, alias del keystore

La generación de la cuenta de servicio de Google Play es un proceso manual y complejo. Sin embargo, es necesario para subir tu aplicación a Google Play. Por favor, ten en cuenta las siguientes cosas:

• Tú DEBES ser el dueño de la cuenta de desarrollador. De lo contrario, no podrás configurar la cuenta de servicio.
• Deberás crear un nuevo proyecto de Google Cloud (separado de tu cuenta de Google Play)

Vamos a empezar.

1. Ve a Consola de Google Cloud

2. Haz clic en el selector de proyecto

3. Si ya tienes un proyecto, seleccionarlo. De lo contrario, crea un nuevo proyecto:

   Nota

   Las capturas de pantalla a continuación son ilustrativas - utiliza un nombre apropiado para tu proyecto.

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

4. Vamos a hacer clic en la barra de búsqueda y buscar service accounts y haz clic en él

5. Vamos a hacer clic en Create service account

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

   1. Recomiendo que establezcas el nombre a Capgo Native Build Service Account
   2. Para el ID de la Cuenta de Servicio, recomiendo que lo establezcas en capgo-native-build-service-acc
   3. En cuanto a la descripción, no tienes que rellenarla, pero recomiendo que la llenes con 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 recién creada en la lista. Haz clic en ella.

   Nota

   Copie esta dirección de correo electrónico también, la necesitará más tarde.

8. Haga clic en el Keys pestaña

9. Haga clic en Add Key y Create new key

10. Haga clic en JSON y Create

    Cuidado

    Haciendo clic en Create creará una nueva clave y descargará el archivo JSON a su máquina local.

    Necesita guardar el archivo JSON en un lugar seguro. Es SERÁ utilizado más tarde.

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

Otorgar acceso a la cuenta de servicio de Play Store API

La cuenta de servicio recién creada no tiene acceso aún al Play Store API. Para otorgárselo, diríjase a la consola de Play Store.

1. Ir a Consola de Google Play
2. Seleccionar la cuenta de desarrollador correcta
3. Hacer clic en Users and permissions
4. Hacer clic en Invite new users
5. Copiar la dirección de correo electrónico de la cuenta de servicio
6. Ir a Account permissions y conceder los permisos mínimos requeridos:
   • En App permissions, otorgar acceso a tu aplicación.
   • En Releases, habilitar Create, edit, and roll out releases.
   • Si tu flujo de trabajo utiliza Play App Signing, habilita la correspondiente permiso de firma.
   • Si no estás seguro, utiliza Admin solo durante la configuración, luego reduce las permisos después.
7. Haz clic en Invite user
8. Confirmar la invitación
9. Confirma que el usuario ha sido invitado

Guardar las credenciales

Ahora estás listo para guardar las credenciales y ejecutar tu primer build. Puedes guardar las credenciales utilizando el siguiente comando:

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 Acciones)

Si ya has completado Keystore, contraseña de keystore, contraseña de clave de keystore, alias de keystore y cuenta de servicios de Google Play, ya tienes todo lo necesario para CI/CD. Esta sección solo cubre cómo pasar esos valores como secretos de GitHub de Actions y variables de entorno.

1) Convierte archivos de credenciales a base64 de 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 GitHub deben ser valores de una sola línea. tr -d '\n' elimina saltos de línea del resultado de base64.

2) Crea secretos de repositorio

In GitHub > Repository > Settings > Secrets and variables > Actions, agregar:

Nombre secreto	Valor
CAPGO_TOKEN	Su Capgo API token
APP_ID	Su Capgo ID de aplicación (por ejemplo: com.example.app)
ANDROID_KEYSTORE_FILE	Contenido de keystore_base64.txt
KEYSTORE_KEY_ALIAS	Alias del almacén de claves desde Almacén de claves, contraseña del almacén de claves, contraseña de la clave del almacén de claves, alias del almacén de claves
KEYSTORE_KEY_PASSWORD	Contraseña de la clave del almacén de claves
KEYSTORE_STORE_PASSWORD	Contraseña del almacén de claves
PLAY_CONFIG_JSON	Contenido de play_config_base64.txt

Nota

Si las contraseñas de la clave y el almacenamiento son las mismas, puede proporcionar solo una de ellas KEYSTORE_KEY_PASSWORD o KEYSTORE_STORE_PASSWORD.

3) Utilice variables de entorno en su flujo de trabajo de GitHub de Acciones

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, la CI envía credenciales a través de variables de entorno solo. No necesita comprometer archivos de firma ni subirlos como artefactos de flujo de trabajo.

Ejecutar la compilación

Felicidades! 🎉 Ahora estás listo para ejecutar tu primera compilación.

Ejecutar:

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

Y esto iniciará el proceso de compilación 🍾🥂

Enviar la versión de Play para revisión

Por defecto, las compilaciones de lanzamiento de Android se suben a Google Play y pueden permanecer inactivas hasta que finalices la versión en la consola de Play. Si tu CI debe enviar la versión de Play automáticamente, pasa --submit-to-store-review con una compilación de lanzamiento:

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --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"

Requiere la misma configuración de cuenta de servicios de Google Play que la ruta de carga normal (PLAY_CONFIG_JSON en CI o credenciales de Android guardadas localmente). --store-release-name se utiliza como nombre de lanzamiento de Google Play. --store-release-notes es el changelog de Play por defecto, y cada --store-release-notes-locale "locale=notes" entrada escribe un changelog de Play localizado para ese idioma. Capgo envía el lanzamiento de Play como completed; si se habilita la publicación administrada en el Console de Play, Google puede seguir esperando a su publicación manual después de la aprobación.

Sigue desde Android Builds

Si está utilizando Android Builds para planificar la automatización de CI/CD, conecte con Capgo CI/CD para el flujo de trabajo del producto en Capgo CI/CD, Capgo Construcción Nativa para el flujo de trabajo del producto en Capgo Construcción Nativa, Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones, Integración de CI/CD para el detalle de implementación en Integración de CI/CD, y GitHub Integración de Acciones para el detalle de implementación en GitHub Integración de Acciones.