CLI Panduan Penggunaan

Ringkasan Cepat

Capgo CLI menyediakan onboarding interaktif yang mengatur pembaruan langsung untuk aplikasi Capacitor Anda. Anda akan:

1. ✅ Mendaftarkan aplikasi Anda di Capgo
2. 🔌 Instal dan konfigurasi plugin pembaruan updater
3. 🚀 Deploy aplikasi live pertama Anda
4. 📱 Tes pembaruan di perangkat Anda

Waktu perkiraan: 10-20 menit (berdasarkan kecepatan internet dan waktu pembangunan Anda)

Trik

Pengalaman onboarding dapat dihentikan dan dilanjutkan kapan saja - keluar dari prosesnya dan lanjutkan dari tempat yang Anda tinggalkan.

Mengaktifkan Pengalaman Onboarding

Jalankan perintah onboarding dengan kunci API Anda:

npx @capgo/cli@latest init [APIKEY]

Anda akan melihat pesan selamat datang:

Capgo onboarding 🛫

Apa yang Terjadi Selama Pengaturan

CLI akan memandu Anda melalui 13 langkah interaktif:

Fase Pengaturan (Langkah 1-6):

• Periksa lingkungan pengembangan Anda (Xcode/Android Studio)
• Tambahkan aplikasi Anda ke Capgo dan buat saluran produksi
• Instal plugin @capgo/capacitor-updater Inject __CAPGO_KEEP_0__ yang diperlukan ke dalam aplikasi Anda
• Inject code yang diperlukan ke dalam aplikasi Anda
• Opsional mengaktifkan enkripsi akhir-ke-akhir
• Pilih platform untuk pengujian (iOS atau Android)

Fase Pengujian (Langkah 7-12):

• Bangun aplikasi dan jalankan di perangkat/simulator
• Buat perubahan yang dapat dilihat code (otomatis atau manual)
• Unggah bundle yang diperbarui ke Capgo
• Lihat pembaruan hidup muncul di perangkat Anda secara real-time

Penyelesaian (Langkah 13):

• Aplikasi Anda sudah siap untuk pembaruan hidup!

Proses Pengenalan 13 Langkah

Langkah 1: Periksa Prasyarat

CLI memeriksa lingkungan pengembangan Anda untuk memastikan Anda telah menginstal alat-alat yang diperlukan.

Apakah yang diperiksa:

• Xcode (hanya macOS) - untuk pengembangan iOS
• Android SDK - untuk pengembangan Android

Hasil yang mungkin:

✅ Kedua lingkungan ditemukan:

✅ Xcode detected - iOS development ready
✅ Android SDK detected - Android development ready

⚠️ Tidak ada lingkungan ditemukan:

⚠️ Xcode not found
⚠️ Android SDK not found
❌ No development environment detected

📱 To develop mobile apps with Capacitor, you need:
   • For iOS: Xcode (macOS only) - https://developer.apple.com/xcode/
   • For Android: Android Studio - https://developer.android.com/studio

Masalah yang mungkin Anda hadapi:

Pertimbangan

Jika tidak ada lingkungan pengembangan yang terdeteksi, Anda akan diminta apakah Anda ingin melanjutkan. Dianjurkan untuk menginstal setidaknya satu platform sebelum melanjutkan.

Langkah 2: Tambahkan Aplikasi Anda

CLI akan masuk ke Capgo dan menambahkan aplikasi Anda ke akun Anda.

(spinner) Running: npm @capgo/cli@latest login ***
Login Done ✅

❓ Add {appId} in Capgo?

Jika ID aplikasi Anda sudah digunakan:

CLI akan menawarkan alternatif:

❌ App ID "com.example.app" is already taken
💡 Here are some suggestions:
   1. com.example.app2
   2. com.example.app3
   3. com.example.app.new
   4. com.example.app.app

❓ What would you like to do?

Anda dapat memilih alternatif atau memasukkan ID aplikasi kustom.

Catatan

ID aplikasi harus mengikuti notasi domain terbalik (misalnya, com.example.myapp)

Langkah 3: Buat Saluran Produksi

Saluran memungkinkan Anda mengelola aliran pembaruan yang berbeda untuk aplikasi Anda.

❓ Create default channel production for {appId} in Capgo?

Trik

Jangan khawatir! Ini hanya untuk pengujian lokal selama proses onboarding. Membuat saluran “produksi” tidak berarti pembaruan Anda akan langsung dipublikasikan ke pelanggan. Anda memiliki kendali penuh atas kapan pembaruan diterapkan. Pilih Ya kecuali Anda memiliki kebutuhan kanal spesifik.

Jika Anda memilih Ya:

(spinner) Running: npm @capgo/cli@latest channel add production {appId} --default
Channel add Done ✅  (or "Channel already added ✅")

akan dibuat kanal produksi dan diatur sebagai default. Ini adalah pilihan yang disarankan untuk pengguna kebanyakan.

Jika Anda memilih Tidak:

If you change your mind, run it for yourself with: "npm @capgo/cli@latest channel add production {appId} --default"

Anda perlu membuat dan mengonfigurasi kanal secara manual kemudian. Atau, Anda bisa:

• Mengatur kanal di file capacitor.config.ts Menggunakan metode JavaScript untuk menetapkan kanal secara dinamis
• Mengonfigurasi kanal kemudian dari __CAPGO_KEEP_0__ console web setChannel() file
• Configure channels later from the Capgo web console

Langkah 4: Pasang Plugin Pembaruan

CLI akan memasang plugin yang kompatibel dengan versi CLI Anda. @capgo/capacitor-updater plugin compatible with your Capacitor version.

❓ Automatic Install "@capgo/capacitor-updater" dependency in {appId}?

__CAPGO_KEEP_0__ 5

• Capacitor 5v5 @capgo/capacitor-updater __CAPGO_KEEP_0__ 6
• Capacitor 6v6 @capgo/capacitor-updater protectedTokens
• Capacitor 7: Menginstal @capgo/capacitor-updater v7
• Capacitor 8+: Menginstal versi terbaru

Pertimbangan

Capgo hanya mendukung Capacitor v5 dan di atas. Jika Anda menggunakan versi yang lebih lama, Anda perlu mengupgrade terlebih dahulu.

Opsi pembaruan instan:

Setelah instalasi, Anda akan diminta:

❓ Do you want to set instant updates in {appId}?
   Read more: https://capgo.app/docs/live-updates/update-behavior/#applying-updates-immediately

Tips

Apa itu pembaruan instan? Dengan pembaruan instan diaktifkan, aplikasi Anda menerapkan pembaruan secara langsung ketika di background dan dibuka kembali. Hal ini berjalan dengan lancar karena Capgo dapat mendistribusikan pembaruan di seluruh dunia dalam waktu kurang dari 300ms. Tanpa itu (mode standar), pembaruan diunduh di latar belakang dan diterapkan pada restart aplikasi berikutnya. Pembaruan instan sangat baik untuk iterasi yang lebih cepat selama pengembangan dan perbaikan bug yang kritikal di produksi.

Jika Anda memilih Ya:

• Pembaruan akan dikonfigurasi untuk diterapkan secara langsung ketika aplikasi di background dan dibuka kembali
• autoUpdate: 'always' dan autoSplashscreen: true context: Halaman/area: Situs web pemasaran Capgo. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman trust.astro. Kunci pesan `dan` (Dan).
• akan ditambahkan ke konfigurasi Anda capacitor.config.ts Aplikasi Anda
• akan diperbarui secara otomatis Pembaruan delta

context: Halaman/area: Halaman produk/harga perusahaan. Peran: Label UI singkat atau item navigasi. Dilihat di: halaman enterprise.astro. Kunci pesan `pembaruan delta perusahaan` (Pembaruan Delta Perusahaan).

• Perbarui akan menggunakan perilaku standar (download di latar belakang, terapkan pada restart berikutnya)
• Kamu bisa selalu mengaktifkan perbarui instan kemudian dengan mengubah pengaturan kamu capacitor.config.ts

Langkah 5: Tambahkan Integrasi Code

CLI akan secara otomatis menginjeksi code yang diperlukan ke dalam file aplikasi utama kamu

❓ Automatic Add "CapacitorUpdater.notifyAppReady()" code and import in {appId}?

Apa yang ditambahkan:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Pengenalan jenis proyek:

• Nuxt.js: Membuat plugins/capacitorUpdater.client.ts
• Lain-lain frameworkMengambahkan ke file utama masuk

Trik

Jika auto-injeksi gagal, Anda dapat menambahkan code secara manual ke file aplikasi utama:

Mengenai Nuxt.js: Membuat plugins/capacitorUpdater.client.ts:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

export default defineNuxtPlugin(() => {
  CapacitorUpdater.notifyAppReady()
})

Mengenai framework lainnya: Mengambahkan ke file utama masuk (misalnya, main.ts, index.js, App.tsx):

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Tempatkan code ini setelah import dan sebelum inisialisasi aplikasi. Untuk informasi lebih lanjut, lihat Petunjuk Menambahkan Aplikasi.

Langkah 6: Pengaturan Enkripsi (Opsional)

Pengaturan enkripsi akhir-ke-akhir menambahkan lapisan keamanan tambahan untuk update Anda.

🔐 End-to-end encryption
   ✅ Use this for: Banking, healthcare, or apps with legal encryption requirements
   ⚠️  Note: Makes debugging harder - skip if you don't need it

❓ Enable end-to-end encryption for {appId} updates?

Catatan

Enkripsi hanya tersedia untuk Capacitor v6 dan di atasnya.

Jika Anda mengaktifkan enkripsi, CLI akan:

1. Menghasilkan kunci enkripsi
2. Mengajukan sinkronisasi pengaturan Capacitor Anda

Langkah 7: Pilih Platform

Pilih platform mana yang akan digunakan selama proses onboarding.

📱 Platform selection for onboarding
   This is just for testing during onboarding - your app will work on all platforms

❓ Which platform do you want to test with during this onboarding?
   Options:
   - iOS
   - Android

Trik

Hanya berpengaruh pada proses onboarding. Aplikasi akhir Anda akan mendukung semua platform.

Langkah 9: Bangun Projek Anda

The CLI will build your app and sync it with Capacitor.

❓ Automatic build {appId} with "npm run build"?

Apa yang terjadi:

1. Mendeteksi jenis proyek Anda
2. Jalankan skrip pembangunan Anda
3. Menggunakan npx cap sync {platform}

Jika skrip pembangunan hilang:

Anda akan diminta apakah ingin melewatkan skrip pembangunan atau menambahkan skrip pembangunan ke proyek Anda package.json.

Langkah 9: Jalankan di Perangkat

Tes versi awal aplikasi Anda di perangkat atau simulator.

❓ Run {appId} on {PLATFORM} device now to test the initial version?

Jika Anda memilih Ya:

(spinner) Running: npx cap run {platform}
(device picker appears)
App started ✅
📱 Your app should now be running on your {platform} device with Capgo integrated
🔄 This is your baseline version - we'll create an update next

Langkah 10: Buat Perubahan Uji

Sekarang saatnya untuk menguji sistem pembaruan Capgo dengan membuat perubahan yang dapat dilihat.

🎯 Now let's test Capgo by making a visible change and deploying an update!

❓ How would you like to test the update?
   Options:
   - Auto: Let Capgo CLI make a visible change for you
   - Manual: I'll make changes myself

Mode Otomatis: CLI akan secara otomatis mengubah file Anda untuk menambahkan banner uji yang dapat dilihat atau perubahan lainnya.

Mode Manual: Anda membuat perubahan sendiri (misalnya, mengubah teks, warna, atau menambahkan elemen).

Pengelolaan Versi:

❓ How do you want to handle the version for this update?
   Options:
   - Auto: Bump patch version ({currentVersion} → {nextVersion})
   - Manual: I'll provide the version number

Bangun dengan perubahan:

❓ Build {appId} with changes before uploading?

Tips

Jika Anda perlu membangun secara manual di terminal lain, pilih “Tidak” dan bangun sendiri, kemudian lanjutkan.

Langkah 11: Unggah Paket

Unggah aplikasi bundle yang diperbarui ke Capgo.

❓ Upload the updated {appId} bundle (v{version}) to Capgo?

CLI berjalan:

npx @capgo/cli@latest bundle upload

Tips

Perbaruan delta dengan perbaruan instan: If Anda mengaktifkan update instan di Langkah 4, CLI akan secara otomatis bertanya apakah Anda ingin mengaktifkan update delta. Update delta mengirimkan hanya file yang berubah antara versi daripada bundle seluruhnya. Karena biasanya hanya beberapa file yang berubah antara update, ini membuat download menjadi lebih cepat. Pilih Ya untuk pengalaman terbaik dengan update instan.

Pesan update delta (jika mode aplikasi instan diaktifkan):

💡 Instant updates are enabled in your config
   Delta updates send only changed files instead of the full bundle

❓ Enable delta updates for this upload? (Recommended with instant updates)

Peringatan

Untuk repositori monorepo, Anda mungkin perlu memberikan jalur tambahan ke package.json dan node_modules.

Sukses:

✅ Update v{version} uploaded successfully!
🎉 Your updated bundle is now available on Capgo

Langkah 12: Tes Update di Perangkat

Salin ke clipboard

🧪 Time to test the Capgo update system!
📱 Go to your device where the app is running

Salin ke clipboard

🔄 IMPORTANT: Background your app (swipe up/press home button) and then reopen it
⏱️  The update should be downloaded and applied automatically

Salin ke clipboard

📱 With standard updates, you will need to:
   1. Background the app (swipe up/press home button) to start download
   2. Wait a few seconds for download to complete
   3. Background and foreground again to see the update

Salin ke clipboard

❓ Monitor Capgo logs to verify the update worked?

Ya , Anda akan melihat log hidup dari perangkat Anda yang menampilkan proses pembaruan.Salin ke clipboard

Langkah 13: Selesai

Welcome onboard ✈️!

Hore! Anda telah berhasil mengatur Capgo pembaruan hidup untuk aplikasi Anda.

Apa yang Anda Capai

Setelah menyelesaikan proses pendaftaran, Anda telah:

✅ Aplikasi Terdaftar

Aplikasi Anda telah terdaftar di Capgo dengan saluran produksi

✅ Plugin Terpasang

Plugin Pembaruan Capacitor telah terpasang dan dikonfigurasi

✅ Code Terintegrasi

Integrasi code telah ditambahkan ke aplikasi Anda

✅ Perbarui yang Dites

Anda telah berhasil menginstal dan menerima pembaruan hidup

Alur Harian

Untuk pembaruan berikutnya, gunakan:

npm run build
npx @capgo/cli@latest bundle upload --channel=production

Untuk pilihan penginstalan yang lebih lengkap, lihat Penginstalan Pembaruan Hidup.

Mengulangi Pengenalan

Jika Anda keluar dari proses onboarding, Anda bisa melanjutkan kapan saja:

npx @capgo/cli@latest init [APIKEY]

Anda akan melihat:

You have already got to the step {stepNumber}/13 in the previous session
❓ Would you like to continue from where you left off?

Trik

Progress disimpan secara lokal, sehingga Anda bisa keluar dan melanjutkan proses onboarding dengan aman.

Bantuan

Tidak Ada Lingkungan Pengembangan

Masalah: Tidak terdeteksi Xcode atau Android SDK.

Solusi:

• Untuk iOS: Pasang Xcode (hanya macOS)
• Untuk Android: Pasang Studio Android

ID Aplikasi Sudah Digunakan

Masalah: ID aplikasi Anda sudah terdaftar.

Solusi: Pilih salah satu alternatif yang disarankan atau masukkan ID aplikasi kustom dalam notasi domain yang dibalik.

Skrip Pembangunan Hilang

Masalah: Tidak ada skrip pembangunan di package.json.

Solusi: Tambahkan skrip pembangunan ke package.json:

{
  "scripts": {
    "build": "your-build-command"
  }
}

Gagal Auto-Injeksi

Masalah: CLI tidak dapat menginjeksi otomatis integrasi code.

Pembahasan: Tambahkan code secara manual ke file utama Anda:

import { CapacitorUpdater } from '@capgo/capacitor-updater'

CapacitorUpdater.notifyAppReady()

Capacitor Versi Terlalu Lama

Masalah: Versi Capacitor Anda masih di bawah v5.

Pembahasan: Upgrade Capacitor ke v5 atau lebih tinggi:

• Mengupgrade ke Capacitor 5
• Mengupgrade ke Capacitor 6
• Mengupgrade ke Capacitor 7

Langkah Selanjutnya

Sekarang Anda telah menyelesaikan proses onboard, eksplorasi topik-topik berikut:

Daftar Periksa Pengaturan Satu Kali

Konfigurasi saluran, CI, dan unggah delta sekali untuk stabilitas jangka panjang

Deploy Update

Belajar bagaimana mengdeploy update dari Capgo dashboard

Jenis Update

Referensi semua jenis update OTA: waktu aplikasi, kondisi penundaan, pemblokiran versi, dan pengiriman

Integrasi CI/CD

Automasi pengiriman update dengan CI/CD

Saluran

Manajemen beberapa aliran update dengan saluran

Enkripsi

Mengamankan update dengan enkripsi end-to-end

Tindakan Update

Mengatur kapan dan bagaimana update diterapkan (langsung, delta, dll.)

Bantuan

Cek

• __CAPGO_KEEP_0__ Petunjuk Perbaikan
• Join Komunitas Komunitas Discord
• Panduan FAQ Pertanyaan Umum
• Hubungi Bantuan

Teruskan dari Panduan Pendaftaran CLI

Jika Anda menggunakan Panduan Pendaftaran __CAPGO_KEEP_0__ untuk merencanakan dashboard dan operasi __CAPGO_KEEP_0__, hubungkan dengan Jika Anda menggunakan Panduan Pendaftaran CLI untuk merencanakan dashboard dan operasi CLI, hubungkan dengan Jika Anda menggunakan Panduan Pendaftaran API untuk merencanakan dashboard dan operasi API, hubungkan dengan Ringkasan API untuk detail implementasi dalam Ringkasan API Pendahuluan untuk detail implementasi dalam Pendahuluan Kunci API untuk detail implementasi dalam Kunci API Perangkat untuk detail implementasi dalam Perangkat, dan Paket untuk detail implementasi dalam Paket.