Costruzione iOS

Costruisci e invia app iOS su TestFlight e App Store utilizzando l'infrastruttura Mac dedicata di Capgo.

Cosa imparerai

• Imparerai a caricare il tuo app tramite Capgo Native build
• Imparerai a configurare i certificati per Capgo Native Build

Requisiti

• Un account Capgo (un periodo di prova gratuito è sufficiente per iniziare)
• La tua app già registrata in Capgo (esegui bunx @capgo/cli@latest app add se non è così)
• A un computer Mac con Xcode installato (è possibile configurare la costruzione su una macchina Linux/Windows, ma non è ancora documentato)
• Un account di sviluppatore Apple valido (99€/anno) (Devi avere diritti di amministratore o proprietario sull'account di sviluppatore Apple)
• La tua app deve essere in grado di costruire con successo tramite Xcode
• Un'app Capacitor
• Un'icona configurata per l'app. Le app senza un'icona non possono essere caricate su App Store

Nota

Utilizzerò l'app seguente per il tutorial: https://github.com/Cap-go/capgo-native-build-tutorial-app

Prima di iniziare nei portali di Apple

Prima di configurare i certificati o di inviare il primo upload di TestFlight, assicurati che l'account e il team Apple siano pronti:

• Attiva l'autenticazione a due fattori per il conto Apple utilizzato per l'iscrizione
• Scegli il tipo di abbonamento giusto:
  • Individuale / Proprietario unico: il tuo nome personale legale diventa il nome del venditore sull'App Store
  • Organizzazione: richiede un'entità legale, un numero D-U-N-S, un sito web aziendale pubblico, un indirizzo email di lavoro sul dominio della società e una persona autorizzata a vincolare l'organizzazione agli accordi di Apple
• Usa un account che possa accedere sia a Apple Developer che a App Store Connect per certificati, registri app, API chiavi e TestFlight
• Assicurati di fissare il tuo ID bundle finale presto. Cambiarlo in seguito significa di solito ricominciare la configurazione dell'App Store
• Pianifica questi elementi di App Store Connect prima della revisione dell'app: URL del supporto, URL della politica sulla privacy, età di accesso, screenshot, conformità all'esportazione e dettagli di contatto per la revisione dell'app

Nota

Riferimenti ufficiali utili:

• Diventare un membro del programma sviluppatore Apple
• Invia le tue app e i giochi
• Informazioni sulla versione del platform in App Store Connect

Attenzione

Apple aggiorna regolarmente il requisito minimo di SDK. A partire dal 28 aprile 2026, le app per iPhone e iPad caricate in App Store Connect devono essere costruite con il IOS e iPadOS 26 SDK o successivi.

Consigliato: onboarding automatizzato

Non è necessario fare nulla di tutto ciò a mano. L'onboarding di Capgo crea e configura i tuoi credenziali di firma iOS (certificato di distribuzione + profilo di provisioning) per te — questo è il percorso consigliato:

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

La guida manuale di seguito è solo per coloro che preferiscono configurare le credenziali da soli o vogliono capire esattamente cosa Capgo faccia sotto il cofano.

La prima costruzione manuale

Prima di poter iniziare a pensare a costruire l'applicazione con Capgo, dovremmo prima configurarla e fare una prima costruzione di TestFlight a mano. Ci sono alcune vantaggi nel fare una costruzione manuale prima:

• Configurerai il certificato di distribuzione sul tuo computer locale
• Creerai il record dell'App Store se non l'hai già fatto
• Potrai risolvere eventuali problemi con il processo di costruzione collegato alla tua app code

Prima di poter iniziare, devi avere installato il certificato di distribuzione sul tuo computer locale. Questo è un po' complesso, ma ti spiegherò come fare di seguito.

Impostazione del certificato di distribuzione

1. Apri Xcode

2. Clicca su Xcode -> Settings... Alternativamente, puoi utilizzare la scorciatoia Cmd + ,

   

3. Vai a Accounts

4. Trova l'Account Apple aggiunto all'Account dello Sviluppatore Apple

5. Trova l'insieme di sviluppatori che utilizzerai per distribuire l'app

6. Clicca sul pulsante Manage Certificates... Pulsante

7. Assicurati di poter vedere il certificato di distribuzione nella lista

8. Se non riesci a vederlo, devi creare un nuovo certificato

   Nota

   Apple limita il numero di certificati di distribuzione che puoi avere a 3. Se ne hai più di 3, devi cancellarne uno per poter crearne uno nuovo. Non coprirò questo argomento nel tutorial

   1. Clicca sul + cliccare su questo pulsante e poi su Apple Distribution
   2. Il certificato verrà creato automaticamente. Puoi vederlo nella lista. Guarda il passaggio precedente per confermare che lo vedi.

Ora che hai installato il certificato di distribuzione, puoi iniziare il processo di costruzione.

Costruzione manuale per TestFlight

1. Apri l'app in Xcode

   Esegui bunx cap open ios per aprire l'app in Xcode.

2. Cerca e clicca sul archive pulsante

   Nella barra degli strumenti di Xcode, cerca e clicca sul product -> archive Clicca.

   

3. Attendere la fine della compilazione

4. Clicca sul Distribute App Clicca sul

   

5. Seleziona TestFlight Internal Only come metodo di distribuzione e clicca sul Distribute Clicca sul metodo di distribuzione di TestFlight interno solo di Xcode

   

6. Compila i seguenti campi:

   __CAPGO_KEEP_0__

   1. Nome: Il nome della tua app - visibile nella App Store
   2. Codice articolo - il codice articolo della tua app - questo viene utilizzato per identificare la tua app nella App Store
   3. La lingua principale - la lingua principale della tua app

   Clicca quindi sul pulsante next Pulsante

   

7. Se la creazione del record dell'applicazione fallisce, prova a chiudere la finestra e riprovare a creare l'archivio dell'applicazione.

8. Attendere la conclusione dell'upload

9. Se tutto è andato bene, dovresti vedere lo schermo seguente

10. Clicca sul pulsante Done Pulsante

Potresti pensare che tutto sia pronto adesso e che potrai vedere la tua app in TestFlight adesso, ma ci sono ancora alcune cose da completare:

1. Aggiungiti a TestFlight
2. Completa la conformità all'esportazione per rendere il build testabile
3. Compila i metadati richiesti di App Store Connect, come il tuo URL di supporto, il tuo URL di politica sulla privacy e la tua classificazione di età
4. context:Pagina/Area: Pagina di soluzione sezione esempi di app. Ruolo: Etichetta UI breve o elemento di navigazione. Visualizzato in: componente soluzioni/SolutionAppExample.astro. Chiave messaggio `solution_app_examples_rating` (Classificazione delle app esemplari).
5. Prepara schermate che corrispondono ai dispositivi che effettivamente supporti

Aggiungi i dettagli di contatto di App Review e qualsiasi credenziale di test prima della sottoscrizione di produzione

Cominciamo con la prima:

1. Sezione intitolata “Aggiungerti a TestFlight” Vai alla Pagina di App Store Connect

2. Accedi con il tuo account di sviluppatore Apple

3. Scegli il team che hai utilizzato quando hai creato il record dell'app. Se hai solo un account di sviluppatore, puoi saltare questo passaggio.

4. Clicca sul Apps tasto

5. Cerca l'app che hai creato nel passaggio precedente e clicca su di essa

6. Clicca sul TestFlight tasto

7. Clicca sul Internal Testers plus bottone

8. Crea un nuovo gruppo

   Mi piace chiamare il gruppo “interni”. Puoi chiamarlo come vuoi.

   

9. Clicca sul Invite testers bottone

10. Aggiungiti al gruppo

    Trova te stesso nella lista e seleziona la casella accanto al tuo nome. (Potresti dover ricaricare la pagina per vederlo) Poi, clicca sul Add bottone.

    

11. Verifica di essere stato aggiunto al gruppo

    Ora dovresti vedere te stesso nel gruppo.

    

Congratulazioni 🎉 Hai aggiunto te stesso a TestFlight. Ora c'è solo una cosa in più che devi fare prima di poter configurare Capgo Build Nativo.

Configurazione delle informazioni di conformità

Ora devi promettere a Apple che il tuo app non utilizza alcuna crittografia non standard (come un algoritmo personalizzato). Se il tuo app utilizza alcuna crittografia non standard, ti consiglio di leggere la Dal documento Apple su come gestire questo. Ci sono due modi per farlo:

1. Puoi farlo a mano ogni volta che costruisci il tuo app.
2. Puoi configurare il tuo file plist per impostare automaticamente questo valore a false.

Cominciamo con il primo:

1. Segui tutte le fasi della sezione precedente per trovare la sezione TestFlight in App Store Connect

2. Clicca su Builds -> iOS

3. Cerca il build con informazioni di conformità mancanti e clicca su Manage

4. Scegli l'opzione che meglio descrive la tua app

   Per me, è nonema potrebbe essere diverso per te. Dopo, clicca su salva

   

5. La tua app dovrebbe ora dire ready to test

   

Ecco i passaggi per il secondo caso:

1. Apre il Info.plist file

2. Aggiungi la seguente chiave:

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

3. Salva il file

Nota

Ecco la documentazione ufficiale di Apple su come informare Apple della tua conformità con le norme di esportazione di cifratura.

Installa l'app TestFlight e accetta l'invito

Ora, sei ALMOST pronto a testare il tuo app in TestFlight. Prima, devi fare le seguenti cose:

1. Scarica l'app TestFlight dal negozio App Store sul tuo dispositivo iOS/iPadOS
2. Accetta l'invito per testare il tuo app

Saltare i dettagli su come installare l'app TestFlight sul tuo dispositivo. Se non sei sicuro su come installare un'app, Google ha alcune guide eccellenti su come farlo.

Per quanto riguarda l'accettazione dell'invito, riceverai un'email da Apple con un link per accettare l'invito.

1. Apre l'email da Apple con il link per accettare l'invito

2. Clicca sul View in TestFlight tasto

3. Clicca sul Install Clicca sul

4. Installa l'app sul tuo dispositivo

   Se hai già installato l'app utilizzando Xcode, potresti vedere la seguente schermata. Per favore clicca sul install Clicca sul pulsante di installazione dell'app di TestFlight

5. Clicca sul

6. Clicca sul pulsante e cliccalo Open Congratulazioni 🎉 Hai accettato l'invito a testare la tua app in TestFlight. Ora puoi configurare __CAPGO_KEEP_0__ Build Nativo per costruire e inviare la tua app a TestFlight.

Congratulations 🎉 You have accepted the invitation to test your app in TestFlight. Now, you can configure Capgo Native Build to build and submit your app to TestFlight.

Configurazione Capgo Build Nativo

C'è bisogno di configurare alcune cose in Capgo Build Nativo per poter costruire e inviare l'applicazione su TestFlight. Ecco una lista delle cose che passerete al Capgo CLI:

Parametro	Descrizione
--platform	La piattaforma per cui costruire (ios)
--apple-team-id	Il tuo ID di sviluppatore Apple (trovabile nel Portale dello Sviluppatore Apple)
--apple-key	Percorso del tuo file API Key di App Store Connect (.p8 file)
--apple-key-id	L'ID Chiave del tuo file API Key di App Store Connect
--apple-issuer-id	L'ID emittente di App Store Connect
--certificate	Percorso per il tuo certificato di distribuzione (.p12 file)
--ios-provisioning-profile	Mappatura del profilo di provisioning (bundleId=path o solo percorso per un profilo singolo)

Esempio di 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 del team

Iniziamo con l'ID del team. Trovarlo è piuttosto facile.

1. Vai a Account del Developer Apple e scorrere verso il basso

2. Trovate la Team ID

   

Apple key, Apple key ID e Apple issuer ID

Ora, passiamo all'Apple key.

macOS: lascia che Capgo crei questa chiave per te

Sul macOS, capgo build init puoi creare questa chiave App Store Connect API per te. Scegli “No — crea una per me” e si apre una finestra guidata App Store Connect, che ti guida attraverso ogni passo e cattura automaticamente la chiave, l'ID chiave e l'ID emittente — senza copia-incolla. I passaggi manuali di seguito sono l'alternativa (e il percorso su Windows o Linux).

1. Vai a Pagina di accesso per l'utente di App Store Connect

   Nota

   Per me il link non funziona a volte. Se non funziona per te, ricarica la pagina.

2. Scegli il team corretto dal menu a discesa

   1. Clicca sul tuo nome nell'angolo in alto a destra
   2. Clicca sul team che vuoi utilizzare

3. Clicca sul Integrations Tasto

4. Trova il issuer

   Attenzione

   Questo DEVE ESSERE SALVATO - lo utilizzerai in seguito

   Clicca sul copy tasto per copiare l'issuer

5. Clicca sul pulsante con il segno più

6. Imposta il nome della chiave e impostare l'accesso App manager e clicca sul Generate bottone

7. Salva l'ID della chiave

   Attenzione

   Questo DEVE ESSERE SALVATO - ne avrai bisogno in seguito

   

8. Scarica la chiave

   Attenzione

   Questo DEVE ESSERE SALVATO - lo utilizzerai in seguito

   Pericolo

   NEVER CONDIVIDERE LA CHIAVE CON ALTRI - UTILIZZALA SOLO NEL CAPGO CLI

   

   

Congratulazioni 🎉 Hai creato la chiave Apple, l'ID chiave Apple e l'ID emittente Apple.

Certificato

Ora, sei pronto per esportare il certificato. Come ricorderai, uno dei primi passaggi di questa guida era la configurazione del certificato di distribuzione.

Tuttavia, Apple, nella loro infinita saggezza, ha deciso che il modo in cui esportare il certificato è molto diverso da quello in cui crearli 😊 Vediamo di impostarlo:

1. Aprite Keychain Access

   1. Cliccate Command + Space per aprire la barra di ricerca
   2. Cercate Keychain Access
   3. Cliccate sul Keychain Access L'applicazione

2. Selezionate la login categoria e cliccate sul My Certificates tasto

3. Trovare il tuo certificato nella lista

   Il certificato dovrebbe essere denominato Apple Distribution: [Your Name/Company] (your team ID)

4. Clicca con il pulsante destro sul certificato e seleziona Export

5. Salva il certificato come un .p12 file

   Attenzione

   Questo DEVE ESSERE SALVATO - avrai bisogno di esso in seguito

   1. Assicurati di selezionare un nome adatto per il file del certificato
   2. Assicurati che il formato del file sia impostato su Personal Information Exchange (.p12)
   3. Clicca sul Save tasto

   

6. Quando ti viene chiesto la password, puoi scegliere di:

   • Saltare la password (consigliato per la semplicità): Clicca OK senza inserire alcuna password
   • Impostare una password: Se preferisci proteggere il tuo certificato con una password, puoi impostarla qui. I file protetti da password sono pienamente supportati dal __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - basta fornire la password utilizzando l' .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password option when running configuration command.

   

7. Quando ti viene chiesto il "password della chiave di rete di accesso", inserisci la password che utilizzi per accedere al tuo Mac

   Inserisci la password che utilizzi per accedere al tuo Mac. Poi, clicca sul Allow tasto.

   

Congratulazioni 🎉 Hai esportato il certificato.

Profilo di provisioning

Ora sei pronto ad esportare il profilo di provisioning. Ti prometto, è l'ultima cosa che dovrai ottenere da Apple.

1. Vai a Profili dello sviluppatore di Apple

2. Scegli il team corretto dal menu a discesa

   1. Clicca sul tuo nome nell'angolo in alto a destra
   2. Clicca sul team che desideri utilizzare

3. Assicurati di essere sulla pagina corretta Deve assomigliare a questo, se non è così clicca su profiles in il menu a discesa

   

4. Clicca sul + tasto

5. Scegli il tipo di profilo Scegli App Store Connect e clicca sul Continue tasto

   

6. Seleziona l'app che desideri costruire

   Trovate l'app nel menu a discesa e cliccate sul Continue button

   

7. Seleziona il certificato di distribuzione corretto

   Selezionate il certificato che avete esportato nel passaggio precedente e cliccate sul Continue button

   

   Se siete incerti sul certificato da selezionare, tornate a Keychain Access e trovate il certificato che avete esportato. Poi guardate la data di scadenza.

   

8. Nominare il profilo

   Dai un nome al profilo e clicca sul Generate bottone

   Suggerimento

   Il nome del profilo viene estratto automaticamente dal Capgo CLI — non è necessario ricordarlo.

   

9. Scarica il profilo

   Clicca sul Download bottone per scaricare il profilo

   Avvertenza

   Questo file E' DA SALVARE - lo utilizzerai più tardi

   

Congratulazioni 🎉 Ora hai tutto ciò di cui hai bisogno per configurare Capgo Build Nativo.

Avvertenza

Non commettere mai le credenziali che hai appena creato nel tuo repository. Tienile al sicuro! 🔒

Eseguire il comando di configurazione

Hai fatto! Ora hai tutto ciò di cui hai bisogno per configurare Capgo Build Nativo.

Il comando che dovrai eseguire è:

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

Sostituisci i valori dei placeholder

Sostituisci i valori dei placeholder sopra con le tue credenziali reali raccolte nei passaggi precedenti:

• --apple-team-id: Il tuo ID di team Apple
• --apple-key: Percorso del tuo file scaricato .p8 file di chiave
• --apple-key-id: Il tuo ID di chiave Apple
• --apple-issuer-id: Il tuo ID di emittente Apple
• --certificate: Percorso del tuo certificato esportato .p12 certificato
• --ios-provisioning-profile: Percorso del tuo file scaricato .mobileprovision file (ID bundle auto-inferito per profili singoli)

Se tutto è andato bene, vedrai l'output seguente:

Fallito l'autenticazione Apple? Sincronizza l'orologio

Se la chiave API di App Store Connect sembra corretta ma l'autenticazione fallisce comunque, sincronizza l'orologio del computer e riprova. Capgo firma il JWT di Apple con il tempo del sistema locale, e Apple rifiuta i token che scadono più di 20 minuti nel futuro. Un orologio che è solo pochi secondi fuori sincrono può essere sufficiente per fallire questo passaggio.

Vedi il guida di troubleshooting del costruttore per i passaggi di sincronizzazione dell'orologio.

Impostazione CI/CD (GitHub Actions)

Se hai già completato ID di squadra, Chiave Apple, ID chiave Apple e ID rilasciatore Apple, Certificato, e Profilo di provisioning, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

Questo sezione copre solo come passare questi valori come segreti di azione __CAPGO_KEEP_0__ e variabili di ambiente.

# 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

Suggerimento

GitHub i segreti dovrebbero essere valori a riga singola. tr -d '\n' rimuove i ritorni a capo dal output base64.

2) Crea i segreti del repository

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

Nome segreto	Valore
CAPGO_TOKEN	Il tuo Capgo API token
APP_STORE_CONNECT_TEAM_ID	ID del team da ID del team
APPLE_KEY_ID	ID della chiave da Chiave Apple, ID chiave Apple e ID emittente Apple
APPLE_ISSUER_ID	ID emittente da Chiave Apple, ID chiave Apple e ID emittente Apple
BUILD_CERTIFICATE_BASE64	Contenuto di certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Generato da CLI — copia da .capgo-credentials file
APPLE_KEY_CONTENT	Contenuto di apple_key_base64.txt
P12_PASSWORD (facoltativo)	La tua .p12 password se impostata durante l'esportazione

3) Utilizza le variabili di ambiente nel tuo GitHub workflow di Actions

github/workflow/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 }}

Suggerimento

Con questa configurazione, il CI invia le credenziali attraverso le variabili di ambiente solo. Non è necessario commitare i file di firma o caricarli come artefatti di flusso di lavoro.

Esecuzione della costruzione

Ora sei pronto a eseguire la tua prima costruzione.

Esegui il seguente comando per costruire il tuo app:

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

Congratulazioni 🎉 In questo punto, hai costruito con successo il tuo app e è pronto per essere inviato alla App Store.

Invia alla revisione della App Store

La normale via di build per la App Store carica il build su App Store Connect/TestFlight. Se il rilascio CI dovrebbe anche allegare il build elaborato di TestFlight alla versione della App Store e inviarla per la revisione, passa --submit-to-store-review con un build di rilascio:

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

Questa richiede le credenziali di chiave API di App Store Connect (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, e APP_STORE_CONNECT_TEAM_IDle password di upload specifiche per l'app e ad_hoc la distribuzione non possono inviare un build per la revisione. --store-release-name è la versione della App Store; se omesso, Capgo legge MARKETING_VERSION dal progetto Xcode. --store-release-notes è il testo di fallback per l'App Store What’s New, e ogni --store-release-notes-locale "locale=notes" ingresso può sovrascriverlo per una localizzazione di store. Utilizza --ios-automatic-release per rilasciare automaticamente dopo l'approvazione di Apple, o --no-ios-automatic-release per attendere un rilascio manuale. --ios-testflight-groups è ancora disponibile per la distribuzione beta esterna, ma non è richiesto per la presentazione di revisione dell'App Store.

Modalità di distribuzione Ad-Hoc

Di default, Capgo costruisce app iOS per la distribuzione dell'App Store (TestFlight + App Store). Se hai bisogno di costruzioni ad-hoc al posto di quelle (per test interni o raccolta di artefatti di CI), puoi utilizzare la --ios-distribution Nota

La distribuzione ad-hoc è

flag. Noto non è lo stesso di Enterprise (In-House) distribuzione. La distribuzione Enterprise richiede un account Apple Developer Enterprise separato e utilizza profili di provisioning diversi. Capgo supporta attualmente app_store E ad_hoc modalità solo.

Quando utilizzare la modalità ad-hoc

• Desideri distribuire le IPA direttamente ai dispositivi registrati (senza TestFlight)
• Non hai o non vuoi utilizzare una chiave API App Store Connect
• Desideri raccogliere gli artefatti di costruzione tramite --output-upload senza sottoporre a valutazione da parte dell'App Store

Requisiti

Costruzioni ad-hoc hanno poche richieste rispetto alle costruzioni di App Store:

La credenziale	È richiesta?
Certificato di distribuzione (.p12)	Sì
Profilo di provisioning ad-hoc (.mobileprovision)	Sì
ID del team (--apple-team-id)	Sì
Chiave App Store Connect API (.p8)	No
ID chiave Apple / ID emittente	No

Nota

In ad_hoc modalità, --apple-key, --apple-key-ide sono ignorati. Questo è il motivo per cui le due righe di App Store Connect sopra non mostrano flag ad-hoc __CAPGO_KEEP_0__; queste opzioni si applicano solo alla --apple-issuer-id are not supported and are ignored. This is why the two App Store Connect rows above do not show ad-hoc CLI flags; these options apply to app_store Precauzione

mode

Senza una chiave API App Store Connect, il numero di build auto-incrementa utilizza un fallback basato su timestamp. Per sopprimere il warning, passa --skip-build-number-bump.

Creazione di un profilo di provisioning ad-hoc

Segui gli stessi passaggi come Profilo di provisioningcontext: Pagina/Area: Capgo Builder / prodotto di build nativo cloud. Ruolo: Etichetta di navigazione o elemento UI breve. Visto in: pagina native-build.astro. Messaggio chiave `native_build_v2_wiz_ios_s3_l` (Native Build V2 Wiz Ios S3 L). , ma in passo 5, seleziona Ad Hoc al posto di:

1. App Store Vai a
2. Profili sviluppatori di Apple + bottoni
3. Seleziona Ad Hoc e clicca Continua
4. Seleziona il tuo app e il certificato di distribuzione
5. Seleziona i dispositivi che desideri registrare
6. Nome e download del profilo

Salvataggio delle credenziali 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-ido, oppure --apple-issuer-id necessario.

Eseguire un build ad-hoc

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

Per raccogliere l'IPA come artefatto di build, aggiungi --output-upload:

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

L'uso di CI/CD con build ad-hoc

Per GitHub Azioni, hai bisogno di meno segreti rispetto ai build per l'App Store:

github/workflow/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

Nota

Nota che APPLE_KEY_ID, APPLE_ISSUER_ID, e APPLE_KEY_CONTENT non sono necessari per le costruzioni ad-hoc.

Applicazioni con Estensioni (Multi-Target Signing)

Se la tua app include estensioni (estensioni di condivisione, widget, estensioni di servizio di notifica, ecc.), ogni target di estensione necessita di un proprio profilo di provisioning. Capgo supporta questo tramite la flag --ios-provisioning-profile ripetibile.

Esempio: App + Estensione di condivisione

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"

Ogni --ios-provisioning-profile la bandiera mappa un ID bundle a suo profilo di provisioning file. Il CLI:

1. Legge ogni file mobileprovision
2. Auto-strappa il nome del profilo dall'embedded plist
3. Codifica in base 64 il file
4. Memorizza tutto come un singolo CAPGO_IOS_PROVISIONING_MAP Credenziale

Suggerimento

Avete bisogno di un certificato di distribuzione per tutti gli obiettivi — differiscono solo i profili di provisioning per obiettivo.

Migrazione da Profilo Singolo

Se avete precedentemente utilizzato BUILD_PROVISION_PROFILE_BASE64 (profilo singolo), eseguite:

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

Questo converte le vostre credenziali esistenti del profilo singolo nel nuovo CAPGO_IOS_PROVISIONING_MAP formato e rimuove le chiavi legacy (BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Dopo la migrazione, aggiungere profili di estensione con il update comando (merge additivo):

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

Suggerimento

Usa update (non save) per aggiungere profili ai credenziali esistenti. Il update comando unisce nuovi profili con quelli esistenti. Usa save solo quando si configurano tutte le credenziali da zero.

Risolvere i problemi

Il profilo di provisioning non include la capacità XYZ.

Alcuni volte, potresti vedere l'errore seguente:

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

Questo accade perché hai abilitato una nuova capacità dopo la creazione del profilo di provisioning. Il vecchio profilo di provisioning non include ancora la nuova capacità.

Per risolvere questo problema, devi rigenerare il profilo di provisioning.

1. Apre Portale dello sviluppatore Apple
2. Scegli il team corretto dal menu a discesa
3. Clicca sul Profiles tasto
4. Cerca il profilo di provisioning che vuoi rigenerare
5. Clicca sul Edit bottone
6. Clicca sul Save bottone
7. Clicca sul Download bottone
8. Esegui nuovamente il comando di configurazione di build nativa Capgo con il profilo scaricato di recente.

Questo dovrebbe risolvere il problema.

Altri problemi

Se per qualsiasi ragione hai problemi con la costruzione nativa Capgo, la configurazione delle credenziali o la costruzione dell'app, non esitare a contattarci tramite il nostro supporto.

Continua da iOS Builds

Se stai utilizzando Costruzione iOS per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD Capgo Native Builds for the product workflow in Capgo Native Builds, Capgo Integrations for the product workflow in Capgo Integrations, Integrazione CI/CD per la dettaglio di implementazione in Integrazione CI/CD, e GitHub Actions Integration for the implementation detail in GitHub Actions Integration.