Costruzione iOS

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

Quello che imparerai

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

Prerequisites

• 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)
• Non è richiesto un Mac: Capgo Build compila e firma il tuo app iOS in cloud, quindi puoi eseguire questo da macOS, Windows o Linux
• Account di sviluppatore Apple valido (99€/anno) (Devi avere diritti di amministratore o proprietario sull'account di sviluppatore Apple)
• La tua app deve costruire con successo (in Xcode localmente, o con Capgo Build)
• 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-tutorial-di-costruzione-di-app-native-per-IOs

Prima di iniziare nei portali di Apple

Prima di configurare i certificati o di attivare il primo upload 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 su 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 aziendale 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, record dell'app, chiavi API e TestFlight
• Riconferma il tuo ID bundle finale presto. Cambiarlo in seguito significa spesso ricompilare la configurazione dell'App Store
• Plan these App Store Connect items before App Review: support URL, privacy policy URL, age rating, screenshots, export compliance, and App Review contact details

Nota

Riferimenti ufficiali utili:

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

Attenzione

Apple aggiorna regolarmente il requisito minimo di SDK. A partire dal 28 aprile 2026applicazioni per iPhone e iPad caricati su App Store Connect devono essere costruiti con il iOS e iPadOS 26 SDK o successivi.

Consigliato: onboarding automatizzato

Non devi 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 passo-passo manuale che segue è 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 per 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 collegati all'app code

Prima di poter iniziare, devi avere il certificato di distribuzione installato sul tuo computer locale. Questo è un po' complesso, ma spiegherò tutto qui sotto.

Configurazione della certificazione di distribuzione

1. Apri Xcode

2. Clicca su Xcode -> Settings... Alternativamente, puoi utilizzare lo shortcut Cmd + ,

   

3. Vai a Accounts

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

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

6. Clicca sul Manage Certificates... bottone

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 hai più di 3 certificati, devi cancellarne uno per poter crearne uno nuovo. Non coprirò questo argomento nel tutorial.

   1. Clicca sul + bottone e poi su Apple Distribution
   2. Il certificato verrà creato automaticamente. Puoi vederlo nella lista. Controlla lo step precedente per confermare di vederlo.

Ora che hai installato la certificazione di distribuzione, puoi iniziare il processo di build.

Costruzione manuale per TestFlight

1. Apre l'applicazione in Xcode

   Esegui bunx cap open ios Apri l'applicazione in Xcode.

2. Per aprire l'applicazione in Xcode. archive Esegui.

   Nell'area di navigazione di Xcode, trova e clicca sul product -> archive Esegui.

   

3. Attendere la conclusione della costruzione

4. Click sul Distribute App button

   

5. Scegli TestFlight Internal Only come metodo di distribuzione e clicca su Distribute button

   

6. Configura il record dell'app

   Riempi i seguenti campi:

   1. Nome: Il nome della tua app - visibile nella App Store
   2. SKU - lo SKU della tua app - questo viene utilizzato per identificare la tua app nella App Store
   3. La lingua primaria - la lingua primaria dell'applicazione

   Cliccare quindi sul next tasto

   

7. Se la registrazione dell'applicazione fallisce, provare a chiudere la finestra e provare a creare l'archivio dell'applicazione di nuovo.

8. Attendere la completa dell'upload

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

10. Cliccare sul Done tasto

Potresti pensare istintivamente che tutto sia andato bene e che potrai vedere l'applicazione in TestFlight adesso, ma ci sono ancora alcune cose da finire:

1. Aggiungere te stesso a TestFlight
2. Completa la conformità all'esportazione in modo che l'edizione diventi eseguibile
3. Inserisci i metadati obbligatori per App Store Connect, come il tuo URL di supporto, la tua politica sulla privacy e la 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:

Aggiungere te stesso a TestFlight

1. Vai alla pagina App Store Connect page

2. Accedi con il tuo account di sviluppatore Apple

3. Seleziona l'equipe 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 bottone

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

6. Clicca sul TestFlight bottone

7. Clicca sul Internal Testers plus bottone

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 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 Build Nativo.

Configurazione delle informazioni sulla conformità

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

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. Trova il build con le informazioni di conformità mancanti e clicca su Manage

4. Seleziona l'opzione che meglio descrive il tuo app

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

   

5. Il tuo 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

Ecco è la documentazione ufficiale di Apple per informare Apple sulla propria conformità con le norme di esportazione di cifratura.

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

Now, you are QUASI pronto per testare il tuo app su TestFlight. Prima, devi fare le seguenti cose:

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

Ometterò i dettagli su come installare l'app di 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 button

3. Clicca sul Install button

4. Installa l'app sul tuo dispositivo

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

5. Aspetta che l'app si installi

6. Clicca sul Open Bottone e cliccalo

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

Configurazione di Capgo Build Nativo

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 da costruire per (ios)
--apple-team-id	La tua ID di sviluppatore Apple (trovata in Portale di sviluppatore Apple)
--apple-key	Percorso del tuo file chiave App Store Connect API (.p8 file)
--apple-key-id	La chiave ID del tuo file chiave App Store Connect API
--apple-issuer-id	La tua 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 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

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

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

2. Trova il 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

Sul 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 App Store Connect, ti guida attraverso ogni passo e cattura la chiave, l'ID chiave e l'ID rilasciatore automaticamente — 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 App Store Connect

   Nota

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

2. Scegli 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 Pulsante

4. Cerca il issuer

   Attenzione

   Questo DA SALVARE - lo avrai bisogno in seguito

   Clicca sul copy tasto per copiare l'emittente

5. Clicca sul pulsante con il segno più

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 È DA SALVARE - lo utilizzerai in seguito

   Pericolo

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

1. Apri Accesso alla Cassetta dei Segreti

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

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

3. Cerca il tuo certificato nella lista

   La certificazione dovrebbe essere denominata Apple Distribution: [Your Name/Company] (your team ID)

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

5. Salva la certificazione come un .p12 file

   Attenzione

   Questo DEVE ESSERE SALVATO - avrai bisogno di esso in seguito

   1. Assicurati di selezionare un buon nome per il file della certificazione
   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 semplicità): Clicca OK senza inserire alcuna password
   • Imposta una password: Se preferisci proteggere il tuo certificato con una password, puoi impostarla qui. Certificato protetto da password .p12 i file sono pienamente supportati dal Capgo CLI - basta fornire la password utilizzando il --p12-password opzione quando si esegue il comando di configurazione.

   

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

   Digita la password che utilizzi per accedere al tuo Mac. Poi, clicca sul Allow button.

   

Congratulazioni 🎉 Hai esportato il certificato.

Profilo di provisioning

Ora, sei pronto a esportare il profilo di provisioning. Ti assicuro, questo è l'ultimo passo che dovrai fare per ottenere qualcosa da Apple.

1. Vai a Profili sviluppatori Apple

2. Profili sviluppatori di Apple

   1. Scegli la squadra corretta dal menu a discesa
   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 riquadro laterale

   

4. Clicca sul + tasto

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

   

6. Scegli l'app che vuoi costruire

   Trova la tua app nella lista a discesa e clicca sul Continue button

   

7. Scegli il certificato di distribuzione corretto

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

   

   Se sei incerto sul certificato da 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 button

   Avviso

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

   

9. Scarica il profilo

   Clicca sul Download bottone per scaricare il profilo

   Attenzione

   Questo file DEVE ESSERE SALVATO — ne avrai bisogno in seguito

   

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

Preavviso

Non commettere mai le credenziali appena create 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 rilascio Apple
• --apple-issuer-id: Il tuo ID emittente Apple
• --certificate: Il tuo file di certificato .p12 certificate
• --ios-provisioning-profile: Percorso del tuo file scaricato .mobileprovision Se tutto è andato bene, vedrai l'output seguente:

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

Apple auth failed? Sync your clock

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 scadranno dopo più di 20 minuti. Un orologio che è solo pochi secondi fuori sincronia può essere sufficiente per fallire questo passaggio.

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

Configurazione CI/CD (GitHub Actions)

Se hai già completato ID di squadra, 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 questi valori come segreti e variabili di ambiente di GitHub Actions.

1) Converti i file di credenziali in base64 singola riga

# 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

Tip

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

2) Crea segreti del 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 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)	Il tuo .p12 password se impostato durante l'esportazione

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

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

Esempio

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

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 avuto successo nella costruzione del tuo app e è pronto per essere inviato alla revisione dell'App Store.

Inviare alla revisione dell'App Store

Il percorso di costruzione normale 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

Ciò richiede le credenziali di chiave API di App Store Connect (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, e APP_STORE_CONNECT_TEAM_IDCarica password di accesso app-specifiche e ad_hoc è la versione di App Store; se omesso, __CAPGO_KEEP_0__ legge --store-release-name è la versione dell'App Store; se omesso, Capgo legge MARKETING_VERSION dal progetto Xcode. --store-release-notes ingresso può sovrascriverlo per una localizzazione di store. Utilizza --store-release-notes-locale "locale=notes" entry può sovrascrivere il valore per una localizzazione di store. Utilizza --ios-automatic-release per rilasciare automaticamente dopo l'approvazione di Apple, o --no-ios-automatic-release o attendere un rilascio manuale. --ios-testflight-groups è ancora disponibile per la distribuzione beta esterna, ma non è richiesta per la sottoscrizione di valutazione della App Store.

Modalità di distribuzione Ad-Hoc

Di default, Capgo crea app iOS per la distribuzione sull'App Store (TestFlight + App Store). Se hai bisogno di costruire app ad-hoc (per test interni o raccolta di artefatti di CI), puoi utilizzare il --ios-distribution Nota

Note

Distribuzione ad-hoc è è 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 supporta attualmente app_store E e solo. ad_hoc Eseguire solo.

Quando utilizzare il modo ad-hoc.

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

Requisiti.

Il modo ad-hoc ha requisiti minori. più App Store build:

Autenticazione	Richiesta?
Certificato di distribuzione (.p12)	Sì
Distribuzione certificato (.mobileprovision)	Sì
ID del team (--apple-team-id)	Sì
Chiave App Store Connect API (.p8)	No
ID Apple Key / Issuer	No

Nota

In ad_hoc modalità, --apple-key, --apple-key-id, and --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 Attenzione

Caution

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

Creazione di un profilo di provisioning ad-hoc

Segui le stesse istruzioni come Profilo di provisioningProfilo di provisioning Ad Hoc Ad Hoc invece di:

1. App Store Profili sviluppatori Apple
2. Clicca + Clicca sul
3. button 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 needed.

Esecuzione di 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 azioni, avete bisogno di meno segreti rispetto alle 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 --ios-provisioning-profile flag.

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-estrae il nome del profilo dall'embedded plist
3. Codifica in Base64 il file
4. Mantieni tutto come un singolo CAPGO_IOS_PROVISIONING_MAP credenziale

Tip

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

Migrazione da Profilo Singolo

Se hai già utilizzato BUILD_PROVISION_PROFILE_BASE64 Esegui (profilo singolo), esegui:

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

Ciò converte i tuoi 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 aggiuntivo):

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

Tip

Usa update (niente) saveAggiungere profili agli account esistenti. update utilizza il comando per unire i nuovi profili con quelli esistenti. save Solo quando si configurano tutti i credenziali da zero.

Risolvere Problemi

Profilo di provisioning non include la capacità XYZ.

Qualche volta 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, devi ricreare il profilo di provisioning.

1. Apri Portale dello sviluppatore Apple
2. Seleziona la squadra corretta nel menu a discesa
3. Clicca sul Profiles tasto
4. Trova il profilo di provisioning che desideri ricreare
5. Clicca sul Edit button
6. Clicca sul Save button
7. Clicca sul Download button
8. Rieccitere il comando di configurazione di build nativa Capgo Ciò dovrebbe risolvere il problema.

Questo dovrebbe risolvere il problema.

Problemi diversi

If for whatever reason you are having issues either with Capgo Native Build, configuring the credentials or building the app, please don’t hesitate to reach via our supporto.

Continua da 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 Native Builds per il flusso di lavoro del prodotto in Capgo Native Builds, Capgo Integrazioni per il flusso di lavoro del prodotto in Capgo Integrazioni Integrazione CI/CD per i dettagli di implementazione in Integrazione CI/CD, e GitHub Azioni di integrazione per i dettagli di implementazione in GitHub Azioni di integrazione.