Construcción de iOS

Construye y envía aplicaciones iOS a TestFlight y la Tienda de Aplicaciones utilizando la infraestructura Mac 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 los certificados para Capgo Native Build

Requisitos previos

• Una cuenta de Capgo (un período de prueba gratuito es suficiente para empezar)
• Tu aplicación ya registrada en Capgo (corre bunx @capgo/cli@latest app add si no)
• A un computador Mac con Xcode instalado (es posible configurar la compilación en una máquina Linux/Windows, pero aún no está documentado)
• Una cuenta de desarrollador Apple válida (99€/año) (Debes tener derechos de administrador o propietario en la cuenta de desarrollador Apple)
• Tu aplicación debe poder compilar con éxito mediante Xcode
• Una aplicación Capacitor
• Un icono configurado para la aplicación. Las aplicaciones sin icono no pueden subirse a la Tienda de Aplicaciones

Nota

Usaré la siguiente aplicación para el tutorial: https://github.com/Cap-go/capgo-tutorial-de-compilación-nativa

Antes de empezar en los portales de Apple

Antes de configurar certificados o desencadenar tu primera subida de prueba de TestFlight, asegúrate de que la cuenta y el equipo de Apple estén listos:

• Activar la autenticación en dos factores para la cuenta de Apple utilizada para la inscripción
• Elige el tipo de membresía correcto:
  • Individual / Propietario único: su nombre personal legal se convierte en el nombre del vendedor en la Tienda de Aplicaciones
  • Organización: requiere una entidad legal, un número D-U-N-S, un sitio web de empresa público, un correo electrónico de trabajo en el dominio de la empresa y una persona con autoridad para vincular a la organización a los acuerdos de Apple
• Utilice una cuenta que pueda acceder a ambos Apple Developer y App Store Connect para certificados, registros de aplicaciones, API claves y TestFlight
• Establezca su ID de paquete final lo antes posible. Cambiarlo más tarde suele significar volver a configurar la Tienda de Aplicaciones
• Planifique estos elementos de App Store Connect antes de la revisión de la aplicación: URL de soporte, URL de política de privacidad, calificación de edad, capturas de pantalla, cumplimiento de exportación y detalles de contacto para la revisión de la aplicación

Nota

Referencias oficiales útiles:

• Únete al programa de desarrolladores de Apple
• Envía tus aplicaciones y juegos
• Información de versión de la plataforma en App Store Connect

Advertencia

Apple actualiza regularmente su requisito mínimo de SDK. A partir del 28 de abril de 2026, Las aplicaciones de iPhone y iPad subidas a App Store Connect deben ser construidas con el IOS y iPadOS 26 SDK o posterior.

Recomendado: onboarding automatizado

No necesita hacer nada de esto a mano. El onboarding de Capgo crea y configura sus credenciales de firma de iOS (certificado de distribución + perfil de configuración) por usted — este es el camino recomendado:

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

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 configurarlo primero, y hacer una primera construcción de TestFlight a mano. Hay algunas ventajas en hacer una construcción manual primero:

• Configurará el certificado de distribución en su máquina local
• Crearán el registro de la Tienda de Mac si aún no lo han hecho
• Podrá resolver cualquier problema con el proceso de compilación relacionado con su aplicación code

Antes de comenzar, debe tener instalado el certificado de distribución en su máquina local. Esto es un poco complicado, pero lo explicaré a continuación.

Configuración del certificado de distribución

1. Abrir Xcode

2. Haga clic en Xcode -> Settings... Alternativamente, puede utilizar la atajada Cmd + ,

   

3. Ir a Accounts

4. Encuentre la cuenta de Apple que se ha agregado a la cuenta del desarrollador de Apple

5. Encuentre el equipo que utilizará para desplegar la aplicación

6. Haga clic en el Manage Certificates... botón

7. Asegúrese de que pueda ver el certificado de distribución en la lista

8. Si no lo ve, necesita crear un nuevo certificado

   Notas

   Apple limita el número de certificados de distribución que puede tener a 3. Si tiene más de 3 certificados, necesita eliminar uno para crear uno nuevo. No cubriré eso en este tutorial

   1. Haga clic en el + botón y luego en Apple Distribution
   2. El certificado se creará automáticamente. Puedes verlo en la lista. Mira el paso anterior para confirmar que lo ves.

Ahora que tienes instalado el certificado de distribución, puedes comenzar el proceso de compilación.

Compilación manual para TestFlight

1. Abrir la aplicación en Xcode

   Ejecutar bunx cap open ios para abrir la aplicación en Xcode.

2. Encuentra y haz clic en el archive botón

   En la barra de herramientas de Xcode, encuentra y haz clic en el product -> archive botón.

   

3. Espera a que se complete la compilación

4. Haz clic en el Distribute App botón

   

5. Selecciona TestFlight Internal Only como método de distribución y haz clic en Distribute botón

   

6. Configura el registro de la aplicación

   Rellena los siguientes campos:

   1. Nombre: El nombre de tu aplicación - visible en la Tienda de Mac
   2. SKU - el código SKU de tu aplicación - se utiliza para identificar tu aplicación en la Tienda de Mac
   3. El idioma principal - el idioma principal de tu aplicación

   Luego, haz clic en el next botón

   

7. Si falla la creación del registro de la aplicación, intenta cerrar la ventana y intenta archivar la aplicación de nuevo.

8. Espera a que la subida se complete

9. Si todo salió bien, deberías ver la siguiente pantalla

10. Haz clic en el Done botón

Puede que piense que todo está bien ahora y que podrá ver su aplicación en TestFlight ahora, pero hay un par de cosas más que terminar:

1. Agregarse a TestFlight
2. Completar la conformidad de exportación para que la compilación se vuelva testable
3. Rellenar los metadatos de App Store Connect obligatorios, como su URL de soporte, la URL de política de privacidad y la calificación de edad
4. Preparar capturas de pantalla que coincidan con los dispositivos que realmente soporta
5. Agregar los detalles de contacto de la revisión de la aplicación y cualquier credencial de prueba antes de la presentación de producción

Vamos a empezar con la primera:

Agregarse a TestFlight

1. Ir a la Conexión de Tienda de App página

2. Iniciar sesión con tu cuenta de desarrollador de Apple

3. Selecciona el equipo que utilizaste cuando creaste el registro de la aplicación. Si solo tienes una cuenta de desarrollador, puedes saltarte este paso.

4. Haga clic en el Apps botón

5. Encuentra la aplicación que creaste en el paso anterior y haga clic en ella

6. Haga clic en el TestFlight botón

7. Haz clic en el Internal Testers plus botón

8. Crear un nuevo grupo

   Me gusta llamar al grupo “internos”. Puedes llamarlo como quieras.

   

9. Haz clic en Invite testers botón

10. Agrega tu nombre a la lista

    Encuentra tu nombre en la lista y selecciona la casilla al lado de tu nombre. (Puede que debas refrescar la página para ver tu nombre) Luego, haz clic en el Add botón.

    

11. Verifica que estás agregado al grupo

    Ahora deberías verte en el grupo.

    

¡Felicidades! Has agregado a ti mismo a TestFlight. Ahora solo queda una cosa más que debes hacer antes de que puedas configurar Capgo Native Build.

Configuración de la información de conformidad

Ahora debes prometer a Apple que tu aplicación no utiliza ninguna criptografía no estándar (como un algoritmo personalizado). Si tu aplicación utiliza alguna criptografía no estándar, te recomiendo leer la documentación de Apple sobre cómo manejar esto. Hay dos formas de hacer esto:

1. Puedes hacer esto manualmente cada vez que construyas tu aplicación.
2. Puedes configurar tu archivo plist para establecer automáticamente este valor false.

Comencemos con el primero:

1. Sigue todos los pasos de la sección anterior para encontrar la sección TestFlight en App Store Connect

2. Haga clic en Builds -> iOS

3. Encuentre la construcción con información de conformidad faltante y haga clic en Manage

4. Seleccione la opción que mejor describa su aplicación

   Para mí, esto es nonePero puede ser diferente para ti. Después, haga clic en guardar

   

5. Su aplicación debería decir ahora ready to test

   

As for the second one, here are the steps:

1. Abra el Info.plist archivo

2. Agregue la siguiente clave:

   <key>ITSAppUsesNonExemptEncryption</key>
   <false/>

3. Guardar el archivo

Nota

Aquí se encuentra la documentación oficial de Apple sobre cómo informar a Apple sobre su cumplimiento con las regulaciones de exportación de cifrado.

Instalar la aplicación TestFlight y aceptar la invitación

Now, you are almost ready to test your app in TestFlight. Before, you need to do the following things: ALMOST Listo para probar su aplicación en TestFlight. Antes, necesita hacer las siguientes cosas:

1. Descargar la aplicación TestFlight de la Tienda de Aplicaciones en su dispositivo iOS/iPadOS
2. Aceptar la invitación para probar su aplicación

No entraré en detalles sobre cómo instalar la aplicación TestFlight en su dispositivo. Si no está seguro de cómo instalar una aplicación, Google tiene algunas grandes guías sobre cómo hacerlo.

Para aceptar la invitación, recibirá un correo electrónico de Apple con un enlace para aceptar la invitación.

1. Abra el correo electrónico de Apple con el enlace para aceptar la invitación

2. Haga clic en View in TestFlight botón

3. Haz clic en el Install botón

4. Instala la aplicación en tu dispositivo

   Si has instalado la aplicación previamente utilizando Xcode, es posible que veas la siguiente pantalla. Por favor, haz clic en el install botón.

5. Espera a que se instale la aplicación

6. Haz clic en el Open botón y haz clic en él

Felicidades 🎉 Has aceptado la invitación para probar tu aplicación en TestFlight. Ahora, puedes configurar Capgo Native Build para compilar y enviar tu aplicación a TestFlight.

Configurando Capgo Compilación Nativa

Hay algunas cosas que debes configurar en Capgo Compilación Nativa para poder compilar y enviar tu aplicación a TestFlight. Aquí tienes una lista de las cosas que pasarás al Capgo CLI:

Parámetro	Descripción
--platform	La plataforma para compilar (ios)
--apple-team-id	Tu ID de equipo de desarrollador de Apple (encontrado en Portal de Desarrollador de Apple)
--apple-key	Ruta a tu archivo API de llave de App Store Connect (.p8 archivo)
--apple-key-id	La clave ID de tu llave de App Store Connect API
--apple-issuer-id	Tu ID de emisor de App Store Connect
--certificate	Ruta a tu certificado de distribución (.p12 archivo)
--ios-provisioning-profile	Configuración de perfil de provisión (bundleId=path o solo ruta para un perfil único)

Ejemplo de comando:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile '/path/to/profile.mobileprovision'

ID de equipo

Comencemos con el ID de equipo. Encontrarlo es bastante sencillo.

1. Ir a Cuenta de desarrollador de Apple y desplázate hacia abajo

2. Encuentra la Team ID

   

Apple key, ID de clave de Apple y ID de emisor de Apple

Ahora, pasemos a la clave de Apple.

macOS: deja que Capgo cree esta clave para ti

En macOS, capgo build init puedes crear esta clave de App Store Connect API para ti. Selecciona “No — crea una para mí” y una ventana guiada se abre en App Store Connect, te guía a través de cada paso y captura automáticamente la clave, el ID de clave y el ID de emisor — sin copiar ni pegar. Los pasos manuales a continuación son la alternativa (y el camino en Windows o Linux).

1. Ir a Página de acceso de usuario y acceso a App Store Connect

   Nota

   Para mí, el enlace a veces no funciona. Recarga la página si no funciona para ti.

2. Selecciona el equipo correcto en el menú desplegable

   1. Haz clic en tu nombre en la esquina superior derecha
   2. Haz clic en el equipo que deseas utilizar

3. Haz clic en el Integrations botón

4. Encuentra el issuer

   Advertencia

   Esta DEBE SER GUARDADO - lo necesitarás más tarde

   Haga clic en el copy botón para copiar el emisor

5. Haga clic en el botón de más

6. Establezca el nombre de la clave y establezca el acceso a App manager y haz clic en el Generate botón

7. Guardar el ID de clave

   Advertencia

   Esto DEBE SER GUARDADO - lo necesitarás más tarde

   

8. Descargar la clave

   Cuidado

   Este ES PARA GUARDAR - lo necesitarás más tarde

   Peligro

   NO COMPARTAS LA LLAVE CON NADIE - ÚSALA SOLO EN EL CAPGO CLI

   

   

Felicidades 🎉 Has creado la clave de Apple, el ID de clave de Apple y el ID de emisor de Apple.

Certificado

Ahora, está listo para exportar el certificado. Como recuerda, uno de los primeros pasos de esta guía fue configurar el certificado de distribución.

Sin embargo, Apple en su infinita sabiduría, decidió que la forma en que exporta el certificado es bastante diferente de la forma en que los crea 😂 Vamos a ver cómo configurarlo:

1. Abra Keychain Access

   1. Haga clic Command + Space para abrir la barra de búsqueda
   2. Busque Keychain Access
   3. Haga clic en el Keychain Access la

2. Seleccione la login y haga clic en el My Certificates botón

3. Encuentre su certificado en la lista

   El certificado debería llamarse Apple Distribution: [Your Name/Company] (your team ID)

4. Haga clic con el botón derecho en el certificado y seleccione Export

5. Guardar el certificado como un .p12 archivo

   Advertencia

   Esto DEBE SER GUARDADO - Necesitarás para más adelante

   1. Verifica que selecciones un buen nombre para el archivo de certificado
   2. Asegúrate de que el formato del archivo esté configurado en Personal Information Exchange (.p12)
   3. Haz clic en el Save botón

   

6. Cuando se te pregunte por la contraseña, puedes elegir:

   • Saltarte la contraseña (recomendado por simplicidad): Haz clic OK sin ingresar una contraseña
   • Establecer una contraseña: Si prefieres proteger tu certificado con una contraseña, puedes establecerla aquí. Los archivos protegidos por contraseña están completamente soportados por el __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - solo proporciona la contraseña utilizando la .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password option when running configuration command.

   

7. Cuando se le pregunte por la "contraseña de la llave de cadena de inicio de sesión", proporcione la contraseña que utiliza para iniciar sesión en su Mac

   Proporcione la contraseña que utiliza para iniciar sesión en su Mac. Luego, haga clic en el Allow botón.

   

Felicidades 🎉 Ha exportado el certificado.

Perfil de provisión

Sección titulada "Perfil de provisión"

1. Ahora, está listo para exportar el perfil de provisión. Le prometo, esto es la última cosa que necesitará obtener de Apple. Ir a

2. Perfiles de desarrollador de Apple (Apple Developer Profiles) no translated as it is a brand name and should be kept as is. Select the correct team in the dropdown (Seleccionar el equipo correcto en el menú desplegable) no translated as it is a brand name and should be kept as is. I have kept the original text for the last two items as they are brand names and should be kept as is. If you want to translate them, please let me know.

   1. Haz clic en tu nombre en la esquina superior derecha
   2. Haz clic en el equipo que deseas utilizar

3. Asegúrate de estar en la página correcta Debería verse así, si no haz clic en profiles in el menú lateral

   

4. Haz clic en el + botón

5. Selecciona el tipo de perfil Selecciona App Store Connect y haz clic en el Continue botón

   

6. Seleccionar la aplicación que deseas construir

   Encuentra tu aplicación en el menú desplegable y haz clic en el Continue botón

   

7. Seleccionar el certificado de distribución correcto

   Seleccionar el certificado que exportaste en el paso anterior y haz clic en el Continue botón

   

   Si no estás seguro de qué certificado seleccionar, vuelve a Keychain Access y encuentra el certificado que exportaste. Luego mira la fecha de vencimiento.

   

8. Nombrar el perfil

   Délele un nombre de perfil y haz clic en el Generate botón

   Consejo

   El nombre de perfil se extrae automáticamente por el Capgo CLI — no necesitas recordarlo.

   

9. Descargar el perfil

   Haz clic en el Download botón para descargar el perfil

   Advertencia

   Este archivo ES DEBE SER GUARDADO - lo necesitarás más tarde

   

Felicidades 🎉 Ahora tienes todo lo que necesitas para configurar Capgo Native Build.

Advertencia

¡Nunca cometas los credenciales que acabas de crear a tu repositorio! Manténlos a salvo! 🔒

Ejecutando el comando de configuración

¡Lo has hecho! Ahora tienes todo lo que necesitas para configurar Capgo Native Build.

El comando que necesitarás ejecutar es:

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id UVTJ336J2D \
  --apple-key ./capgo-tutorial/AuthKey_66FGQZB566.p8 \
  --apple-key-id 66FGQZB566 \
  --apple-issuer-id 0cd4db4a-5598-45b8-9d32-75cdf127d005 \
  --certificate ./capgo-tutorial/capgo-build-tutorial-certificate.p12 \
  --ios-provisioning-profile ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision

Sustituir valores de reemplazo

Sustituye los valores de reemplazo anteriores con tus credenciales reales recopiladas en los pasos anteriores:

• --apple-team-id: Tu ID de equipo de Apple
• --apple-key: Ruta a tu archivo descargado .p8 archivo de clave
• --apple-key-id: Tu ID de clave de Apple
• --apple-issuer-id: Tu ID de emisor de Apple
• --certificate: Ruta a tu archivo de certificado exportado .p12 certificado
• --ios-provisioning-profile: Ruta a tu archivo descargado .mobileprovision archivo (identificador de paquete autoinferido para perfiles únicos)

Si todo salió bien, verás la siguiente salida:

Falló la autenticación de Apple? Sincroniza tu reloj

Si la clave de App Store Connect API parece correcta pero la autenticación sigue fallando, sincroniza el reloj de tu computadora y vuelve a intentarlo. Capgo firma el JWT de Apple con el tiempo de tu sistema local, y Apple rechaza los tokens que expiran más de 20 minutos en el futuro. Un reloj que solo está unos segundos desfasado puede ser suficiente para fallar este paso.

Consulta la guía de solución de problemas del constructor para pasos de sincronización de reloj.

Configuración de CI/CD (GitHub Acciones)

Si ya completaste ID de equipo, Clave de Apple, ID de clave de Apple y ID de emisor de Apple, Certificado, y Perfil de configuración de provisión, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

Ya tienes todo lo necesario para CI/CD. Esta sección solo cubre cómo pasar esos valores como secretos de acciones de __CAPGO_KEEP_0__ y variables de entorno.

# Distribution certificate (.p12)
base64 -i ./capgo-tutorial/capgo-build-tutorial-certificate.p12 | tr -d '\n' > certificate_base64.txt

# Provisioning profile (.mobileprovision)
base64 -i ./capgo-tutorial/capgo_native_build_tutorial.mobileprovision | tr -d '\n' > profile_base64.txt

# App Store Connect API key (.p8)
base64 -i ./capgo-tutorial/AuthKey_66FGQZB566.p8 | tr -d '\n' > apple_key_base64.txt

Consejo

GitHub secretos deben ser valores de una sola línea. tr -d '\n' elimina los saltos de línea del resultado 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_STORE_CONNECT_TEAM_ID	ID de equipo desde ID de equipo
APPLE_KEY_ID	ID de clave desde Clave de Apple, clave de Apple ID y clave de emisor de Apple
APPLE_ISSUER_ID	ID de emisor desde Clave de Apple, clave de Apple ID y clave de emisor de Apple
BUILD_CERTIFICATE_BASE64	Contenido de certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Generado por CLI — copiar desde .capgo-credentials archivo
APPLE_KEY_CONTENT	Contenido de apple_key_base64.txt
P12_PASSWORD opcional	Su contraseña si se estableció durante la exportación .p12 3) Utilice variables de entorno en su __CAPGO_KEEP_0__ flujo de trabajo de Actions

Sección titulada “3) Utilice variables de entorno en su GitHub flujo de trabajo de Actions”

github/trabajos/ios-build.yml

name: iOS Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  ios-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS build with Capgo
        run: bunx @capgo/cli@latest build request --platform ios
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          APPLE_KEY_ID: ${{ secrets.APPLE_KEY_ID }}
          APPLE_ISSUER_ID: ${{ secrets.APPLE_ISSUER_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP }}
          APPLE_KEY_CONTENT: ${{ secrets.APPLE_KEY_CONTENT }}
          P12_PASSWORD: ${{ secrets.P12_PASSWORD }}

Consejo

Con esta configuración, CI envía credenciales a través de variables de entorno solo. No necesitas comprometer archivos de firma ni subirlos como artefactos de flujo de trabajo.

Ejecutando la compilación

Ahora, estás listo para ejecutar tu primera compilación.

Ejecuta el siguiente comando para compilar tu aplicación:

bunx @capgo/cli@latest build request --platform ios

Felicidades 🎉 En este punto, has compilado con éxito tu aplicación y está lista para ser enviada a la Tienda de App.

Enviar a revisión de App Store

El camino de construcción normal de App Store sube la construcción a App Store Connect/TestFlight. Si su lanzamiento de CI también debe adjuntar la construcción procesada de TestFlight a la versión de App Store y enviarla para revisión de App Store, pase --submit-to-store-review con una construcción de lanzamiento:

npx @capgo/cli@latest build request com.example.app \
  --platform ios \
  --build-mode release \
  --ios-distribution app_store \
  --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" \
  --no-ios-automatic-release

Esto requiere credenciales de clave de App Store Connect API (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, y APP_STORE_CONNECT_TEAM_ID). La contraseña de aplicación de carga y la distribución no pueden enviar una construcción para revisión. ad_hoc es la versión de App Store; si se omite, __CAPGO_KEEP_0__ lee --store-release-name is the App Store version; if omitted, Capgo reads MARKETING_VERSION Enviar a revisión de App Store --store-release-notes es el texto de fallback de What’s New de App Store, y cada --store-release-notes-locale "locale=notes" puede sobrescribirlo para una localización de tienda. Utilice --ios-automatic-release para liberar automáticamente después de la aprobación de Apple, o --no-ios-automatic-release para esperar a una liberación manual. --ios-testflight-groups está disponible aún para la distribución de beta externa, pero no es necesario para la presentación de la revisión de App Store.

Modo de Distribución Ad-Hoc

Por defecto, Capgo compila aplicaciones iOS para la distribución de App Store (TestFlight + App Store). Si necesita compilaciones ad-hoc en su lugar (para pruebas internas o recopilación de artefactos de CI), puede utilizar la --ios-distribution Nota

La distribución ad-hoc es

Modo de Distribución Ad-Hoc Nota No es lo mismo que la distribución Enterprise (en casa). La distribución Enterprise requiere una cuenta de desarrollador Apple Enterprise separada y utiliza perfiles de provisión diferentes. Capgo admite actualmente app_store y ad_hoc Modos

Solo

• Título de la sección “¿Cuándo usar el modo ad-hoc”
• You don’t have or don’t want to use an App Store Connect API key
• No tienes o no quieres usar una clave __CAPGO_KEEP_0__ de App Store Connect --output-upload Quieres recopilar artefactos de compilación mediante

sin enviar a la Tienda de App

Construcciones de ad-hoc tienen pocos requisitos que las construcciones de App Store:

Requisito de credencial	¿Requerido?
Certificado de distribución (.p12)	Sí
Perfil de provisión de ad-hoc (.mobileprovision)	Sí
ID de equipo (--apple-team-id)	Sí
App Store Connect API clave (.p8)	No
ID de clave de Apple / ID emisor	No

Nota

En ad_hoc modo, --apple-key, --apple-key-id, y --apple-issuer-id no están soportados y se ignoran. Esto es por qué las dos filas de App Store Connect arriba no muestran banderas de CLI ad-hoc; estas opciones solo se aplican al app_store modo solo.

Cuidado

Sin una clave API de App Store Connect, el número de compilación autoincremental utiliza un fallback basado en fecha y hora. --skip-build-number-bump.

Creando un perfil de provisión ad-hoc

Sigue los mismos pasos que Perfil de provisiónRol: Etiqueta de navegación o elemento UI corto. Visto en: página native-build.astro. Mensaje clave `native_build_v2_wiz_ios_s3_l` (Native Build V2 Wiz Ios S3 L). , pero en el paso 5, selecciona Ad Hoc en lugar de:

1. Tienda de Aplicaciones Vaya a
2. Perfiles de Desarrollador de Apple + botón
3. Seleccionar Ad Hoc y haga clic en Continuar
4. Seleccione su aplicación y certificado de distribución
5. Seleccione los dispositivos que desea registrar
6. Nombre y descarga del perfil

Almacenando credenciales ad-hoc

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --ios-distribution ad_hoc \
  --apple-team-id YOUR_TEAM_ID \
  --certificate './certificate.p12' \
  --ios-provisioning-profile './adhoc_profile.mobileprovision'

No --apple-key, --apple-key-id, o --apple-issuer-id necesario.

Ejecutar un build ad-hoc

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc

Para recopilar el IPA como un artefacto de build, agrega --output-upload:

bunx @capgo/cli@latest build request \
  --platform ios \
  --ios-distribution ad_hoc \
  --output-upload

CI/CD con builds ad-hoc

Para GitHub Acciones, necesitas menos secretos que builds de App Store:

github/trabajos/ios-adhoc-build.yml

name: iOS Ad-Hoc Build

on:
  workflow_dispatch:

jobs:
  ios-adhoc:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request iOS ad-hoc build
        run: bunx @capgo/cli@latest build request --platform ios --ios-distribution ad_hoc --output-upload
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          APP_STORE_CONNECT_TEAM_ID: ${{ secrets.APP_STORE_CONNECT_TEAM_ID }}
          BUILD_CERTIFICATE_BASE64: ${{ secrets.BUILD_CERTIFICATE_BASE64 }}
          CAPGO_IOS_PROVISIONING_MAP: ${{ secrets.CAPGO_IOS_PROVISIONING_MAP_ADHOC }}
          CAPGO_IOS_DISTRIBUTION: ad_hoc

Consejo

Observa que APPLE_KEY_ID, APPLE_ISSUER_ID, y APPLE_KEY_CONTENT no se necesitan para ediciones de ad-hoc.

Aplicaciones con Extensiones (Firma de múltiples objetivos)

Si tu aplicación incluye extensiones (extensiones de compartir, widgets, extensiones de servicios de notificaciones, etc.), cada objetivo de extensión necesita su propio perfil de provisión. Capgo admite esto mediante la bandera repetible --ios-provisioning-profile Bandera

Ejemplo: Aplicación + Extensión de Compartir

bunx @capgo/cli@latest build credentials save \
  --platform ios \
  --apple-team-id YOUR_TEAM_ID \
  --apple-key '/path/to/AuthKey_XXXXX.p8' \
  --apple-key-id YOUR_KEY_ID \
  --apple-issuer-id YOUR_ISSUER_ID \
  --certificate '/path/to/certificate.p12' \
  --ios-provisioning-profile "com.example.app=./app_profile.mobileprovision" \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Cada --ios-provisioning-profile la bandera asigna un identificador de paquete a su archivo de perfil de configuración. El CLI:

1. Lee cada archivo de mobileprovision
2. Extrae automáticamente el nombre del perfil desde el plist incorporado
3. Codifica en Base64 el archivo
4. Almacena todo como un CAPGO_IOS_PROVISIONING_MAP credencial única

Consejo

Necesita un certificado de distribución para todos los objetivos — solo los perfiles de configuración difieren por objetivo.

Migración desde Perfil Único

Si anteriormente utilizó BUILD_PROVISION_PROFILE_BASE64 (perfil único), ejecute:

bunx @capgo/cli@latest build credentials migrate --platform ios

Esto convierte sus credenciales de perfil único existentes en el nuevo CAPGO_IOS_PROVISIONING_MAP formato y elimina las claves legado (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Después de la migración, agregue perfiles de extensión con el update comando (unión aditiva):

bunx @capgo/cli@latest build credentials update \
  --platform ios \
  --ios-provisioning-profile "com.example.app.share-extension=./share_ext_profile.mobileprovision"

Consejo

Usar update sin savepara agregar perfiles a credenciales existentes. La update comando combina nuevos perfiles con los existentes. Usar save solo cuando esté configurando todas las credenciales desde cero.

Solución de problemas

El perfil de provisión no incluye la capacidad XYZ.

Algunas veces, puedes ver el siguiente error:

Provisioning profile "YOUR_PROVISIONING_PROFILE_NAME" doesn't include the XYZ capability. (in target 'App' from project 'App')"

Esto ocurre porque has habilitado una nueva capacidad después de que se creó el perfil de provisión.

El antiguo perfil de provisión no incluye la nueva capacidad todavía.

1. Para solucionar esto, necesitas regenerar el perfil de provisión. Abrir
2. Portal del desarrollador de Apple
3. Selección de equipo de claves del desarrollador de Apple Profiles Haz clic en el
4. botón de perfiles de desarrollador de Apple para abrir el menú de opciones de perfil de provisión para seleccionar el perfil de provisión que deseas regenerar
5. Haz clic en el Edit botón
6. Haz clic en el Save botón
7. Haz clic en el Download botón
8. Re-ejecuta el comando de configuración de compilación nativa Capgo con el perfil descargado recientemente.

Debería solucionar el problema.

Otros problemas

Si por alguna razón estás teniendo problemas con Capgo Navegación nativa, configuración de credenciales o compilación de la aplicación, no dudes en contactarnos a través de nuestro soporte.

Sigue adelante desde Compilaciones de iOS

Si estás utilizando Compilaciones de iOS para planificar la automatización de CI/CD, conecta con Capgo CI/CD 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