Costruzioni iOS

Crea 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
• You imparerai come configurare i certificati per Capgo Build Nativo

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)
• Un computer Mac con Xcode installato (è possibile configurare la build 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 caricare il primo upload di TestFlight, assicurati che l'account e il team Apple siano pronti:

• Attiva l'autenticazione a due fattori per l'account 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 i certificati, i record dell'app, le API chiavi e TestFlight
• Blocca il tuo ID bundle finale presto. Cambiarlo in seguito significa di solito ricominciare la configurazione di App Store
• Pianifica questi elementi di App Store Connect prima della revisione di App Review: URL di supporto, URL di politica sulla privacy, età di valutazione, screenshot, conformità all'esportazione e dettagli di contatto di App Review

Nota

Riferimenti ufficiali utili:

• Diventa membro del programma Apple Developer
• Invia le tue app e i giochi
• Informazioni sulla versione della piattaforma in App Store Connect

Attenzione

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

Consigliato: onboarding automatizzato

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

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

The manual walkthrough below is only for those who prefer to set up credentials themselves, or want to understand exactly what Capgo does under the hood.

La prima costruzione manuale

Prima di poter iniziare a pensare a costruire l'app con Capgo, dovremmo prima di tutto impostarla e fare una prima build di TestFlight a mano. Ci sono alcuni 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 fatto ancora
• Potrai capire eventuali problemi con il processo di costruzione legati all'app code

Prima di poter iniziare, è necessario che il certificato di distribuzione sia installato sul tuo computer locale. Questo è abbastanza complesso, ma spiegherò tutto qui sotto.

Impostazione del certificato di distribuzione

1. Apre Xcode

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

   

3. Vai a Accounts

4. Trova l'account Apple aggiunto all'account sviluppatore Apple

5. Trova il team che utilizzerai per distribuire l'app

6. Clicca sul Manage Certificates... button

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

8. Se non lo fai, devi creare un nuovo certificato

   Nota

   Apple limita il numero di certificati di distribuzione che puoi avere a 3. Se hai più di 3 certificati, devi eliminare uno per poter creare uno nuovo. Non lo coprirò in questo tutorial.

   1. Clicca sul + tasto 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 build.

Costruzione manuale per TestFlight

1. Apri l'app in Xcode

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

2. Trova e clicca sul archive button

   Nella barra degli strumenti di Xcode, trova e clicca sul product -> archive button.

   

3. Aspetta che la compilazione sia completata

4. Clicca sul Distribute App button

   

5. Scegli come metodo di distribuzione e clicca su TestFlight Internal Only button Distribute Metodo di distribuzione Xcode TestFlight interno solo

   

6. Compila i seguenti campi:

   Nome: Il nome della tua app - visibile nella App Store

   1. SKU - lo SKU della tua app - questo viene utilizzato per identificare la tua app nella App Store
   2. La lingua principale - la lingua principale della tua app
   3. Poi, clicca sul

   button next Metodo di distribuzione Xcode TestFlight configura record dell'app

   

7. Se la creazione del record dell'app non riesce, prova a chiudere la finestra e riprova ad archiviare l'app di nuovo.

8. Attendere la conclusione dell'upload

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

10. Clicca sul Done bottoni

Potresti pensare istintivamente che tutto sia andato bene ora 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 affinché la costruzione diventi testabile
3. Riempire i metadati di App Store Connect richiesti, come l'URL del tuo supporto, l'URL della tua politica sulla privacy e la classificazione di età
4. Preparare screenshot che corrispondono ai dispositivi che effettivamente supporti
5. Aggiungere i dettagli di contatto per la revisione dell'app e qualsiasi credenziale di test prima della sottoscrizione di produzione

Iniziamo con il primo:

Aggiungere se stesso a TestFlight

1. Vai al App Store Connect pagina

2. Accedi con il tuo account di sviluppatore Apple

3. Seleziona 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 button

5. Trova l'app che hai creato nel passo precedente e clicca su di essa

6. Clicca sul TestFlight pulsante

7. Clicca sul Internal Testers plus pulsante

8. Crea un nuovo gruppo

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

   

9. Clicca su Invite testers tasto

10. Aggiungiti al gruppo

    Trova te stesso nella lista e seleziona la casella accanto al tuo nome. (Potresti dover ricaricare la pagina per vederlo) Quindi, clicca su il Add tasto di selezione tester App Store Connect checkbox

    

11. Ora dovresti vedere te stesso nel gruppo.

    App Store Connect verifica tester

    

Congratulations 🎉 You have added yourself to TestFlight. Now, there is just one more thing you need to do before you can configure Capgo Native Build.

Setting up the compliance information

Ora hai bisogno di promettere a Apple che la tua app non utilizza alcuna crittografia non standard (come un algoritmo personalizzato). Se la tua app utilizza effettivamente alcuna crittografia non standard, ti consiglio di leggere il documentazione di Apple su come gestire questo aspetto. Ci sono due modi per farlo:

1. Potresti farlo a mano ogni volta che costruisci l'app.
2. Potresti configurare il file plist per impostare automaticamente questo valore su false.

Iniziamo con il primo:

1. Segui tutti i passaggi della sezione precedente per trovare la sezione TestFlight in App Store Connect

2. Clicca su Builds -> iOS

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

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

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

   

5. La tua app dovrebbe ora dire ready to test

   

Per quanto riguarda la seconda, ecco i passaggi:

1. Apri il Info.plist file

2. Aggiungi la seguente chiave:

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

3. Salva il file

Nota

Ecco qui la documentazione ufficiale di Apple su come informare Apple della propria conformità alle norme di esportazione di cifratura.

L'installazione dell'app TestFlight e l'accettazione dell'invito

Ora, sei PRATICAMENTE pronto per testare la tua app in TestFlight. Prima, devi fare le seguenti cose:

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

Mi scuso per non fornire i dettagli su come installare l'app TestFlight sul tuo dispositivo. Se non sei sicuro su come installare un'app, Google ha alcune guide fantastiche su come farlo.

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

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

2. Clicca su View in TestFlight button

3. button 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 button.

5. Aspetta che l'app venga installata

6. Clicca su il Open button e cliccalo

Congratulazioni 🎉 Hai accettato l'invito per testare la tua app in TestFlight. Ora puoi configurare Capgo Build Nativo per costruire e inviare la tua app a TestFlight.

Configurazione di Capgo Build Nativo

Ci sono alcune cose che devi configurare in Capgo Build Nativo per poter costruire e inviare la tua app a TestFlight. Ecco una lista delle cose che passerai al Capgo CLI:

Parametro	Descrizione
--platform	La piattaforma per cui costruire (ios)
--apple-team-id	Il tuo ID del team di sviluppatore Apple (trovato in Portale del sviluppatore Apple)
--apple-key	Percorso del tuo file chiave App Store Connect API (.p8 file)
--apple-key-id	The Key ID of your App Store Connect API Key
--apple-issuer-id	Il tuo ID emittente App Store Connect
--certificate	Percorso del 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 della squadra

Iniziamo con l'ID della squadra. Trovarlo è abbastanza facile.

1. Vai a Account del sviluppatore Apple e scorri verso il basso

2. Trova la Team ID

   

Chiave Apple, ID chiave Apple e ID rilasciatore Apple

Ora, passiamo alla chiave Apple.

macOS: lascia che Capgo crei questa chiave per te

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

1. Vai a pagina di accesso utente e accesso a App Store Connect

   Nota

   Per me il link non funziona a volte. Ricarica la pagina se non funziona per te.

2. Seleziona la squadra corretta nel menu a discesa

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

3. Clicca sul Integrations button

4. Trova il issuer

   Attenzione

   Questo DEVE ESSERE SALVATO - avrai bisogno di esso in seguito

   Clicca sul copy tasto per copiare l' emittente

5. Clicca sul

6. Imposta il nome della chiave e impostalo per l'accesso a App manager e clicca sul Generate tasto

7. Salva l'ID della chiave

   Attenzione

   Questo __CAPGO_KEEP_0__ - lo avrai bisogno più tardi

   

8. Scarica la chiave

   Attenzione

   Questo __CAPGO_KEEP_1__ - lo avrai bisogno più tardi

   Pericolo

   NEVER CONDIVIDI LA CHIAVE CON QUALCUNO - USALA SOLO NEL CAPGO CLI

   

   

Congratulazioni 🎉 Hai creato la chiave Apple, ID chiave Apple e ID rilasciatore 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 capire come impostarlo:

1. Aprite Keychain Access

   1. Clicca Command + Space per aprire la barra di ricerca
   2. Cerca Keychain Access
   3. Clicca sul Keychain Access app

2. Seleziona la login categoria e clicca sul My Certificates tasto

3. Trova il tuo certificato nella lista

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

4. Fai clic destro sul certificato e seleziona Export

5. Salva il certificato come un .p12 file

   Attenzione

   Questo __CAPGO_KEEP_0__ - 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 bottoni

   

6. When richiesto la password, puoi scegliere:

   • Saltare la password (consigliato per semplicità): Clicca OK senza inserire una password
   • Imposta 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 Dialogo di salvataggio della password del certificato di Accesso alla chiave

   

7. Fornisci la password che utilizzi per accedere al tuo Mac. Poi, clicca sul

   tasto. Allow Dialogo di salvataggio della password della chiave di accesso del login

   

Skip the password (recommended for simplicity): Click __CAPGO_KEEP_0__ without entering a password

Profilo di provisioning

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

1. Vai a Profili sviluppatori Apple

2. Seleziona il team corretto nella casella 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 avere questo aspetto, se non è così clicca su profiles nella barra laterale

   

4. Clicca sul + __CAPGO_KEEP_0__

5. Aggiungi profilo sviluppatore Apple App Store Connect Seleziona il tipo di profilo Seleziona Continue __CAPGO_KEEP_0__

   

6. Seleziona il tipo di profilo sviluppatore Apple

   Seleziona l'app che vuoi costruire Continue Trova l'app nel menu a discesa e clicca sul

   

7. button sviluppatore Apple seleziona app

   Seleziona il certificato che hai esportato nel passaggio precedente e clicca sul Continue __CAPGO_KEEP_0__

   

   Se sei incerto su quale certificato selezionare, torna a Keychain Access e trova il certificato che hai esportato. Poi guarda la data di scadenza.

   

8. Nome il profilo

   Dai un nome al profilo e clicca sul Generate __CAPGO_KEEP_0__

   Consiglio

   Il nome del profilo viene estratto automaticamente da Capgo CLI — non hai bisogno di ricordarlo.

   

9. Scarica il profilo

   Clicca sul Download tasto per scaricare il profilo

   Attenzione

   Questo file DEVE ESSERE SALVATO - lo avrai bisogno in futuro

   

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

Attenzione

Non commettere mai le credenziali appena create nel tuo repository. Tienile al sicuro! 🔒

Eseguire il comando di configurazione

Lo hai fatto! Ora hai tutto ciò di cui hai bisogno per configurare Capgo Native Build.

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 Apple Team
• --apple-key: Percorso del tuo file scaricato .p8 chiave file
• --apple-key-id: Il tuo ID Apple Key
• --apple-issuer-id: Il tuo ID Apple Issuer
• --certificate: Percorso del tuo file esportato .p12 certificato
• --ios-provisioning-profile: Percorso del tuo file scaricato .mobileprovision : Percorso del tuo file scaricato (ID bundle auto-inferito per profili singoli)

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

Fallita l'autenticazione Apple? Sincronizza l'orologio

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

Vedi il guida di risoluzione dei problemi del costruttore per i passaggi di sincronizzazione dell'orologio.

Impostazione CI/CD (GitHub Actions)

Se hai già completato ID del team, Chiave Apple, ID chiave Apple e ID rilasciatore Apple, Certificato, e Profilo di provisioning, hai già tutto ciò che ti serve per la CI/CD. Questa sezione copre solo come passare quei valori come segreti e variabili di ambiente di GitHub Actions.

1) Converti file di credenziali in base64 a riga singola

# 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 le segrete dovrebbero essere valori a riga singola. tr -d '\n' rimuove i ritorni a capo dall'output base64.

2) Crea segreti di repository

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

Nome segreto	Valore
CAPGO_TOKEN	Il tuo token Capgo API
APP_STORE_CONNECT_TEAM_ID	ID del team da ID del team
APPLE_KEY_ID	ID della chiave da Chiave Apple, ID della chiave Apple e ID dell'emittente Apple
APPLE_ISSUER_ID	ID dell'emittente da Chiave Apple, ID della chiave Apple e ID dell'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)	Il tuo .p12 password se impostato durante l'esportazione

3) Utilizza le variabili di ambiente nei tuoi GitHub Actions workflow

github/workflows/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 questo setup, CI invia le credenziali solo attraverso le variabili di ambiente. Non è necessario commitare i file di firma o caricarli come artefatti del workflow.

Esecuzione della build

Ora sei pronto a eseguire la tua prima costruzione.

Esegui il seguente comando per costruire la tua app:

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

Congratulazioni 🎉 In questo punto, hai avuto successo nella costruzione della tua app e è pronta per essere inviata alla valutazione dell'App Store.

Invia alla valutazione dell'App Store

Il percorso di costruzione normale dell'App Store carica la costruzione su App Store Connect/TestFlight. Se il rilascio CI dovrebbe anche allegare la costruzione elaborata di TestFlight alla versione dell'App Store e inviarla per la valutazione, passa --submit-to-store-review con un rilascio di costruzione:

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

Richiede le credenziali chiave di App Store Connect API (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, e APP_STORE_CONNECT_TEAM_ID). L'upload di password app-specific e la distribuzione non possono inviare una build per la revisione. ad_hoc è la versione di App Store; se omesso, __CAPGO_KEEP_0__ legge --store-release-name is the App Store version; if omitted, Capgo reads MARKETING_VERSION è il testo di What’s New di App Store di fallback, e ogni --store-release-notes entry può sovrascriverlo per una localizzazione di store. Utilizza --store-release-notes-locale "locale=notes" per rilasciare automaticamente dopo l'approvazione di Apple, o --ios-automatic-release per attendere un rilascio manuale. --no-ios-automatic-release è ancora disponibile per la distribuzione beta esterna, ma non è richiesta per la sottoscrizione di App Store. --ios-testflight-groups Modalità di distribuzione Ad-Hoc

Modalità di distribuzione Ad-Hoc

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

Nota

La distribuzione ad-hoc non è la stessa della distribuzione Enterprise (In-House). La distribuzione Enterprise richiede un account separato di sviluppatore Apple Enterprise e utilizza profili di provisioning diversi. __CAPGO_KEEP_0__ supporta attualmente solo e the same as Enterprise (In-House) distribution. Enterprise distribution requires a separate Apple Developer Enterprise account and uses different provisioning profiles. Capgo currently supports app_store Quando utilizzare la modalità ad-hoc ad_hoc Sezione intitolata “Quando utilizzare la modalità ad-hoc”

targetLanguage

• Vuoi distribuire le IPAs direttamente ai dispositivi registrati (senza TestFlight)
• Non hai o non vuoi utilizzare una chiave App Store Connect API
• Vuoi raccogliere gli artefatti di costruzione via --output-upload senza sottoporre a valutazione l'App Store

Requisiti

Il build ad-hoc ha requisiti minori rispetto ai build per l'App Store:

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

Nota

In ad_hoc modalità, --apple-key, --apple-key-id, e --apple-issuer-id non sono supportate e vengono ignorate. Questo è il motivo per cui le due righe di App Store Connect sopra non mostrano flag CLI ad-hoc; queste opzioni si applicano solo alla app_store modalità.

Attenzione

Senza una chiave API di App Store Connect, l'incremento automatico del numero di build 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 provisioning, ma nel passo 5, seleziona Ad Hoc al posto di App Store:

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

Salvare 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-id, o --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

CI/CD con build ad-hoc

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

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

Suggerimento

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 ripetibile. --ios-provisioning-profile Esempio: App + Estensione di condivisione

Finestra del terminale

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"

Legge ogni file mobileprovision --ios-provisioning-profile flag maps a bundle ID to its provisioning profile file. The CLI:

1. Legge ogni file mobileprovision
2. Estrae automaticamente il nome del profilo dal plist incorporato
3. Codifica in Base64 il file
4. Memorizza tutto come un singolo CAPGO_IOS_PROVISIONING_MAP credenziale

Suggerimento

Hai bisogno di un certificato di distribuzione per tutti i target — differiscono solo i profili di provisioning per target.

Migrazione da Profilo Singolo

(profilo singolo), esegui: BUILD_PROVISION_PROFILE_BASE64 Finestra del terminale

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

Questo converte i tuoi credenziali esistenti a profilo singolo in formato nuovo e elimina le chiavi legacy ( CAPGO_IOS_PROVISIONING_MAP Dopo la migrazione, aggiungi profili di estensione con il comando (merge additivo):BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Finestra del terminale update Copia nel portapenne

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

(non

) per aggiungere profili alle credenziali esistenti. Il update Il save) to add profiles to existing credentials. The update Il comando combina i nuovi profili con quelli esistenti. Utilizza save solo quando si configurano tutti i credenziali da zero.

Risoluzione dei problemi

Il profilo di provisioning non include la capacità XYZ.

A volte, potresti vedere l'errore seguente:

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

Ciò 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, è necessario rigenerare il profilo di provisioning.

1. Apri Portale dello Sviluppatore Apple
2. Scegli la squadra corretta dal menu a discesa
3. Clicca sul Profiles tasto
4. Trova il profilo di provisioning che desideri rigenerare
5. Clicca sul Edit tasto
6. Clicca sul Save tasto
7. Clicca sul Download button
8. Riecco il comando di configurazione Capgo Native Build Esegui nuovamente il comando di configurazione __CAPGO_KEEP_0__ Native Build con il profilo scaricato.

Questo dovrebbe risolvere il problema.

Altri problemi

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

Continua con iOS Builds

Se stai utilizzando Costruzioni iOS per pianificare l'automazione CI/CD, connettilo con Capgo CI/CD per il flusso di lavoro del prodotto in Capgo CI/CD, Capgo Costruzioni Native per il flusso di lavoro del prodotto in Capgo Costruzioni Native, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni, Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, GitHub Azioni di integrazione per i dettagli di implementazione in GitHub Azioni di integrazione.