Constructions iOS

Construirez et soumettrez des applications iOS à TestFlight et à l'App Store à l'aide de l'infrastructure Mac dédiée de Capgo.

Ce que vous allez apprendre

• Vous allez apprendre à télécharger votre application via Capgo Native build
• Vous allez apprendre à configurer les certificats pour Capgo Native Build

Prerequisites

• Un compte Capgo (un essai gratuit suffit pour commencer)
• Votre application déjà enregistrée dans Capgo (exécutez bunx @capgo/cli@latest app add si pas
• Pas de Mac nécessaire : Capgo Build compile et signe votre application iOS dans le cloud, vous pouvez donc exécuter cela depuis macOS, Windows ou Linux
• Compte Apple valide (99 $/an) (Vous devez avoir des droits d'administrateur ou propriétaire sur le compte Apple Developer)
• Votre application doit se construire avec succès (en Xcode localement, ou avec Capgo Build)
• Une application Capacitor
• Un icône configuré pour l'application. Les applications sans icône ne peuvent pas être mises en ligne sur l'App Store.

Remarque

J'utiliserai l'application suivante pour le tutoriel : https://github.com/Cap-go/capgo-native-build-tutorial-app

Avant de commencer dans les portails d'Apple

Avant de configurer les certificats ou de déclencher votre première mise en ligne TestFlight, assurez-vous que le compte Apple et l'équipe soient prêts.

• Section intitulée « Avant de commencer dans les portails d'Apple »
• Choisissez le bon type de membership :
  • Individuel / Propriétaire unique: votre nom personnel légal devient le nom du vendeur sur l'App Store
  • Organisation: nécessite une entité juridique, un numéro D-U-N-S, un site web de société public, un courriel de travail sur le domaine de la société, et une personne ayant l'autorité de lier l'organisation aux accords d'Apple
• Utilisez un compte pouvant accéder à Apple Developer et App Store Connect pour les certificats, les enregistrements d'applications, les clés API et TestFlight.
• Fixez votre ID de bundle final tôt. Le changement ultérieur implique généralement de refaire la configuration de l'App Store.
• Planifiez ces éléments App Store Connect avant la revue d'App : URL de support, URL de politique de confidentialité, note d'âge, captures d'écran, conformité à l'exportation et détails de contact pour la revue d'App

Note

Références officielles utiles :

• Devenez membre du programme Apple Developer
• Soumettez vos applications et jeux
• Informations sur la version du plateforme dans App Store Connect

Attention

Apple met à jour régulièrement ses exigences minimales de SDK. À partir du 28 avril 2026, les applications iPhone et iPad mises en ligne sur App Store Connect doivent être construites avec le iOS et iPadOS 26 SDK ou ultérieur.

Recommandé : l'inscription automatique

Vous n'avez pas besoin de faire tout cela manuellement. L'inscription de Capgo crée et configure vos certificats de signature iOS (certificat de distribution + profil de provisioning) pour vous — c'est le chemin recommandé :

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 première construction manuelle

Before we can start thinking about building the app with Capgo, we should first set it up, and do a first TestFlight build by hand. There are some advantages to doing a manual build first:

• Vous allez configurer le certificat de distribution sur votre machine locale.
• Vous configurerez le certificat de distribution sur votre machine locale
• Vous pourrez identifier les problèmes liés au processus de construction associé à votre application code.

Avant de commencer, vous devez avoir le certificat de distribution installé sur votre machine locale. Cela est assez complexe, mais je vais l'expliquer ci-dessous.

Configuration du certificat de distribution

1. Ouvrez Xcode

2. Cliquez sur Xcode -> Settings... Alternativement, vous pouvez utiliser la raccourci Cmd + ,

   

3. Allez à Accounts

4. Trouvez le compte Apple qui est ajouté au compte développeur Apple

5. Trouvez l'équipe que vous utiliserez pour déployer l'application

6. Cliquez sur le bouton Manage Certificates... bouton

7. Vérifiez que vous pouvez voir le certificat de distribution dans la liste

8. Si vous ne le voyez pas, vous devez créer un nouveau certificat

   Remarque

   Apple limite le nombre de certificats de distribution que vous pouvez avoir à 3. Si vous avez plus de 3 certificats, vous devez supprimer un pour créer un nouveau. Je ne couvrirai pas cela dans ce tutoriel.

   1. Cliquez sur le bouton + button et puis sur Apple Distribution
   2. Le certificat sera créé automatiquement. Vous pouvez le voir dans la liste. Regardez l'étape précédente pour vous assurer que vous le voyez.

Maintenant que vous avez le certificat de distribution installé, vous pouvez commencer le processus de build.

Build manuel vers TestFlight

1. Ouvrir l'application dans Xcode

   Exécuter bunx cap open ios Ouvrir l'application dans Xcode.

2. Pour ouvrir l'application dans Xcode. archive button

   Dans la barre d'outils Xcode, recherchez et cliquez sur le product -> archive button.

   

3. Attendez que la construction soit terminée

4. Cliquez sur le Distribute App bouton

   

5. Sélectionnez TestFlight Internal Only comme méthode de distribution et cliquez sur Distribute bouton

   

6. Configurez l'enregistrement de l'application

   Remplissez les champs suivants :

   1. Nom : Le nom de votre application - visible dans l'App Store
   2. SKU - le SKU de votre application - il s'agit de l'identifiant de votre application sur l'App Store
   3. La langue principale - la langue principale de votre application

   Ensuite, cliquez sur le next bouton

   

7. Si la création de l'enregistrement de l'application échoue, essayez de fermer la fenêtre et essayez d'archiver l'application à nouveau.

8. Attendez la fin de l'envoi

9. Si tout s'est bien passé, vous devriez voir l'écran suivant

10. Cliquez sur le Done bouton

Vous pourriez penser instinctivement que tout va bien maintenant et que vous pourrez voir votre application dans TestFlight maintenant, mais il y a encore quelques choses à terminer :

1. Ajoutez-vous à TestFlight
2. Complétez la conformité à l'exportation afin que la construction devienne testable
3. Remplissez les métadonnées App Store Connect obligatoires, telles que votre URL de support, votre politique de confidentialité et votre note d'âge.
4. Préparez des captures d'écran correspondant aux appareils que vous soutenez réellement
5. Ajoutez les coordonnées de contact de la revue d'application et tout les crédentiels de test avant la soumission de production

Commencez par le premier :

Ajouter vous-même à TestFlight

1. Allez à la page App Store Connect page

2. Se connecter avec votre compte développeur Apple

3. Sélectionnez l'équipe que vous avez utilisée lors de la création du dossier d'application. Si vous n'avez qu'un seul compte développeur, vous pouvez passer cette étape.

4. Cliquez sur le Apps bouton

5. Trouvez l'application que vous avez créée dans l'étape précédente et cliquez dessus

6. Cliquez sur le TestFlight bouton

7. Cliquez sur le Internal Testers plus bouton

8. Créer un nouveau groupe

   J'aime nommer le groupe « interne ». Vous pouvez le nommer comme vous le souhaitez.

   

9. Cliquez sur Invite testers bouton

10. Ajoutez-vous au groupe

    Trouvez-vous dans la liste et sélectionnez la case à côté de votre nom. (Vous pouvez avoir besoin de rafraîchir la page pour vous voir) Ensuite, cliquez sur le Add bouton.

    

11. Vérifiez que vous êtes ajouté au groupe

    Vous devriez maintenant vous voir dans le groupe.

    

Félicitations ! Vous avez ajouté votre propre compte à TestFlight. Il ne vous reste plus qu'une chose à faire avant de configurer Capgo Native Build.

Configuration des informations de conformité

Vous devez maintenant promettre à Apple que votre application ne utilise aucune cryptage non standard (comme un algorithme personnalisé). Si votre application utilise une cryptage non standard, je vous conseille de lire la documentation d'Apple sur la façon de gérer cela. Il existe deux façons de procéder :

1. You can do this by hand every time you build your app.
2. Vous pouvez configurer votre fichier plist pour définir automatiquement cette valeur à false.

Commencez par la première option :

1. Suivez toutes les étapes de la section précédente pour trouver la section TestFlight dans App Store Connect

2. Appuyez sur Builds -> iOS

3. Trouvez la build avec des informations de conformité manquantes et appuyez sur Manage

4. Sélectionnez l'option qui décrit le mieux votre application

   Pour moi, c'est nonemais cela pourrait être différent pour vous. Ensuite, cliquez sur Enregistrer

   

5. Votre application devrait maintenant dire ready to test

   

Pour la deuxième étape, voici les étapes :

1. Ouvrir le Info.plist le fichier

2. Ajoutez la clé suivante :

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

3. Sauvegarder le fichier

Remarque

Voici la documentation officielle d'Apple sur la façon d'informer Apple de votre conformité aux réglementations d'exportation de cryptage.

L'installation de l'application TestFlight et l'acceptation de l'invitation

Maintenant, vous êtes PRÈS d'être prêt à tester votre application dans TestFlight. Avant, vous devez faire les choses suivantes :

1. Télécharger l' application TestFlight à partir de l'App Store sur votre appareil iOS/iPadOS
2. Accepter l'invitation pour tester votre application

Je passerai sous silence les détails sur l'installation de l'application TestFlight sur votre appareil. Si vous n'êtes pas sûr de savoir comment installer une application, Google propose des guides excellents sur la façon de le faire.

Pour accepter l'invitation, vous recevrez un courrier électronique de l'Apple avec un lien pour accepter l'invitation.

1. Ouvrez le courrier électronique de l'Apple avec le lien pour accepter l'invitation

2. Cliquez sur View in TestFlight le bouton

3. Cliquez sur le Install bouton

4. Installez l'application sur votre appareil

   Si vous avez déjà installé l'application à l'aide de Xcode, vous pouvez voir l'écran suivant. Cliquez sur le install button.

5. bouton et cliquez dessus

6. Cliquez sur le Open Cliquez sur le bouton et appuyez dessus.

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.

Configuring Capgo Native Build

Il existe quelques choses que vous devez configurer dans la mise en œuvre native Capgo pour pouvoir construire et soumettre votre application à TestFlight. Voici une liste des choses que vous transmettrez au Capgo CLI:

Paramètre	Description
--platform	La plateforme à construire pour (ios)
--apple-team-id	Votre identifiant de développeur Apple (trouvé dans Portail du développeur Apple)
--apple-key	Chemin vers votre fichier de clé API App Store Connect (.p8 fichier)
--apple-key-id	L'ID de clé de votre clé API App Store Connect
--apple-issuer-id	Votre ID émetteur App Store Connect
--certificate	Chemin vers votre certificat de distribution (.p12 fichier)
--ios-provisioning-profile	Mappage de profil de provisionnement (bundleId=path ou simplement chemin pour un profil unique)

Exemple de commande :

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 d'équipe

Commencez par l'ID de l'équipe. Le trouver est relativement facile.

1. Allez à Compte Apple Developer Compte Apple Developer

2. Trouvez la Team ID

   

l'ID de clé Apple, l'ID de clé Apple et l'ID émetteur Apple

Maintenant, passons à la clé Apple.

macOS : laissez Capgo créer cette clé pour vous

Sur macOS, capgo build init peut créer cette clé App Store Connect API pour vous. Choisissez « Non — créez-en une pour moi » et une fenêtre guidée s'ouvre sur App Store Connect, vous guidez chaque étape et capturez automatiquement la clé, l'ID de clé et l'ID émetteur — sans copier-coller. Les étapes manuelles ci-dessous sont l'alternative (et le chemin sur Windows ou Linux).

1. Allez à Page d'utilisateur et de connexion d'App Store Connect

   Note

   Pour moi, le lien ne fonctionne parfois pas. Rechargez la page si cela ne marche pas pour vous.

2. Sélectionnez l'équipe correcte dans le menu déroulant

   1. Cliquez sur votre nom dans le coin supérieur droit
   2. Cliquez sur l'équipe que vous souhaitez utiliser

3. Cliquez sur le bouton Integrations button

4. bouton issuer

   Attention

   Ce Ceci doit être enregistré vous le trouverez utile plus tard

   Cliquez sur le copy bouton pour copier l'identifiant de l'éditeur

5. Cliquez sur le bouton plus

6. Définissez le nom de la clé et définissez l'accès à App manager et cliquez sur le Generate bouton

7. Sauvegardez l'ID de la clé

   Attention

   Ceci C'EST À SAVOIR - vous en aurez besoin plus tard

   

8. Téléchargez la clé

   Attention

   Ceci C'EST À SAVOIR - vous le devrez plus tard

   Attention

   NE PAS PARTAGER LA CLÉ AVEC PERSONNE - L'UTILISER SEULEMENT DANS LE CAPGO CLI

   

   

Félicitations 🎉 Vous avez créé la clé Apple, l'ID de clé Apple et l'ID émetteur Apple.

Certificat

Maintenant, vous êtes prêt à exporter le certificat. Comme vous vous souvenez, l'une des premières étapes de ce guide était la mise en place du certificat de distribution.

Cependant, Apple dans leur sagesse infinie, a décidé que la façon dont vous exportez le certificat est très différente de la façon dont vous les créez 😂 Commençons par configurer cela :

1. Ouvrez Keychain Access

   1. Cliquez Command + Space pour ouvrir la barre de recherche
   2. Recherchez Keychain Access
   3. Cliquez sur le Keychain Access app

2. Sélectionnez la login catégorie et cliquez sur le My Certificates bouton

3. Trouvez votre certificat dans la liste

   Le certificat doit s'appeler Apple Distribution: [Your Name/Company] (your team ID)

4. Right-click on the certificate and select Export

5. Enregistrez le certificat sous forme de .p12 fichier

   Attention

   Ceci DOIT ÊTRE SAUVEGARDÉ - vous en aurez besoin plus tard

   1. Assurez-vous de choisir un bon nom pour le fichier de certificat
   2. Assurez-vous que le format de fichier est défini sur Personal Information Exchange (.p12)
   3. Cliquez sur le Save bouton

   

6. When asked for the password, you can either:

   • Ignorer le mot de passe (recommandé pour la simplicité) : Cliquez OK sans entrer de mot de passe
   • Définir un mot de passe : Si vous préférez protéger votre certificat avec un mot de passe, vous pouvez le définir ici. Mot de passe protégé .p12 Les fichiers sont pleinement pris en charge par le Capgo CLI - il suffit de fournir le mot de passe à l'aide du --p12-password option lors de l'exécution de la commande de configuration.

   

7. Lorsque demandé le mot de passe de la "clé de connexion", entrez le mot de passe que vous utilisez pour vous connecter à votre Mac.

   Entrez le mot de passe que vous utilisez pour vous connecter à votre Mac. Cliquez ensuite sur Allow button.

   

Félicitations ! Vous avez exporté le certificat.

Profil de provisionnement

Maintenant, vous êtes prêt à exporter le profil de provisionnement. Je vous promets, c'est la dernière chose que vous aurez besoin de récupérer auprès d'Apple.

1. Allez à Profils développeurs Apple

2. Sélectionnez l'équipe correcte dans le menu déroulant

   1. Cliquez sur votre nom dans le coin supérieur droit
   2. Appuyez sur l'équipe que vous souhaitez utiliser

3. Assurez-vous d'être sur la bonne page Elle devrait ressembler à ceci, si ce n'est pas le cas, appuyez sur profiles dans le menu latéral

   

4. Appuyez sur le + bouton

5. Sélectionnez le type de profil Sélectionnez App Store Connect et appuyez sur le Continue bouton

   

6. Sélectionnez l'application que vous souhaitez construire

   Trouvez votre application dans le menu déroulant et cliquez sur le Continue bouton

   

7. Sélectionnez le certificat de distribution correct

   Sélectionnez le certificat que vous avez exporté dans l'étape précédente et cliquez sur le Continue bouton

   

   Si vous êtes incertain de savoir quel certificat sélectionner, revenez à Keychain Access et trouvez le certificat que vous avez exporté. Regardez ensuite la date d'expiration.

   

8. Nommez le profil

   Donnez un nom au profil et cliquez sur le Generate bouton

   Conseil

   Le nom de profil est automatiquement extrait par le Capgo CLI — vous n'avez pas besoin de le rappeler.

   

9. Téléchargez le profil

   Cliquez sur le Download bouton pour télécharger le profil

   Attention

   Ce fichier DOIT ÊTRE SAUVEGÉ - Vous aurez besoin de cela plus tard.

   

Félicitations ! Vous avez maintenant tout ce dont vous avez besoin pour configurer Capgo Native Build.

Attention

N'ajoutez jamais ces informations à votre dépôt. Gardez-les en sécurité ! 🔒

Exécution de la commande de configuration

Vous l'avez fait ! Vous avez maintenant tout ce dont vous avez besoin pour configurer Capgo Native Build.

La commande que vous devrez exécuter est :

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

Remplacez les valeurs de remplacement

Remplacez les valeurs de remplacement ci-dessus par vos informations d'identification réelles collectées dans les étapes précédentes :

• --apple-team-id: Votre ID d'équipe Apple
• --apple-key: Chemin vers votre fichier téléchargé .p8 fichier clé
• --apple-key-id: Votre ID émetteur Apple
• --apple-issuer-id: Votre ID émetteur Apple
• --certificate: Chemin vers votre projet exporté .p12 certificate
• --ios-provisioning-profile: Chemin vers votre fichier téléchargé .mobileprovision fichier (ID de bundle automatiquement inféré pour les profils uniques)

Si tout s'est bien passé, vous devriez voir le résultat suivant :

Apple auth failed? Sync your clock

Si la clé API d'App Store Connect semble correcte mais que l'authentification continue à échouer, synchronisez votre horloge de l'ordinateur et réessayez. Capgo signe le JWT d'Apple avec l'heure système locale, et Apple rejette les jetons qui expirent dans les 20 minutes à venir. Un horloge qui est seulement quelques secondes hors synchronisation peut suffire à échouer cette étape.

Voir le guide de dépannage du constructeur pour les étapes de synchronisation de l'horloge.

Configuration CI/CD (GitHub Actions)

Si vous avez déjà complété ID d'équipe, Apple key, Apple key ID et Apple ID émetteur, Certificat, et Profil de provisionnementVous avez déjà tout ce qu'il vous faut pour CI/CD. Cette section ne couvre que la façon de passer ces valeurs sous forme de secrets d'actions GitHub et de variables d'environnement.

1) Convertir les fichiers de credenciaux en base64 à une ligne unique

# 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

les secrets GitHub doivent être des valeurs sur une ligne. tr -d '\n' supprime les sauts de ligne de la sortie base64.

2) Créez des secrets de dépôt

Dans GitHub > Repository > Settings > Secrets and variables > Actions, ajoutez :

Nom du secret	Valeur
CAPGO_TOKEN	Votre jeton Capgo API
APP_STORE_CONNECT_TEAM_ID	ID d'équipe depuis ID d'équipe
APPLE_KEY_ID	ID de clé depuis Clé Apple, ID de clé Apple et ID émetteur Apple
APPLE_ISSUER_ID	Identifiant émetteur depuis Clé Apple, ID de clé Apple et ID émetteur Apple
BUILD_CERTIFICATE_BASE64	Contenu de certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Généré par CLI — copier depuis .capgo-credentials fichier
APPLE_KEY_CONTENT	Contenu de apple_key_base64.txt
P12_PASSWORD (facultatif)	Votre .p12 mot de passe si défini lors de l'exportation

3) Use env vars in your 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 }}

Conseil

With this setup, CI sends credentials through environment variables only. You do not need to commit signing files or upload them as workflow artifacts.

Exécution de la construction

Maintenant, vous êtes prêts à lancer votre première build.

Exécutez la commande suivante pour construire votre application :

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

Félicitations 🎉 À ce stade, vous avez réussi à construire votre application et elle est prête à être soumise à la revue de l'App Store.

Soumettre à la revue de l'App Store

La voie de construction normale de l'App Store envoie la construction à App Store Connect/TestFlight. Si votre lancement CI doit également attacher la construction traitée de TestFlight à la version de l'App Store et la soumettre à la revue, passez --submit-to-store-review Avec une mise en production :

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

Cette opération nécessite les clés de connexion App Store Connect API (APPLE_KEY_ID, APPLE_ISSUER_ID, APPLE_KEY_CONTENT, and APP_STORE_CONNECT_TEAM_IDTéléchargements de mot de passe d'application et ad_hoc est la version de l'App Store ; si omis, --store-release-name C'est la version de l'App Store ; si elle est omise, Capgo lit MARKETING_VERSION est le texte What’s New de l'App Store par défaut, et chaque --store-release-notes est le texte What’s New de l'App Store par défaut, et chaque --store-release-notes-locale "locale=notes" l'entrée peut le remplacer pour une localisation de magasin. Utilisez --ios-automatic-release pour libérer automatiquement après l'approbation d'Apple, ou --no-ios-automatic-release pour attendre une mise à jour manuelle. --ios-testflight-groups est toujours disponible pour la distribution bêta externe, mais il n'est pas requis pour la soumission de la revue de l'App Store.

Mode de distribution Ad-Hoc

Par défaut, les Capgo construisent des applications iOS pour la distribution de l'App Store (TestFlight + App Store). Si vous avez besoin de builds ad-hoc au lieu (pour des tests internes ou la collecte d'artefacts CI), vous pouvez utiliser le --ios-distribution flag.

Note

La distribution ad-hoc n'est pas le même que la distribution Enterprise (en interne). La distribution Enterprise nécessite un compte Apple Developer Enterprise séparé et utilise des profils de provisionnement différents. Capgo prend actuellement en charge app_store et ad_hoc seulement en mode.

Quand utiliser le mode ad-hoc

• Vous souhaitez distribuer des IPAs directement aux appareils enregistrés (pas TestFlight)
• Vous n'avez pas ou ne voulez pas utiliser une clé API App Store Connect
• Vous souhaitez collecter des artefacts de construction via --output-upload sans soumettre à l'App Store

Exigences

Les builds ad-hoc ont moins de exigences que les builds de l'App Store :

Authentification	Required?
Certificat de distribution (.p12)	Oui
Profil de provisionnement ad-hoc (".mobileprovision)	Oui
ID d'équipe (--apple-team-id)	Oui
Clé App Store Connect API (.p8)	No
Clé ID Apple / ID émetteur	Non

Remarque

En ad_hoc mode, --apple-key, --apple-key-idet --apple-issuer-id ne sont pas pris en charge et sont ignorés. C'est pourquoi les deux lignes App Store Connect ci-dessus ne montrent pas les drapeaux ad-hoc CLI ; ces options s'appliquent uniquement app_store mode.

Prudence

Sans clé API d'App Store Connect, le numéro de build utilise un fallback basé sur la date et l'heure. Pour supprimer l'avertissement, passez --skip-build-number-bump.

Création d'un profil de provisionnement ad-hoc

Suivez les mêmes étapes que Profil de provisionnementProfil de provisionnement Ad Hoc Ad Hoc au lieu de:

1. App Store Profils Apple Developer
2. Cliquez sur + Cliquez sur le
3. Sélectionner Ad Hoc Cliquez sur Continuer
4. Sélectionnez votre application et votre certificat de distribution
5. Sélectionnez les appareils que vous souhaitez enregistrer
6. Nommez et téléchargez le profil

Enregistrement des informations d'identification 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'

Non --apple-key, --apple-key-id, ou --apple-issuer-id nécessaire.

Exécuter une build ad-hoc

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

Pour collecter l'IPA en tant qu'artifact de build, ajoutez --output-upload:

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

CI/CD avec des builds ad-hoc

Pour les GitHub Actions, vous avez besoin de moins de secrets que les builds de l'App Store :

github/flux de travail/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

Conseil

Notez que APPLE_KEY_ID, APPLE_ISSUER_ID, et APPLE_KEY_CONTENT ne sont pas nécessaires pour les builds ad-hoc.

Applications avec Extensions (Signature Multi-Cible)

Si votre application comprend des extensions (extensions de partage, widgets, extensions de services de notification, etc.), chaque cible d'extension nécessite son propre profil de provisioning. Capgo prend en charge cela via la flag répétitive. --ios-provisioning-profile flag.

Section intitulée « Exemple : Application + Extension de partage »

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"

Chacun --ios-provisioning-profile La balise maps un ID de bundle à son fichier de profil de provisioning. Le CLI:

1. Lis chaque fichier mobileprovision
2. Extrait automatiquement le nom de profil à partir du plist intégré
3. Encode en Base64 le fichier
4. Stocke tout cela sous forme de fichier unique CAPGO_IOS_PROVISIONING_MAP credential

Conseil

Vous avez besoin d'un seul certificat de distribution pour tous les cibles — seuls les profils de provisioning diffèrent par cible.

Migration depuis un Profil Unique

Si vous avez utilisé précédemment BUILD_PROVISION_PROFILE_BASE64 (exécutez avec un profil unique), exécutez :

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

Après la migration, ajoutez des profils d'extension avec la commande (fusion additive) : CAPGO_IOS_PROVISIONING_MAP formatte et supprime les clés legacy ("BUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

Après la migration, ajoutez des profils d'extension avec le update commande (fusion additive) :

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

Conseil

Utilisez update (pas saveAjouter des profils aux informations d'identification existantes. update commande fusionne de nouveaux profils avec les profils existants. Utilisez save seulement lors de la configuration de tous les identifiants depuis zéro.

Troubleshooting

Le profil de provisionnement ne comprend pas la capacité XYZ.

Parfois, vous pouvez voir le message d'erreur suivant :

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

Cela se produit car vous avez activé une nouvelle capacité après la création du profil de provisionnement. Le profil de provisionnement ancien ne comprend pas encore la nouvelle capacité.

Pour résoudre ce problème, vous devez régénérer le profil de provisionnement.

1. Ouvrir Portail du développeur Apple
2. Sélectionnez l'équipe correcte dans le menu déroulant
3. Cliquez sur le Profiles bouton
4. Trouvez le profil de provisionnement que vous souhaitez régénérer
5. Cliquez sur le bouton Edit bouton
6. Cliquez sur le bouton Save bouton
7. Cliquez sur le bouton Download bouton
8. Re-run the Capgo Native Build setup command Cela devrait résoudre le problème.

Cela devrait résoudre le problème.

Autres problèmes

Si, pour une raison quelconque, vous rencontrez des problèmes avec la construction native de Capgo, la configuration des informations d'identification ou la construction de l'application, n'hésitez pas à nous contacter via notre support.

Continuez à partir des constructions iOS

Si vous utilisez Constructions iOS pour planifier l'automatisation CI/CD, connectez-l’avec Capgo CI/CD pour le flux de travail du produit dans Capgo CI/CD, Capgo Constructions natives pour le flux de travail du produit dans les Capgo Builds natifs, les Capgo Intégrations pour le flux de travail du produit dans Capgo Intégrations, Intégration CI/CD pour les détails d'implémentation dans l'Intégration CI/CD, et les GitHub Actions d'intégration pour les détails d'implémentation dans les GitHub Actions d'intégration.