CLI Panduan Orientasi

Ikhtisar Singkat

Capgo CLI menyediakan orientasi interaktif yang menyiapkan pembaruan langsung untuk aplikasi Capacitor Anda. Anda akan:

1. ✅ Daftarkan aplikasi Anda di Capgo
2. 🔌 Instal dan konfigurasikan plugin pembaru
3. 🚀 Terapkan pembaruan langsung pertama Anda
4. 📱 Uji pembaruan pada perangkat Anda

Perkiraan waktu: 10-20 menit (bervariasi berdasarkan kecepatan internet dan waktu pembuatan)

Tips

Orientasi sepenuhnya dapat dilanjutkan - keluar kapan saja dan lanjutkan nanti dari bagian terakhir yang Anda tinggalkan.

Memulai Orientasi

Jalankan perintah orientasi dengan kunci API Anda:

npx @capgo/cli@latest init [APIKEY]

Anda akan melihat pesan selamat datang:

Capgo onboarding 🛫

Apa yang Terjadi Selama Orientasi

CLI akan memandu Anda melalui 13 langkah interaktif:

Fase Penyiapan (Langkah 1-6):

• Periksa lingkungan pengembangan Anda (Xcode/Android Studio)
• Tambahkan aplikasi Anda ke Capgo dan buat saluran produksi
• Instal plugin @capgo/capacitor-updater
• Suntikkan kode yang diperlukan ke dalam aplikasi Anda
• Secara opsional mengaktifkan enkripsi ujung ke ujung
• Pilih platform untuk pengujian (iOS atau Android)

Fase Pengujian (Langkah 7-12):

• Bangun aplikasi Anda dan jalankan di perangkat/simulator
• Buat perubahan kode yang terlihat (otomatis atau manual)
• Unggah bundel yang diperbarui ke Capgo
• Lihat pembaruan langsung yang muncul di perangkat Anda secara real-time

Penyelesaian (Langkah 13):

• Aplikasi Anda siap untuk pembaruan langsung! 🎉

Proses Orientasi 13 Langkah

Langkah 1: Periksa Prasyarat

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

Yang diperiksa:

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

Kemungkinan hasil:

✅ Kedua lingkungan ditemukan:

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

⚠️ Tidak ditemukan lingkungan:

⚠️ 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

Pertanyaan yang mungkin ditanyakan kepada Anda:

Perhatian

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

Langkah 2: Tambahkan Aplikasi Anda

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

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

❓ Add {appId} in Capgo?

Jika ID aplikasi Anda sudah dipakai:

CLI akan menyarankan 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 saran atau memasukkan ID aplikasi khusus.

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?

Tips

Jangan khawatir! Ini hanya untuk pengujian lokal selama orientasi. Membuat saluran “produksi” tidak berarti pembaruan Anda akan langsung ditayangkan kepada pelanggan. Anda memiliki kendali penuh atas kapan pembaruan disebarkan. Pilih Ya kecuali Anda memiliki persyaratan saluran tertentu.

Jika Anda memilih Ya:

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

Saluran produksi akan dibuat dan ditetapkan sebagai default. Ini adalah opsi yang direkomendasikan bagi sebagian besar pengguna.

Jika Anda memilih Tidak:

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

Anda harus membuat dan mengonfigurasi saluran secara manual nanti. Alternatifnya, Anda dapat:

• Atur saluran di file capacitor.config.ts Anda
• Gunakan metode JavaScript setChannel() untuk mengatur saluran secara dinamis
• Konfigurasikan saluran nanti dari konsol web Capgo

Langkah 4: Instal Plugin Pembaruan

CLI akan menginstal plugin @capgo/capacitor-updater yang kompatibel dengan versi Capacitor Anda.

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

Kompatibilitas versi:

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

Perhatian

Capgo hanya mendukung Capacitor v5 dan yang lebih baru. Jika Anda menggunakan versi lama, Anda harus melakukan upgrade terlebih dahulu.

Opsi pembaruan instan:

Setelah instalasi, Anda akan ditanya:

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

Tips

Apa yang dimaksud dengan pembaruan instan? Dengan mengaktifkan pembaruan instan, aplikasi Anda akan segera menerapkan pembaruan saat berada di latar belakang dan dibuka kembali. Ini berfungsi dengan lancar karena Capgo dapat mendistribusikan pembaruan ke seluruh dunia dalam waktu kurang dari 300 md. Tanpa itu (mode standar), pembaruan diunduh di latar belakang dan diterapkan pada aplikasi berikutnya yang dimulai ulang. Pembaruan instan sangat bagus untuk iterasi yang lebih cepat selama pengembangan dan perbaikan bug penting dalam produksi.

Jika Anda memilih Ya:

• Pembaruan akan dikonfigurasi untuk diterapkan segera ketika aplikasi berada di latar belakang dan dibuka kembali
• directUpdate: 'always' dan autoSplashscreen: true akan ditambahkan ke konfigurasi Anda
• capacitor.config.ts Anda akan diperbarui secara otomatis
• Pembaruan Delta akan diaktifkan secara otomatis - ini hanya mengirimkan file yang berubah di antara pembaruan, bukan paket lengkap, sehingga pembaruan menjadi jauh lebih cepat

Jika Anda memilih Tidak:

• Pembaruan akan menggunakan perilaku standar (unduh di latar belakang, terapkan saat restart berikutnya)
• Anda selalu dapat mengaktifkan pembaruan instan nanti dengan memodifikasi capacitor.config.ts Anda

Langkah 5: Tambahkan Kode Integrasi

CLI akan secara otomatis memasukkan kode yang diperlukan ke dalam file aplikasi utama Anda.

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

Apa yang ditambahkan:

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

CapacitorUpdater.notifyAppReady()

Deteksi jenis proyek:

• Nuxt.js: Membuat plugins/capacitorUpdater.client.ts
• Kerangka kerja lainnya: Menambahkan ke file entri utama Anda

Tips

Jika injeksi otomatis gagal, Anda dapat menambahkan kode secara manual ke file aplikasi utama Anda:

Untuk Nuxt.js: Buat plugins/capacitorUpdater.client.ts:

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

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

Untuk kerangka lain: Tambahkan ke file entri utama Anda (mis., main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Tempatkan kode ini setelah impor Anda dan sebelum inisialisasi aplikasi Anda. Untuk detail selengkapnya, lihat Panduan Menambahkan Aplikasi.

Langkah 6: Siapkan Enkripsi (Opsional)

Enkripsi ujung ke ujung menambahkan lapisan keamanan ekstra untuk pembaruan 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 yang lebih baru.

Jika Anda mengaktifkan enkripsi, CLI akan:

1. Hasilkan kunci enkripsi
2. Tawarkan untuk menyinkronkan konfigurasi Capacitor Anda

Langkah 7: Pilih Platform

Pilih platform mana yang akan diuji selama orientasi.

📱 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

Tips

Ini hanya mempengaruhi proses orientasi. Aplikasi akhir Anda akan mendukung semua platform.

Langkah 8: Bangun Proyek Anda

CLI akan membuat aplikasi Anda dan menyinkronkannya dengan Capacitor.

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

Apa yang terjadi:

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

Jika skrip build tidak ada:

Anda akan ditanya apakah ingin melewati build atau menambahkan skrip build ke package.json Anda.

Langkah 9: Jalankan di Perangkat

Uji 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: Lakukan Uji Perubahan

Sekarang saatnya menguji sistem pembaruan Capgo dengan membuat perubahan yang terlihat.

🎯 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 memodifikasi file Anda untuk menambahkan spanduk pengujian yang terlihat atau mengubah.

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

Penanganan 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 buat sendiri, lalu lanjutkan.

Langkah 11: Unggah Paket

Unggah paket aplikasi Anda yang telah diperbarui ke Capgo.

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

CLI berjalan:

npx @capgo/cli@latest bundle upload

Tips

Pembaruan Delta dengan Pembaruan Langsung: Jika Anda mengaktifkan pembaruan instan (Pembaruan Langsung) pada Langkah 4, CLI akan otomatis menanyakan apakah Anda ingin mengaktifkan pembaruan delta. Pembaruan Delta hanya mengirimkan file yang berubah antar versi, bukan keseluruhan paket. Karena biasanya hanya sedikit file yang berubah di antara pembaruan, hal ini membuat pengunduhan menjadi lebih cepat. Pilih Ya untuk pengalaman terbaik dengan pembaruan instan.

Permintaan pembaruan Delta (jika Pembaruan Langsung diaktifkan):

💡 Direct Update (instant updates) is enabled in your config
   Delta updates send only changed files instead of the full bundle

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

Perhatian

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

Sukses:

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

Langkah 12: Uji Pembaruan pada Perangkat

Saatnya melihat pembaruan beraksi!

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

Untuk pembaruan instan:

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

Untuk pembaruan standar:

📱 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

Log pemantauan:

❓ Monitor Capgo logs to verify the update worked?

Jika Anda memilih Ya, Anda akan melihat log langsung dari perangkat Anda yang menunjukkan proses pembaruan.

Langkah 13: Penyelesaian

Welcome onboard ✈️!

Selamat! Anda berhasil menyiapkan Capgo pembaruan langsung untuk aplikasi Anda.

Apa yang Telah Anda Capai

Setelah menyelesaikan orientasi, Anda memiliki:

✅ Aplikasi Terdaftar

Aplikasi Anda terdaftar di Capgo dengan saluran produksi

✅ Plugin Terpasang

Plugin Capacitor Updater telah diinstal dan dikonfigurasi

✅ Kode Terintegrasi

Kode integrasi ditambahkan ke aplikasi Anda

✅ Pembaruan Diuji

Anda telah berhasil menerapkan dan menerima pembaruan langsung

Alur Kerja Harian

Untuk pembaruan selanjutnya, gunakan:

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

Untuk opsi penerapan lainnya, lihat Menerapkan Pembaruan Langsung.

Melanjutkan Orientasi

Jika Anda keluar dari proses orientasi, Anda dapat melanjutkannya 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?

Tips

Kemajuan disimpan secara lokal, sehingga Anda dapat keluar dengan aman dan melanjutkan proses orientasi.

Pemecahan masalah

Tidak Ada Lingkungan Pengembangan

Masalah: Baik Xcode maupun Android SDK tidak terdeteksi.

Solusi:

• Untuk iOS: Instal Xcode (khusus macOS)
• Untuk Android: Instal Android Studio

ID Aplikasi Sudah Diambil

Masalah: ID aplikasi Anda sudah terdaftar.

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

Skrip Pembuatan Hilang

Masalah: Tidak ditemukan skrip build di package.json.

Solusi: Tambahkan skrip build ke package.json Anda:

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

Injeksi Otomatis Gagal

Masalah: CLI tidak dapat memasukkan kode integrasi secara otomatis.

Solusi: Tambahkan kode secara manual ke file utama Anda:

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

CapacitorUpdater.notifyAppReady()

Capacitor Versi Terlalu Lama

Masalah: Versi Capacitor Anda di bawah v5.

Solusi: Tingkatkan Capacitor ke v5 atau lebih tinggi:

• Meningkatkan ke Capacitor 5
• Meningkatkan ke Capacitor 6
• Meningkatkan ke Capacitor 7

Langkah Selanjutnya

Sekarang setelah Anda menyelesaikan orientasi, jelajahi topik berikut:

Terapkan Pembaruan

Pelajari cara menerapkan pembaruan dari dasbor Capgo

Jenis Pembaruan

Referensi semua jenis pembaruan OTA: penerapan waktu, kondisi penundaan, pemblokiran versi, dan pengiriman

Integrasi CI/CD

Otomatiskan penerapan pembaruan Anda dengan CI/CD

Channels

Kelola beberapa aliran pembaruan dengan saluran

Encryption

Amankan pembaruan Anda dengan enkripsi ujung ke ujung

Perbarui Perilaku

Sesuaikan kapan dan bagaimana pembaruan diterapkan (langsung, delta, dll.)

Mendapatkan Bantuan

Jika Anda mengalami masalah selama orientasi:

• Periksa Panduan Mengatasi Masalah
• Bergabunglah dengan Komunitas Perselisihan
• Tinjau FAQ
• Hubungi Dukungan