Costruzione di Build iOS

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

Questo che imparerai

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

Requisiti preliminari

• Un account Capgo (un'offerta di prova gratuita è sufficiente per iniziare)
• La tua app già registrata in Capgo (esegui bunx @capgo/cli@latest app add se non lo è)
• 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 dollari all'anno) (Devi avere diritti di amministratore o proprietario sull'account di sviluppatore Apple)
• Il tuo app deve poter essere costruito con successo tramite Xcode
• Un'app Capacitor
• Un'icon configurata per l'app. Le app senza un'icon non possono essere caricate sul Store App.

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 attivare il primo caricamento di TestFlight, assicurati che l'account Apple e il team siano pronti:

• Attiva l'autenticazione a due fattori per l'Account Apple utilizzato per l'iscrizione
• Scegli il tipo di abbonamento giusto:
  • Persona fisica / Proprietario individuale: il tuo nome personale 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 di app, API chiavi e TestFlight
• Assicurati di bloccare 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: URL di supporto, URL della politica sulla privacy, classificazione di età, screenshot, conformità all'esportazione e dettagli di contatto per la revisione di App

Nota

Riferimenti ufficiali utili:

• Diventa membro del programma di sviluppatori di Apple
• 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 2026Si consiglia di utilizzare iPhone e iPad app caricati su App Store Connect con il iOS e iPadOS 26 SDK o successivi.

Consigliato: onboarding automatizzato

Non dovete fare nulla di tutto ciò a mano. Capgo crea e configura i vostri credenziali di firma iOS (certificato di distribuzione + profilo di provisioning) per voi — 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 fa sotto la cappa.

La prima costruzione manuale

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

• Configurerete il certificato di distribuzione sul vostro computer locale
• Creerete il record dell'App Store se non l'avete già fatto
• Potrete risolvere eventuali problemi con il processo di costruzione collegati all'app code

Prima di poter iniziare, dovete avere il certificato di distribuzione installato sul vostro computer locale. Questo è un po' complesso, ma spiegherò tutto 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 sviluppatore Apple

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

6. Clicca sul Manage Certificates... tasto

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

8. Se non riesci a farlo, 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 crearne uno nuovo. Non coprirò questo argomento nel 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 costruzione.

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 tasto

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

   

3. Aspettate che la costruzione sia completa

4. Clicca sul Distribute App tasto

   

5. Seleziona TestFlight Internal Only come metodo di distribuzione e clicca su Distribute tasto

   

6. Configura il record dell'app

   Riempi i seguenti campi:

   1. Nome: Il nome della tua app - visibile nella App Store
   2. SKU - il codice SKU della tua app - questo viene utilizzato per identificare la tua app nella App Store
   3. The primary language - la lingua principale del tuo app

   Poi, clicca sul next button

   

7. Se la creazione del record dell'app fallisce, prova a chiudere la finestra e prova a creare l'archivio dell'app di nuovo.

8. Aspetta che l'upload sia completo

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

10. Clicca sul Done button

Possibilmente penserai che tutto sia andato bene ora e che potrai vedere il tuo app in TestFlight ora, ma ci sono ancora alcune cose da finire:

1. Aggiungiti a TestFlight
2. Esegui l'export compliance in modo che il build diventi testabile
3. Inserisci i metadati obbligatori di App Store Connect, come il tuo URL di supporto, il tuo URL di politica sulla privacy e la tua classificazione di età
4. Prepara le schermate che corrispondono ai dispositivi che effettivamente supporti
5. Aggiungi i dettagli di contatto per la revisione App e qualsiasi credenziale di test prima della sottoscrizione di produzione

Iniziamo con il primo:

Aggiungiti a TestFlight

1. Vai al Pagina di App Store Connect Pagina di accesso a App Store Connect

2. Accedi con il tuo account Apple Developer

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 su Apps button

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

6. Clicca su TestFlight button

7. Clicca su Internal Testers plus button

8. Crea un nuovo gruppo

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

   

9. Clicca su Invite testers button

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 su il Add button.

    

11. Verifica che sei stato aggiunto al gruppo

    Ora dovresti vederti nel gruppo.

    

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

Impostazione delle informazioni sulla conformità

Ora devi 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 documento di Apple sulla gestione di questo aspetto. Ci sono due modi per farlo:

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

Iniziamo 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. Trova la costruzione con informazioni di conformità mancanti e clicca su Manage

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

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

   

5. La tua app dovrebbe ora dire ready to test

   

Per quanto riguarda il secondo, ecco i passaggi:

1. Apri il Info.plist file

2. Aggiungi la seguente chiave:

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

3. Salva il file

Nota

Qui è 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, hai bisogno di fare le seguenti cose:

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

Tralascerò i dettagli su come installare l'app TestFlight sul tuo dispositivo. Se non sei sicuro di 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 sul View in TestFlight button

3. Clicca sul Install button

4. Installa l'app sul tuo dispositivo

   Se hai già installato l'app precedentemente utilizzando Xcode, potresti vedere lo schermo seguente. Per favore clicca sul install button.

5. Aspetta che l'app si installi

6. Clicca sul Open button e cliccalo

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

Configurazione di Capgo Native Build

Ci sono alcune cose che devi configurare in Capgo Build nativo per poter costruire e inviare il tuo app su 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 di sviluppatore Apple (trovabile in Portale dello Sviluppatore Apple)
--apple-key	Percorso del tuo file di chiave API di App Store Connect (.p8 file)
--apple-key-id	L'ID di chiave del tuo file di chiave API di App Store Connect
--apple-issuer-id	Il tuo ID emittente di App Store Connect
--certificate	Percorso del tuo certificato di distribuzione (.p12 file)
--ios-provisioning-profile	Mappatura del profilo di provisioning (bundleId=path o semplicemente 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

Vai a

1. Account Apple Developer e scorri verso il basso Trova il

2. Find the team ID in your Apple Developer Account and scroll down to find it. Team ID

   

Chiave Apple, ID chiave Apple e ID emittente Apple

Ora, passiamo alla chiave Apple.

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, 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. Accedi a pagina di accesso e account utente di 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 dal menu a discesa

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

3. Clicca sul Integrations tasto

4. Trova il issuer

   Attenzione

   Questo DEVE ESSERE SALVATO - ne avrai bisogno in seguito

   Clicca sul copy tasto per copiare l'emittente

5. Clicca sul pulsante +

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

7. Salva l'ID chiave

   Attenzione

   Questo DEVE ESSERE SALVATO - ne avrai bisogno in seguito

   

8. Scarica la chiave

   Attenzione

   Questo E' DA SALVARE - avrai bisogno di esso in seguito

   Pericolo

   NON CONDIVIDERE MAI LA CHIAVE CON ALTRI - 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 come impostarlo:

1. Apri 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 buon nome per il file del certificato
   2. Assicurati di aver impostato il formato del file 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 semplicità): Clicca OK senza inserire alcuna 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 del certificato di Accesso alla chiave password

   

7. dialogo di salvataggio del certificato di Accesso alla chiave password

   Dai la password che usi per accedere al tuo Mac. Poi, clicca sul Allow tasto.

   

Congratulazioni 🎉 Hai esportato il certificato.

Profilo di provisioning

Ora sei pronto per esportare il profilo di provisioning. Ti prometto, questo è l'ultimo cosa dovrai ottenere da Apple.

1. Vai a Profili sviluppatori di Apple

2. Seleziona l'equipe corretta dal menu a discesa

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

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

   

4. Clicca sul + bottoni

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

   

6. Scegli l'app che vuoi costruire

   Trova la tua app nel menu a discesa e clicca sul Continue button

   

7. Seleziona il certificato di distribuzione corretto

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

   

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

   

8. Nome il profilo

   Dai un nome al profilo e clicca sul Generate button

   Tip

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

   

9. Scarica il profilo

   Clicca sul Download tasto per scaricare il profilo

   Attenzione

   Questo file DEVE ESSERE SALVATO - lo avrai bisogno in seguito

   

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

Attenzione

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 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 team Apple
• --apple-key: Percorso del tuo file scaricato .p8 : Il tuo ID di chiave Apple
• --apple-key-id: Il tuo ID di emittente Apple
• --apple-issuer-id: Percorso del tuo certificato esportato
• --certificate: Percorso del tuo file scaricato (ID bundle auto-inferito per profili singoli) .p12 Se tutto è andato bene, vedrai l'output seguente:
• --ios-provisioning-profile__CAPGO_KEEP_0__ .mobileprovision __CAPGO_KEEP_1__

__CAPGO_KEEP_2__

Fallita l'autenticazione Apple? Sincronizza l'orologio

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

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 emittente Apple, Certificato, e Profilo di provisioning, hai già tutto ciò che ti serve per CI/CD. Questa sezione copre solo come passare quei valori come segreti GitHub Actions e variabili di ambiente.

1) Converti i 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

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

2) Crea segreti del repository

Inserisci: 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 della chiave Apple e ID dell'emittente Apple
APPLE_ISSUER_ID	ID dell'emittente da Chiave Apple, ID chiave Apple e ID rilasciatore 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 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 }}

Eccetto

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 la tua app:

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

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

Inviare alla revisione dell'App Store

The percorso di build standard di App Store carica il build su App Store Connect/TestFlight. Se il rilascio CI dovrebbe anche allegare il build elaborato di TestFlight alla versione di App Store e sottoporla per la revisione, passa --submit-to-store-review con un rilascio di build:

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 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 ad_hoc la distribuzione non possono sottoporre un build per la revisione. --store-release-name è la versione di App Store; se omesso, Capgo legge MARKETING_VERSION dal progetto Xcode. --store-release-notes è il testo 'What’s New' di App Store di default, e ogni --store-release-notes-locale "locale=notes" ingresso può sovrascriverlo per una localizzazione di store. Utilizza --ios-automatic-release rilasciare automaticamente dopo l'approvazione di Apple, o --no-ios-automatic-release attendere un rilascio manuale. --ios-testflight-groups è ancora disponibile per la distribuzione beta esterna, ma non è richiesta per la sottoscrizione di revisione di App Store.

Modalità di distribuzione Ad-Hoc

Di default, Capgo crea applicazioni iOS per la distribuzione su 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 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 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 e solo modalità. ad_hoc Quando utilizzare la modalità ad-hoc

Sottosezione intitolata “Quando utilizzare la modalità ad-hoc”

• Non hai o non vuoi utilizzare una chiave App Store Connect __CAPGO_KEEP_0__
• You don’t have or don’t want to use an App Store Connect API key
• senza sottoporre a Store App --output-upload Requisiti

Sottosezione intitolata “Requisiti”

poche richieste poche richieste rispetto alle build di App Store:

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

Nota

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

Preavviso

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

Crea un profilo di provisioning ad-hoc

Segui le stesse istruzioni come Profilo di provisioning, ma nel passo 5, seleziona Ad Hoc al posto di App Store:

1. Vai a Profili sviluppatori di Apple
2. Clicca sul + button
3. Scegli 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

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 --apple-issuer-id necessario.

Esegui 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

Avviso

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

Sottosezione intitolata “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 al suo file di profilo di provisioning. Il CLI:

1. Legge ogni file mobileprovision
2. Auto-strappa il nome del profilo dall'embedded plist
3. Codifica in Base64 il file
4. Mantieni 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 ogni target.

Migrazione da Single Profile

Se hai utilizzato precedentemente BUILD_PROVISION_PROFILE_BASE64 (profilo singolo), esegui:

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

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

Dopo la migrazione, aggiungi 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"

Esegui

Usa update (non save) per aggiungere profili a credenziali esistenti. Il update comando combina nuovi profili con quelli esistenti. Usa save solo quando si configurano tutte le 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à.

1. Per risolvere questo problema, devi rigenerare il profilo di provisioning. Apri
2. Portale dello sviluppatore Apple
3. Selezione team chiavi dello sviluppatore Apple Profiles Clicca sul
4. Button dei profili dello sviluppatore Apple
5. Trova profilo dello sviluppatore Apple e rigenera il profilo di provisioning e clicca sul Edit button
6. Clicca sul Save button
7. Clicca sul Download button
8. Esegui nuovamente il comando di configurazione di build nativa Capgo con il profilo appena scaricato.

Ciò dovrebbe risolvere il problema.

Altri problemi

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

Continua da iOS Builds

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