Construcción de Android

Construye 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-tutorial-de-compilación-nativa-de-aplicaciones

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 compilación manual

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

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

Construir 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. Haga clic en Build -> Generate Signed App Bundles / APKs

3. Seleccione Android App Bundle y haga clic en Next

Crear un Keystore

En este momento, 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 construido la aplicación. Para generarla, utilizaremos el método de interfaz gráfica 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. Haga clic en Create new

2. Rellene el camino del almacén de claves

   Cuidado

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

3. Establecer la contraseña del Key Store

   Nota

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

   Advertencia

   Esto GUARDE ESTO - se utilizará más adelante

4. Completa el resto del formulario

   1. Mantenga el Key Alias tal cual (key0)
   2. Rellene los detalles del certificado. He llenado con detalles falsos, pero usted debe llenarlo con sus propios detalles.

   

5. Haga clic en OK

Finalizando la construcción manual

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

2. Seleccione el release build variant y haga clic en Create

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

   1. Este popup indica que el build 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. Elija el nombre de la aplicación y el idioma

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

6. Aceptar los términos y condiciones

   Cuidado

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

7. Haga clic en Create

Crear 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 Play, 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 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. Vaya a internal testing Haga clic en Test and release -> Testing -> Internal testing

   

2. Haga clic en Testers

3. Haga clic en Create email list

4. Asigne un nombre a la lista de correos electrónicos

5. Agregar las direcciones de correo electrónico de los probadores

6. Presione Enter y haga clic en Save

7. Haz clic en Create group

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

Subir la aplicación al grupo de pruebas internas

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

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

2. Haz 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 de Capgo, la compilación nativa de 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 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. Envía el enlace a tu teléfono, abre el navegador y haz clic en Accept

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

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 Google Play, asegúrate de que hayas seleccionado la cuenta correcta en la Tienda de Google Play.

Configuración de Capgo de compilación nativa (Android)

Ahora estás listo para empezar la configuración de Capgo de compilación nativa. ¡Felicidades!

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

Clave de tienda, contraseña de la tienda, contraseña de la clave de la tienda, alias de la tienda

Si has seguido las instrucciones de compilación manual instrucciones de compilación manualDeberías tener generado el keystore ya. Si no has seguido las instrucciones, por favor sigue las para generar el keystore.

cuenta de servicio de Google Play

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. Ten en cuenta las siguientes cosas:

• Usted contexto: texto HTML de un fragmento más largo de la interfaz de usuario de Capgo (clave de página `you_definition`). Página/área: sitio web de marketing de Capgo. Rol: párrafo de marketing o legal largo. Visto en: página de advertencia.astro, página de devolución.astro. Clave de mensaje `you_definition` (Definición de usted). NECESITAS ser eldueño de la cuenta de desarrollador
• . De lo contrario, no podrás configurar la cuenta de servicio.

Necesitarás crear un nuevo proyecto de Google Cloud (separado de tu cuenta de Google Play)

1. Empecemos. Consola de Google Cloud

2. Haga clic en el selector de proyecto

3. Si ya tiene un proyecto, selecciónelo. De lo contrario, cree un nuevo proyecto:

   Nota

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

   1. Haga clic en New project
   2. Asigne un nombre a su proyecto y haga clic Create
   3. Asegúrese de estar en el proyecto correcto

4. Hagamos clic en la barra de búsqueda y busquemos service accounts y hagamos clic en ella

5. Hagamos clic en Create service account

6. Rellene el formulario para la cuenta de servicio y haga clic en Done

   1. Recomiendo establecer el nombre en Capgo Native Build Service Account
   2. Para el ID de la Cuenta de Servicio, recomiendo establecerlo en capgo-native-build-service-acc
   3. En cuanto a la descripción, no tiene que rellenarla, pero recomiendo llenarla con Allows Capgo Native Build to build and submit the app to the Play Store

   

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

   Nota

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

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án una nueva clave y descargará el archivo JSON en su máquina local.

    Necesita guardar el archivo JSON en un lugar seguro. Él SERÁ Descargar el archivo JSON El archivo JSON debería haberse descargado automáticamente. Puede hacer clic en

11. Descargar clave de Google Console close Otorgar acceso a la tienda de Play __CAPGO_KEEP_0__ al servicio de cuenta

Granting Play Store API access to the service account

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

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 conceder los permisos mínimos requeridos:
   • En App permissions, conceda 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 de firma relacionado.
   • 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

Guardando 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 CI/CD (GitHub Acciones)

Si ya completaste Keystore, contraseña de keystore, contraseña de clave de keystore, alias de keystore y cuenta de servicio de Google PlayYa tienes 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) 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 de 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

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

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

Notas

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

3) Use env vars in your GitHub Actions workflow

3) Utilice variables de entorno en su flujo de trabajo de github Actions

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

Copiar a portapapeles

Con esta configuración, 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.

Ejecutando la compilación

¡Felicidades! Ahora está listo para ejecutar su 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 liberación de Android suben a Google Play y pueden permanecer inactivas hasta que termine la versión en el Console de Play. Si su CI de liberación debe enviar la versión de Play automáticamente, pase --submit-to-store-review con una compilación de liberación:

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"

Cuidado

En Android, --submit-to-store-review por defecto es la producción seguir con release_status: completed cuando no se establezca un seguimiento. Esto puede ir en vivo a un 100% de usuarios. Pasar --android-track internal (o alpha / beta) — o establecer PLAY_STORE_TRACK en CI — para mantener la versión final en un seguimiento no de producción. Utilice --android-release-status / PLAY_STORE_RELEASE_STATUS cuando necesitas un estado diferente a completed.

Este 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 fallback, 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 superes --android-release-status; si se habilita la publicación gestionada en el Console de Play, Google puede esperar a que publique manualmente después de la aprobación.

Sigue adelante desde Android Builds

Si estás utilizando Android Builds planear la automatización de CI/CD, conectarla con Capgo automatización de CI/CD para el flujo de trabajo del producto en Capgo automatización de CI/CD, Capgo compilaciones nativas para el flujo de trabajo del producto en Capgo compilaciones nativas, Capgo integraciones for the product workflow in Capgo Integrations, para el flujo de trabajo del producto en __CAPGO_KEEP_0__ integraciones, Integración de CI/CD GitHub Actions Integration for the implementation detail in GitHub Actions Integration.