Build iOS

Build and submit iOS apps to TestFlight and the App Store using Capgo’s dedicated Mac infrastructure.

Judul bagian “Apa yang akan Anda pelajari”

• Anda akan belajar bagaimana mengunggah aplikasi melalui Capgo Build Nativ
• Anda akan belajar bagaimana mengonfigurasi sertifikat untuk Capgo Build Nativ

Persyaratan

• Akun Capgo (cukup uji coba gratis untuk memulai)
• Aplikasi Anda sudah terdaftar di Capgo (jalankan bunx @capgo/cli@latest app add jika belum)
• Komputer Mac dengan Xcode terinstal (mungkin untuk mengatur build pada mesin linux/windows, tetapi belum terdokumentasi)
• Akun Pengembang Apple yang valid ($99/tahun) (Anda harus memiliki hak admin atau hak pemilik pada akun Pengembang Apple)
• Aplikasi Anda harus dapat dibangun dengan sukses melalui Xcode
• Aplikasi Capacitor
• Ikon yang telah dikonfigurasi untuk aplikasi. Aplikasi tanpa ikon tidak dapat diunggah ke App Store.

Catatan

Saya akan menggunakan aplikasi berikut untuk tutorial: https://github.com/Cap-go/capgo-native-build-tutorial-app

Sebelum Anda memulai di portal Apple

Sebelum Anda mengatur sertifikat atau mengaktifkan unggahan TestFlight pertama, pastikan akun dan tim Apple sudah siap:

• Aktifkan autentikasi dua faktor untuk Akun Apple yang digunakan untuk pendaftaran
• Pilih jenis keanggotaan yang tepat:
  • Individu / Pemilik Usaha SendiriNama pribadi Anda menjadi nama penjual di App Store
  • Organisasi: memerlukan entitas hukum, nomor D-U-N-S, situs web perusahaan publik, alamat email kerja di domain perusahaan, dan orang yang berwenang untuk mengikat organisasi ke perjanjian Apple
• Pilih akun yang dapat mengakses baik Apple Developer maupun App Store Connect untuk sertifikat, catatan aplikasi, API kunci, dan TestFlight
• Pastikan ID paket akhir Anda sejak awal. Mengubahnya kemudian biasanya berarti melakukan setup App Store ulang
• Rencanakan item App Store Connect ini sebelum App Review: URL dukungan, URL kebijakan privasi, klasifikasi usia, screenshot, kewajiban ekspor, dan detail kontak App Review

Catatan

Sumber referensi resmi yang berguna:

• Jadilah anggota dari Program Pengembang Apple
• Kirimkan aplikasi dan game Anda
• Informasi versi platform di App Store Connect

Peringatan

Apple updates its minimum SDK requirement regularly. As of Apple memperbarui persyaratan minimum __CAPGO_KEEP_0__ secara teratur. Sebagai contoh, padaApril 28, 2026 iOS & iPadOS 26 SDK or later.

Dianjurkan: onboarding otomatis

You don’t have to do any of this by hand. Capgo’s onboarding creates and configures your iOS signing credentials (distribution certificate + provisioning profile) for you — this is the recommended path:

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

Petunjuk manual di bawah ini hanya untuk mereka yang lebih suka mengatur kredit sendiri, atau ingin memahami secara tepat apa Capgo lakukan di balik layar.

Pembangunan manual pertama

Sebelum kita bisa memulai berpikir tentang membangun aplikasi dengan Capgo, kita harus terlebih dahulu mengatur dan melakukan pembangunan TestFlight pertama secara manual. Ada beberapa kelebihan melakukan pembangunan manual pertama:

• Anda akan mengatur sertifikat distribusi pada mesin lokal Anda
• Anda akan membuat catatan App Store jika belum melakukannya sebelumnya
• Anda akan dapat mengetahui masalah-masalah dengan proses pembangunan yang terkait dengan aplikasi code

Sebelum kita bisa memulai, Anda harus memiliki sertifikat distribusi terinstal pada mesin lokal Anda. Hal ini cukup kompleks, tetapi saya akan menjelaskannya di bawah ini.

Mengatur sertifikat distribusi

1. Buka Xcode

2. Klik pada Xcode -> Settings... Atau, Anda dapat menggunakan pintasan Cmd + ,

   

3. Buka Accounts

4. Cari Akun Apple yang ditambahkan ke Akun Pengembang Apple

5. Cari tim yang akan digunakan untuk mengirimkan aplikasi

6. Klik pada tombol Manage Certificates... button

7. Pastikan Anda dapat melihat sertifikat distribusi di daftar

8. Jika Anda tidak melihatnya, Anda perlu membuat sertifikat baru

   Catatan

   Apple memiliki batasan jumlah sertifikat distribusi yang dapat Anda miliki hingga 3. Jika Anda memiliki lebih dari 3 sertifikat, Anda perlu menghapus salah satu untuk dapat membuat sertifikat baru. Saya tidak akan menjelaskannya dalam tutorial ini.

   1. Klik pada tombol + dan kemudian pada Apple Distribution
   2. Sertifikat akan dibuat secara otomatis. Anda dapat melihatnya di daftar. Lihat langkah sebelumnya untuk memastikan Anda melihatnya.

Sekarang Anda telah menginstal sertifikat distribusi, Anda dapat memulai proses pembangunan.

Pembangunan manual ke TestFlight

1. Buka aplikasi di Xcode

   Run bunx cap open ios untuk membuka aplikasi di Xcode.

2. Cari dan klik tombol archive button

   Di toolbar Xcode, cari dan klik tombol product -> archive button.

   

3. Tunggu proses build selesai

4. Klik tombol Distribute App button

   

5. Pilih TestFlight Internal Only sebagai metode distribusi dan klik pada Distribute tombol

   

6. Konfigurasi rekaman aplikasi

   Isi bidang berikut:

   1. Nama: Nama aplikasi Anda - terlihat di App Store
   2. SKU - Kode SKU aplikasi Anda - ini digunakan untuk mengidentifikasi aplikasi Anda di App Store
   3. Bahasa utama - bahasa utama aplikasi Anda

   Lalu, klik pada next tombol

   

7. Jika pembuatan rekaman aplikasi gagal, coba tutup jendela dan coba arsip aplikasi lagi.

8. Tunggu hingga upload selesai

9. Jika semuanya berjalan lancar, Anda seharanya akan melihat layar berikut

10. Klik pada tombol Done Anda mungkin secara naluriah berpikir bahwa semuanya baik-baik saja sekarang dan Anda akan dapat melihat aplikasi Anda di TestFlight sekarang, tetapi ada beberapa hal lain yang masih harus diselesaikan:

Tambahkan diri Anda ke TestFlight

1. Lengkapi ketentuan ekspor untuk membuat build menjadi dapat diuji
2. Isi metadata App Store Connect yang diperlukan seperti URL dukungan, URL kebijakan privasi, dan klasifikasi usia
3. Siapkan screenshot yang sesuai dengan perangkat yang Anda dukung
4. Konfigurasi Xcode TestFlight untuk merekam aplikasi
5. Tambahkan detail kontak App Review dan kredit uji sebelum pengiriman produksi

Mari kita mulai dengan yang pertama:

Menambahkan diri Anda ke TestFlight

1. Pergi ke halaman App Store Connect halaman

2. Masuk dengan akun Pengembang Apple Anda

3. Pilih tim yang Anda gunakan ketika membuat catatan aplikasi. Jika Anda hanya memiliki satu akun pengembang, Anda dapat melewatkan langkah ini.

4. Klik pada Apps button

5. Cari aplikasi yang Anda buat di langkah sebelumnya dan klik pada tombolnya

6. Klik pada tombol TestFlight button

7. Klik pada tombol Internal Testers plus button

8. Buat kelompok baru

   Saya suka menamai kelompok “internal”. Anda dapat menamainya apa saja.

   

9. Klik pada Invite testers tombol

10. Tambahkan diri Anda ke grup

    Cari diri Anda di daftar dan pilih kotak centang di samping nama Anda. (Mungkin Anda perlu memperbarui halaman untuk melihat diri Anda) Lalu, klik pada Add tombol.

    

11. Pastikan Anda telah ditambahkan ke grup

    Sekarang, Anda harus melihat diri Anda di grup.

    

Selamat 🎉 Anda telah menambahkan diri Anda ke TestFlight. Sekarang, ada satu hal lagi yang Anda perlu lakukan sebelum Anda dapat mengonfigurasi Capgo Native Build.

Menyiapkan informasi kesesuaian

Anda sekarang perlu berjanji kepada Apple bahwa aplikasi Anda tidak menggunakan enkripsi non-standar (seperti algoritma kustom). Jika aplikasi Anda memang menggunakan enkripsi non-standar, saya sarankan membaca documentasi Apple untuk mengetahui cara mengatasi hal ini. Ada dua cara untuk melakukannya:

1. Anda dapat melakukannya secara manual setiap kali Anda membangun aplikasi.
2. Anda dapat mengonfigurasi file plist Anda untuk mengatur nilai ini secara otomatis ke false.

Mari kita mulai dengan cara pertama:

1. Ikuti semua langkah dari bagian sebelumnya untuk menemukan bagian TestFlight di App Store Connect

2. Klik pada Builds -> iOS

3. Cari build dengan informasi kesesuaian yang hilang dan klik pada Manage

4. Pilih opsi yang paling baik menggambarkan aplikasi Anda

   Bagi saya, ini adalah noneTapi mungkin berbeda untuk Anda. Setelah itu, klik simpan

   

5. Aplikasi Anda seharusnya sekarang mengatakan ready to test

   

Mengenai yang kedua, berikut adalah langkah-langkah:

1. Buka file Info.plist Tambahkan kunci berikut:

2. Salin ke klipbord

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

3. Simpan file ini

Catatan

Di sini adalah dokumentasi resmi Apple tentang cara menginformasikan Apple tentang kewajiban Anda untuk mengikuti regulasi ekspor enkripsi.

Menginstal aplikasi TestFlight dan menerima undangan

Sekarang, Anda HAMPIR sudah siap untuk menguji aplikasi Anda di TestFlight. Sebelumnya, Anda perlu melakukan hal-hal berikut:

1. Unduh aplikasi TestFlight dari App Store pada perangkat iOS/iPadOS Anda
2. Terima undangan untuk menguji aplikasi Anda

Saya akan melewatkan detail tentang cara menginstal aplikasi TestFlight pada perangkat Anda. Jika Anda tidak yakin cara menginstal aplikasi, Google memiliki beberapa panduan yang bagus tentang cara melakukannya.

Untuk menerima undangan, Anda akan menerima surel dari Apple dengan tautan untuk menerima undangan.

1. Buka surel dari Apple dengan tautan untuk menerima undangan

2. Klik pada View in TestFlight tombol

3. Klik pada tombol Install tombol

4. Instal aplikasi pada perangkat Anda

   If Anda telah menginstal aplikasi sebelumnya menggunakan Xcode, Anda mungkin melihat layar berikut. Silakan klik pada tombol. install button.

5. Tunggu aplikasi terinstal

6. Klik pada tombol dan klik tombol tersebut Open Selamat 🎉 Anda telah menerima undangan untuk menguji aplikasi Anda di TestFlight. Sekarang, Anda dapat mengonfigurasi __CAPGO_KEEP_0__ Build Natively untuk membangun dan mengirimkan aplikasi ke TestFlight.

Mengonfigurasi Capgo Build Natively

Bagian berjudul “Mengonfigurasi Capgo Build Natively”

There are a few things you need to configure in Capgo Native Build to be able to build and submit your app to TestFlight. Here is a list of the things you will pass to the Capgo CLI:

Deskripsi	Parameter 1 untuk __CAPGO_KEEP_1__ __CAPGO_KEEP_2__
--platform	Platform untuk membangun (ios)
--apple-team-id	ID Tim Pengembang Apple Anda (ditemukan di Portal Pengembang Apple)
--apple-key	Jalur ke API File Kunci App Store Connect Anda (.p8 file)
--apple-key-id	The Key ID of your App Store Connect API Key
--apple-issuer-id	ID Pengemudang App Store Connect Anda
--certificate	Jalur ke sertifikat distribusi Anda (.p12 file)
--ios-provisioning-profile	Peta profil pengaturan (bundleId=path atau hanya jalur untuk profil tunggal)

Contoh perintah:

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 Tim

Mari kita mulai dengan ID tim. Mencarinya cukup mudah.

1. Pergi ke Akun Pengembang Apple dan gulir ke bawah

2. Cari lokasi Team ID

   

Kunci Apple, ID Kunci Apple dan ID Pengembang Apple

Sekarang, mari kita lanjutkan ke kunci Apple.

1. Pergi ke Halaman akses pengguna dan App Store Connect

   Catatan

   Untuk saya, link ini tidak selalu berfungsi. Jika tidak berfungsi untuk Anda, muat ulang halaman ini.

2. Pilih tim yang benar di dropdown

   1. Klik nama Anda di sudut kanan atas
   2. Klik tim yang ingin Anda gunakan

3. Klik pada Integrations tombol

4. Temukan issuer

   Peringatan

   Ini IS TO BE SAVED - Anda memerlukan nanti

   Klik pada tombol copy untuk menyalin penerbit

5. Klik pada tombol plus

6. Atur nama kunci dan atur akses ke App manager dan klik pada tombol Generate button

7. Simpan ID kunci

   Peringatan

   Hal ini PERLU DI SIMPAN - Anda akan membutuhkannya nanti

   

8. Unduh kunci

   Peringatan

   Ini DIPERLUKAN UNTUK DISIMPAN - Anda akan membutuhkannya nanti

   Bahaya

   TIDAK PERNAH BERBAHAGIAKAN KUNCI DENGAN SIAPA PUN - HANYA GUNAKANNYA DI DALAM CAPGO CLI

   

   

Selamat 🎉 Anda telah membuat kunci Apple, ID kunci Apple, dan ID penerbit Apple.

Sertifikat

Sekarang, Anda sudah siap untuk mengexport sertifikat. Seperti yang Anda ingat, salah satu langkah awal dari panduan ini adalah mengatur sertifikat distribusi.

Namun, Apple dalam kebijakan mereka yang tidak terbatas, memutuskan bahwa cara Anda mengexport sertifikat sangat berbeda dari cara Anda membuatnya

1. Buka Akses Kunci

   1. Klik Command + Space untuk membuka bar pencarian
   2. Cari Keychain Access
   3. Klik pada Keychain Access aplikasi

2. Pilih kategori dan klik pada login Sertifikat My Certificates button

3. Cari sertifikat Anda di daftar

   Sertifikat harus bernama Apple Distribution: [Your Name/Company] (your team ID)

4. Klik kanan pada sertifikat dan pilih Export

5. Simpan sertifikat sebagai .p12 file

   Peringatan

   Ini Untuk Disimpan - Anda akan membutuhkannya nanti

   1. Pastikan untuk memilih nama yang baik untuk file sertifikat
   2. Pastikan format file telah disetel ke Personal Information Exchange (.p12)
   3. Klik pada tombol Save button

   

6. Ketika diminta untuk memasukkan kata sandi, Anda dapat memilih:

   • Melewati kata sandi (direkomendasikan untuk kesederhanaan): Klik OK tanpa memasukkan kata sandi
   • Setel kata sandi: Jika Anda lebih suka melindungi sertifikat Anda dengan kata sandi, Anda dapat menyetelnya di sini. File yang dilindungi kata sandi sepenuhnya didukung oleh __CAPGO_KEEP_0__ __CAPGO_KEEP_1__ - cukup berikan kata sandi menggunakan .p12 files are fully supported by the Capgo CLI - just provide the password using the --p12-password pilihan ketika menjalankan perintah konfigurasi.

   

7. Ketika diminta untuk “kata sandi keychain login”, berikan kata sandi yang Anda gunakan untuk masuk ke Mac Anda

   Berikan kata sandi yang Anda gunakan untuk masuk ke Mac Anda. Kemudian, klik pada tombol Allow tombol

   

Hore! 🎉 Sertifikat telah diekspor.

Profil Pengaturan

Sekarang, Anda sudah siap untuk mengexport profil pengaturan. Saya berjanji, ini adalah hal terakhir yang Anda perlu dapatkan dari Apple.

1. Pergi ke Profildan Pengembang Apple

2. Pilih tim yang benar di dropdown

   1. Klik nama Anda di sudut kanan atas
   2. Klik tim yang ingin Anda gunakan

3. Pastikan Anda berada di halaman yang benar Halaman ini harus seperti ini, jika tidak klik pada profiles di sidebar

   

4. Klik pada + Tombol

5. Pilih jenis profil Pilih App Store Connect dan klik pada Continue button

   

6. Pilih Aplikasi yang Anda Inginkan untuk Dibangun

   Cari aplikasi Anda di dropdown dan klik pada Continue button

   

7. Pilih Sertifikat Distribusi yang Benar

   Pilih sertifikat yang Anda ekspor di langkah sebelumnya dan klik pada Continue button

   

   Jika Anda tidak yakin sertifikat mana yang harus dipilih, kembali ke Akses Kunci dan cari sertifikat yang Anda ekspor. Kemudian lihat tanggal kadaluarsa.

   

8. Nama profil

   Berikan nama profil dan klik tombol Generate Tombol

   Tips

   Nama profil secara otomatis diekstrak oleh Capgo CLI — Anda tidak perlu mengingatnya.

   

9. Unduh profil

   Klik tombol untuk mengunduh profil Download Peringatan

   Peringatan

   File ini PERLU DI SIMPAN - Anda akan membutuhkannya nanti

   

Selamat 🎉 Anda telah memiliki segala sesuatu yang diperlukan untuk mengonfigurasi Capgo Native Build.

Peringatan

Jangan pernah mengkomit kredential yang baru saja dibuat ke repositori Anda. Simpanlah mereka dengan aman! 🔒

Menggunakan perintah pengaturan

Anda telah melakukannya! Anda telah memiliki segala sesuatu yang diperlukan untuk mengonfigurasi Capgo Native Build.

Perintah yang akan Anda butuhkan untuk menjalankannya adalah:

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

Ganti nilai tempat pengganti

Ganti nilai-nilai tempat pengganti di atas dengan kreditual asli Anda yang dikumpulkan dalam langkah-langkah sebelumnya:

• --apple-team-idID Tim Apple Anda
• --apple-key: Jalur ke file kunci Anda yang diunduh .p8 ID Kunci Apple Anda
• --apple-key-idID Pengirim Apple Anda
• --apple-issuer-id: Jalur ke sertifikat Anda yang diekspor']}
• --certificatekey file .p12 : Path to your exported certificate
• --ios-provisioning-profile: Jalur ke file yang telah diunduh .mobileprovision file (ID paket otomatis ditentukan untuk profil tunggal)

Jika semuanya berjalan dengan baik, Anda akan melihat output berikut:

Pengaturan CI/CD (GitHub Aksi)

Jika Anda telah menyelesaikan ID Tim, Kunci Apple, ID kunci Apple, dan ID penerbit Apple, Sertifikat, dan Profil pengaturananda sudah memiliki semua yang dibutuhkan untuk CI/CD. Bagian ini hanya menjelaskan cara mengirimkan nilai-nilai tersebut sebagai rahasia GitHub Actions dan variabel lingkungan.

1) Konversi file kredit ke base64 tunggal baris

# 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

Trik

Rahasia GitHub harus berupa nilai tunggal baris. tr -d '\n' menghilangkan baris-baris dari hasil base64.

2) Buat rahasia repository

Dalam GitHub > Repository > Settings > Secrets and variables > Actions, tambahkan:

Nama rahasia	Nilai
CAPGO_TOKEN	Token Anda Capgo API
APP_STORE_CONNECT_TEAM_ID	ID Tim dari ID Tim
APPLE_KEY_ID	ID Kunci dari Kunci Apple, ID Kunci Apple dan ID Penerbit Apple
APPLE_ISSUER_ID	ID Penerbit dari Kunci Apple, ID Kunci Apple dan ID Penerbit Apple
BUILD_CERTIFICATE_BASE64	Isi dari certificate_base64.txt
CAPGO_IOS_PROVISIONING_MAP	Dibuat oleh CLI — salin dari .capgo-credentials file
APPLE_KEY_CONTENT	Isi Konten apple_key_base64.txt
P12_PASSWORD (opsional)	Anda .p12 kata sandi jika telah ditetapkan selama ekspor

3) Gunakan variabel lingkungan di dalam GitHub Actions workflow Anda

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

Tips

Dengan konfigurasi ini, CI mengirimkan kunci keamanan melalui variabel lingkungan saja. Anda tidak perlu mengkomit file tanda tangan atau mengunggahnya sebagai artefak workflow.

Running the build

Sekarang, Anda sudah siap untuk menjalankan build pertama Anda.

Jalankan perintah berikut untuk membangun aplikasi Anda:

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

Pengumuman 🎉 Pada tahap ini, Anda telah berhasil membangun aplikasi Anda dan siap untuk disubmit ke App Store.

Mode Distribusi Ad-Hoc

Oleh default, Capgo membangun aplikasi iOS untuk distribusi App Store (TestFlight + App Store). Jika Anda membutuhkan build ad-hoc (untuk pengujian internal atau pengumpulan artefak CI), Anda dapat menggunakan --ios-distribution flag.

Catatan

Penyebaran ad-hoc bukanlah sama dengan Enterprise (Dalam Ruangan) penyebaran. Penyebaran Enterprise memerlukan akun Apple Developer Enterprise yang terpisah dan menggunakan profil provisioning yang berbeda. Capgo saat ini mendukung __CAPGO_KEEP_0__ hanya mode. Kapan menggunakan mode ad-hoc 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 Anda ingin menyebarluaskan IPAs secara langsung ke perangkat yang terdaftar (tidak melalui TestFlight) ad_hoc Anda tidak memiliki atau tidak ingin menggunakan kunci __CAPGO_KEEP_0__ App Store Connect

Anda ingin mengumpulkan artefak pembangunan melalui

• Penggunaan ad-hoc mode dapat membantu Anda menguji aplikasi di lingkungan yang lebih realistis sebelum mengirimkannya ke App Store.
• You don’t have or don’t want to use an App Store Connect API key
• Anda dapat menggunakan mode ad-hoc untuk menguji aplikasi di lingkungan yang lebih realistis sebelum mengirimkannya ke App Store. --output-upload Anda dapat menggunakan mode ad-hoc untuk mendistribusikan aplikasi ke perangkat yang telah terdaftar tanpa melalui App Store.

Persyaratan

Ad-hoc build memiliki persyaratan yang lebih sedikit dibandingkan dengan build App Store:

Kredensial	Diperlukan?
Sertifikat distribusi (.p12)	Iya
Profil distribusi ad-hoc (.mobileprovision)	Iya
ID Tim (--apple-team-id)	Ya
App Store Connect API kunci (.p8)	Tidak
ID Apple / Pengembang ID	Tidak

Catatan

Di ad_hoc mode, --apple-key, --apple-key-iddan --apple-issuer-id tidak didukung dan diabaikan. Itulah mengapa dua baris App Store Connect di atas tidak menampilkan flag ad-hoc CLI; opsi-opsi ini hanya berlaku pada app_store mode saja.

Peringatan

Tidak memiliki kunci API App Store Connect, nomor build otomatis akan menggunakan fallback berdasarkan timestamp. Untuk menghilangkan peringatan, pass --skip-build-number-bump.

Membuat profil provisioning ad-hoc

Ikuti langkah-langkah yang sama seperti Profil provisioning, tapi pada langkah 5, pilih Ad Hoc sebaliknya dari App Store:

1. Lihat di Profildiri Pengembang Apple
2. Klik tombol + button
3. Pilih Ad Hoc dan klik Lanjutkan
4. Pilih aplikasi dan sertifikat distribusi Anda
5. Pilih perangkat yang ingin Anda daftarkan
6. Nama dan download profil

Menghemat kredit 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'

Tidak --apple-key, --apple-key-idatau --apple-issuer-id diperlukan.

Membuat build ad-hoc

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

Untuk mengumpulkan IPA sebagai artefak build, tambahkan --output-upload:

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

Penggunaan CI/CD dengan build ad-hoc

Untuk GitHub Aksi, Anda memerlukan rahasia lebih sedikit daripada pembangunan 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

Trik

Perhatikan bahwa APPLE_KEY_ID, APPLE_ISSUER_ID, dan APPLE_KEY_CONTENT tidak diperlukan untuk pembangunan ad-hoc.

Aplikasi dengan Ekstensi (Tanda Tangan Multi-Target)

Jika aplikasi Anda termasuk ekstensi (ekstensi berbagi, widget, ekstensi layanan pemberitahuan, dll.), setiap target ekstensi memerlukan profil pengaturan sendiri. Capgo mendukung hal ini melalui repeatable --ios-provisioning-profile flag.

Contoh: Aplikasi + Ekstensi Bagikan

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"

Setiap --ios-provisioning-profile flag mewakili ID aplikasi ke profil pengaturan file-nya. Profil pengaturan file-nya disimpan di CLI:

1. Membaca setiap file mobileprovision
2. Mengextract profil secara otomatis dari plist yang diintegrasikan
3. Meng-encode file dalam format Base64
4. Menyimpan semua sebagai satu CAPGO_IOS_PROVISIONING_MAP kredensial

Tips

Anda memerlukan satu sertifikat distribusi untuk semua target — hanya profil pengaturan yang berbeda per target.

Migrasi dari Profil Tunggal

Jika Anda sebelumnya menggunakan BUILD_PROVISION_PROFILE_BASE64 (profil tunggal), jalankan:

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

Ini mengonversi kredit Anda yang ada ke format baru dan menghapus kunci legasi ( CAPGO_IOS_PROVISIONING_MAP Setelah migrasi, tambahkan profil ekstensi denganBUILD_PROVISION_PROFILE_BASE64, APPLE_PROFILE_NAME).

__CAPGO_KEEP_0__ update perintah (penyatuan tambahan):

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

Trik

Pakai update (bukan save) untuk menambahkan profil ke kredit yang sudah ada. Perintah ini menyatukan profil baru dengan yang sudah ada. Gunakan update hanya ketika mengatur semua kredit dari awal. save Pengaturan

Bab berjudul “Pengaturan”

Profil pengaturan tidak termasuk kemampuan XYZ.

Kadang-kadang, Anda mungkin melihat pesan kesalahan berikut:

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

Hal ini terjadi karena Anda telah mengaktifkan kemampuan baru setelah profil pengaturan dibuat. Profil pengaturan lama tidak termasuk kemampuan baru belum.

Untuk memperbaiki hal ini, Anda perlu menghasilkan ulang profil pengaturan.

1. Buka Portal Pengembang Apple
2. Pilih tim yang benar di dropdown
3. Klik pada tombol Profiles button
4. Cari profil pengaturan yang ingin Anda regenerasi
5. Klik pada tombol Edit button
6. Klik pada tombol Save button
7. Klik pada tombol Download button
8. Jalankan ulang perintah Capgo Pembangunan Nama Asli untuk mengatur ulang setup. dengan profil yang baru saja diunduh.

Ini harus dapat memperbaiki masalah.

Lain-lain masalah

Jika Anda mengalami masalah apa pun, baik itu dengan Capgo Pembangunan Nama Asli, pengaturan kredit, atau pembangunan aplikasi, silakan hubungi kami melalui dukungan.

Lanjutkan dari Pembangunan iOS

Jika Anda menggunakan Pembangunan iOS untuk merencanakan otomatisasi CI/CD, hubungkan dengan Capgo Pengujian Integrasi untuk alur kerja produk di Capgo Pengujian Integrasi, Capgo Pembangunan Nativ untuk alur kerja produk di Capgo Pembangunan Nativ, Capgo Integrasi untuk alur kerja produk di Capgo Integrasi, Pengintegrasian CI/CD untuk detail implementasi di Pengintegrasian CI/CD, dan GitHub Pengintegrasian Aksi untuk detail implementasi di GitHub Pengintegrasian Aksi.