Construcción de Android

Construya y envíe 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-tutorial-de-compile-nativo-para-Android

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 construcción posterior de Capgo
• Crear un registro en la Consola de Tienda de Google Play

Construyendo la aplicación manualmente con Android Studio

Antes de que podamos 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. Hacer clic en Build -> Generate Signed App Bundles / APKs

3. Seleccionar Android App Bundle Hacer clic en Next

Crear un almacén de claves

Actualmente, te falta el archivo de keystore. Este archivo se utiliza para firmar tu aplicación, lo que permite a Google saber que es tú quien ha creado la aplicación. Para generarla, utilizaremos el método GUI proporcionado por Android Studio. También hay una forma de hacer esto con la línea de comandos, pero no la cubriremos en este tutorial.

1. Haz clic en Create new

2. Rellena la ruta del Key Store

   Precaución

   Esto DEBE SER GUARDADO - se utilizará más adelante

3. Establece la contraseña del Key Store

   Nota

   Recomiendo utilizar la misma contraseña para el Almacén de Claves y el Alias de Clave.

   Precaución

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

4. Completa el resto del formulario

   1. Mantén el Alias de Clave tal como está (key0)
   2. Completa los detalles del certificado. He llenado los detalles con información falsa, pero debes llenarlos con tus propios detalles.

   

5. Haga clic en OK

Finalizar la compilación manual

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

2. Seleccione el release varianta de compilación y haga clic en Create

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

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

4. Asegúrate de que puedas ver la compilación en el explorador de archivos

Crear la aplicación en el Console de Play Store

1. Vaya a Console 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 de pago o gratuita

6. Aceptar los términos y condiciones

   Precaución

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

7. Haz clic en Create

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 un lanzamiento real.

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

1. Ir a internal testing Hacer clic en Test and release -> Testing -> Internal testing

   

2. Haz clic en Testers

3. Haz clic en Create email list

4. nombrar la lista de correos electrónicos

5. Add the email addresses of the testers

6. Presiona Enter y haz 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 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 nativa Capgo 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 no he verificado mi número de teléfono todavía. 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 ha subido la aplicación al grupo de pruebas internas, puede aceptar la invitación al grupo de pruebas internas.

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

2. Haga clic en Testers

3. Haga clic en Copy link

4. Envíe el enlace a su teléfono, abra en el navegador y haga clic en Accept

5. Confirme que la invitación ha sido aceptada y haga clic en “descárguelo en la Tienda de Play”

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

   Si no ves la aplicación en la Tienda de Juegos, asegúrate de que hayas seleccionado la cuenta correcta en la Tienda de Juegos.

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

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

Requisito	Bandera	Descripción	Requerido
Archivo de llave de fábrica	--keystore <path>	Ruta a tu archivo .jks/.keystore utilizado para firmar el APK/AAB.	Sí
Nombre de alias del certificado	--keystore-alias <alias>	Nombre de alias de la clave dentro del keystore.	Sí
Ver la nota debajo	--keystore-key-password <password>	Contraseña para la clave. Si las contraseñas de la clave y el almacén coinciden, solo debes proporcionar una.	Nombre de cuenta de servicios de Google Play
Contraseña del almacén de claves	--keystore-store-password <password>	Contraseña para el keystore. Si las contraseñas de la clave y el almacén coinciden, solo debes proporcionar una.	Nombre de cuenta de servicios de Google Play
Contraseña del almacén de certificados	--play-config <path>	Nombre de cuenta de servicios de Google Play	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 la tienda son idénticas, proporcione solo una de ellas. --keystore-key-password or --keystore-store-password.

Keystore, keystore password, keystore key password, keystore alias

Si has seguido los pasos Instrucciones de compilación manualTiene que haber generado ya el keystore. Si no ha seguido las instrucciones, por favor, síguelas para generar el keystore.

servicio de cuenta de Google Play

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

• Usted NEED NECESITA dueño de la cuenta del DesarrolladorDe lo contrario, no podrás configurar la cuenta de servicio.
• Necesitará crear un nuevo proyecto de Google Cloud (separado de su cuenta de Google Play).

Comencemos.

1. Comencemos. Google Cloud Console

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. Haz clic en la barra de búsqueda y busca por service accounts haz clic en ella

5. Haz clic en Create service account

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

   1. Recomiendo que establezcas el nombre en 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 es necesario 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

   Copia también la dirección de correo electrónico, 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

    Cuidado

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

    Necesitas guardar el archivo JSON en un lugar seguro. Él SERÁ usado más tarde.

11. Descargar el archivo JSON El archivo JSON debería haberse descargado automáticamente. Puedes hacer clic en close 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 concederle acceso, diríjase a la Consola del Play Store.

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

Almacenando las credenciales

Ahora está listo para guardar las credenciales y ejecutar su primer build. Puede 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 CI/CD (GitHub Acciones)

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

1) Convierta 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) Cree secretos de repositorio

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

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

Notas

Si las claves y contraseñas de almacenamiento son iguales, puede proporcionar solo una de KEYSTORE_KEY_PASSWORD o KEYSTORE_STORE_PASSWORD.

3) Use env vars in your GitHub Actions workflow

.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 }}

Tip

Con esta configuración, CI envía credenciales a través de variables de entorno solo. No es necesario que comitas archivos de firma ni los subas como artefactos de flujo de trabajo.

Ejecutando 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

Presentar la versión de Play para revisión

Por defecto, las compilaciones de lanzamiento de Android suben a Google Play y pueden permanecer inactivas hasta que finalices la versión en la consola de Play. Si tu CI debe presentar 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 \
  --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 la producción se sigue con release_status: completed cuando no se establece un seguimiento. Puede ir en vivo a 100% de usuarios. Pasar --android-track internal o alpha / betaestablecer PLAY_STORE_TRACK en CI — para mantener la versión final en una pista no de producción. Utilizar --android-release-status / PLAY_STORE_RELEASE_STATUS cuando necesite un estado diferente a completed.

Requiere la misma configuración de cuenta de servicios de Google Play que el camino de carga normal ("PLAY_CONFIG_JSON en CI o credenciales de Android guardadas localmente). --store-release-name se utiliza como el Google Play version_name. --store-release-notes es el cambio de Play de respaldo, y cada --store-release-notes-locale "locale=notes" entrada escribe un cambio de Play localizado para ese idioma. Capgo envía la versión de Play como completed a menos que se sobrescriba --android-release-status; si se habilita la publicación administrada en el Console de Play, Google puede esperar a su publicación manual después de la aprobación.

Sigue adelante desde Android Builds

Si está utilizando Construcción de Android para planificar la automatización de CI/CD, conectéalo con Capgo CI/CD para el flujo de trabajo del producto en Capgo CI/CD Capgo Compilaciones Nativas para el flujo de trabajo del producto en Capgo Compilaciones Nativas Capgo Integraciones para el flujo de trabajo del producto en Capgo Integraciones Integración CI/CD para el detalle de implementación en Integración CI/CD, y GitHub Integración de Acciones para el detalle de implementación en GitHub Integración de Acciones