Panduan Onboarding CLI

Ringkasan Singkat

Capgo CLI menyediakan onboarding interaktif untuk mengatur live updates pada aplikasi Capacitor Anda. Anda akan:

1. ✅ Mendaftarkan aplikasi Anda di Capgo
2. 🔌 Menginstal dan mengonfigurasi plugin updater
3. 🚀 MendePLOY live update pertama Anda
4. 📱 Menguji update di perangkat Anda

Perkiraan waktu: 10-20 menit (tergantung kecepatan internet dan waktu build Anda)

Tips

Onboarding sepenuhnya dapat dilanjutkan - keluar kapan saja dan lanjutkan nanti dari tempat Anda berhenti.

Memulai Onboarding

Jalankan perintah onboarding dengan key API Anda:

npx @capgo/cli@latest init [APIKEY]

Anda akan melihat pesan sambutan:

Capgo onboarding 🛫

Apa yang Terjadi Selama Onboarding

CLI akan memandu Anda melalui 13 langkah interaktif:

Fase Setup (Langkah 1-6):

• Periksa lingkungan pengembangan Anda (Xcode/Android Studio)
• Tambahkan aplikasi Anda ke Capgo dan buat channel produksi
• Instal @capgo/capacitor-updater plugin
• Sisipkan code yang diperlukan ke aplikasi Anda
• Opsional, aktifkan enkripsi end-to-end
• Pilih platform untuk pengujian (iOS atau Android)

Fase Pengujian (Langkah 7-12):

• Build aplikasi Anda dan jalankan di perangkat/simulator
• Buat perubahan code yang terlihat (otomatis atau manual)
• Upload bundle yang diperbarui ke Capgo
• Lihat live update muncul di perangkat Anda secara real-time

Selesai (Langkah 13):

• Aplikasi Anda sudah siap untuk live updates! 🎉

Proses Onboarding 13 Langkah

Langkah 1: Periksa Prasyarat

CLI memeriksa lingkungan pengembangan Anda untuk memastikan tools yang diperlukan sudah terpasang.

Yang dicek:

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

Kemungkinan hasil:

✅ Kedua environment ditemukan:

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

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

Pertanyaan yang mungkin muncul:

Peringatan

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

Langkah 2: Tambahkan Aplikasi Anda

CLI akan membuat Anda login 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 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 kustom.

Catatan

ID aplikasi harus mengikuti notasi reverse domain (mis., com.example.myapp)

Langkah 3: Buat Channel Produksi

Channel memungkinkan Anda mengelola berbagai stream update untuk aplikasi Anda.

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

Tips

Jangan khawatir! Ini hanya untuk pengujian lokal selama onboarding. Membuat channel “produksi” tidak berarti update Anda akan langsung live ke pelanggan. Anda memiliki kendali penuh atas kapan update di-deploy. Pilih Ya kecuali Anda memiliki persyaratan channel tertentu.

Jika Anda memilih Ya:

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

Channel produksi akan dibuat dan diset sebagai default. Ini adalah opsi yang direkomendasikan untuk sebagian besar pengguna.

Jika Anda memilih No:

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

Anda perlu membuat dan mengonfigurasi channel secara manual nanti. Atau, Anda bisa:

• Set the channel in your capacitor.config.ts file
• Gunakan metode JavaScript setChannel() untuk mengatur channel secara dinamis
• Konfigurasi channel nanti dari konsol web Capgo

Langkah 4: Instal Plugin Updater

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

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

Kompatibilitas versi:

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

Peringatan

Capgo hanya mendukung Capacitor v5 ke atas. Jika Anda memakai versi lama, Anda perlu upgrade dulu.

Opsi instant updates:

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 itu instant updates? Dengan fitur instant updates aktif, aplikasi Anda akan langsung menerapkan update saat masuk ke background dan dibuka kembali. Ini berjalan mulus karena Capgo dapat mendistribusikan update ke seluruh dunia dalam waktu kurang dari 300ms. Tanpa fitur ini (mode standar), update akan di-download di background dan baru diterapkan saat aplikasi di-restart. Instant updates sangat berguna untuk iterasi yang lebih cepat selama development maupun perbaikan bug kritis di production.

Jika Anda memilih Ya:

• Update akan dikonfigurasi untuk langsung diterapkan saat aplikasi masuk ke background dan dibuka kembali
• autoUpdate: 'always' dan autoSplashscreen: true akan ditambahkan ke config Anda
• @capacitor/splash-screen akan diinstal jika belum ada, dengan launchAutoHide: false
• Anda capacitor.config.ts akan diperbarui secara otomatis
• Update Delta tetap aktif. Instant apply (always, atInstall, onLaunch) sebaiknya tetap menggunakan npx @capgo/cli@latest bundle upload --delta agar hanya file yang berubah yang diunduh dan pengguna tidak perlu menunggu unduhan zip penuh

Jika Anda memilih No:

• Update akan menggunakan perilaku standar (unduh di background, terapkan saat restart berikutnya)
• Anda selalu bisa mengaktifkan instant updates nanti dengan mengubah capacitor.config.ts

Langkah 5: Tambahkan Integrasi Code

CLI akan otomatis menginjeksi code 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 tipe proyek:

• Nuxt.js: Membuat plugins/capacitorUpdater.client.ts
• Framework lain: Menambahkan ke file entry utama Anda

Tips

Jika auto-injection gagal, Anda bisa menambahkan code 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 framework lain: Tambahkan ke file entry utama Anda (mis., main.ts, index.js, App.tsx):

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

CapacitorUpdater.notifyAppReady()

Letakkan code ini setelah import dan sebelum inisialisasi aplikasi. Untuk detail lebih lanjut, lihat Panduan Menambahkan Aplikasi.

Langkah 6: Konfigurasi Enkripsi (Opsional)

Enkripsi end-to-end menambahkan lapisan keamanan ekstra 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 ke atas.

Jika Anda mengaktifkan enkripsi, CLI akan:

1. Membuat kunci enkripsi
2. Menawarkan untuk menyinkronkan konfigurasi Capacitor Anda

Langkah 7: Pilih Platform

Pilih platform yang ingin Anda gunakan untuk pengujian selama 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

Tips

Ini hanya memengaruhi proses onboarding. Aplikasi final Anda akan mendukung semua platform.

Langkah 8: Build Project Anda

CLI akan mem-build aplikasi Anda dan menyinkronkannya dengan Capacitor.

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

Apa yang terjadi:

1. Mendeteksi tipe project Anda
2. Menjalankan build script Anda
3. Mengeksekusi npx cap sync {platform}

Jika build script tidak ada:

Anda akan ditanya apakah ingin skip build atau tambahkan build script ke package.json.

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

Sekarang saatnya menguji sistem update 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 banner uji yang terlihat atau perubahan.

Mode manual: Anda melakukan 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

Build dengan perubahan:

❓ Build {appId} with changes before uploading?

Tips

Jika Anda perlu melakukan build manual di terminal lain, pilih “No” dan build sendiri, lalu lanjutkan.

Langkah 11: Upload Bundle

Upload bundle aplikasi terbaru Anda ke Capgo.

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

CLI menjalankan:

npx @capgo/cli@latest bundle upload

Tips

Delta updates dengan update instan: Jika Anda mengaktifkan instant updates di Langkah 4, CLI akan otomatis menanyakan apakah Anda ingin mengaktifkan delta updates. Delta updates hanya mengirim file yang berubah antar versi, bukan seluruh bundle. Karena biasanya hanya sedikit file yang berubah, ini membuat download jauh lebih cepat. Pilih Ya untuk pengalaman terbaik dengan instant updates.

Prompt delta update (jika mode instant apply aktif):

💡 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 monorepo, Anda mungkin perlu menyediakan path tambahan ke package.json dan node_modules.

Berhasil:

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

Langkah 12: Tes Update di Perangkat

Saatnya melihat update ini bekerja!

🧪 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

Pantau logs:

❓ Monitor Capgo logs to verify the update worked?

Jika Anda memilih Ya, Anda akan melihat live logs dari perangkat Anda yang menunjukkan proses pembaruan.

Langkah 13: Selesai

Welcome onboard ✈️!

Selamat! Anda berhasil mengatur Capgo live updates untuk aplikasi Anda.

Apa yang Telah Anda Capai

Setelah menyelesaikan onboarding, Anda memiliki:

✅ Aplikasi Terdaftar

Aplikasi Anda terdaftar di Capgo dengan channel produksi

✅ Plugin Terpasang

Plugin Capacitor Updater terpasang dan dikonfigurasi

✅ Code Terintegrasi

Integrasi code ditambahkan ke aplikasi Anda

✅ Update Diuji

Anda berhasil deploy dan menerima live update

Workflow Harian

Untuk update selanjutnya, gunakan:

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

Untuk opsi deployment lainnya, lihat Deploy Live Update.

Melanjutkan Onboarding

Jika Anda keluar dari proses onboarding, Anda bisa 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

Progres disimpan secara lokal, jadi Anda bisa keluar dan melanjutkan onboarding dengan aman.

Pemecahan Masalah

Tanpa Development Environment

Masalah: Baik Xcode maupun Android SDK tidak terdeteksi.

Solusi:

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

App ID Sudah Digunakan

Masalah: App ID Anda sudah terdaftar.

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

Build Script Tidak Ditemukan

Masalah: Build script tidak ditemukan di package.json.

Solusi: Tambahkan build script ke package.json:

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

Auto-Injection Gagal

Masalah: CLI tidak dapat menginjeksi integrasi code secara otomatis.

Solusi: Tambahkan code secara manual ke file utama Anda:

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

CapacitorUpdater.notifyAppReady()

Versi Capacitor Terlalu Lama

Masalah: Versi Capacitor Anda di bawah v5.

Solusi: Upgrade Capacitor ke v5 atau lebih tinggi:

• Upgrade ke Capacitor 5
• Upgrade ke Capacitor 6
• Upgrade ke Capacitor 7

Langkah Berikutnya

Setelah onboarding selesai, jelajahi topik-topik ini:

Checklist setup satu kali

Konfigurasi channel, CI, dan delta upload sekali untuk stabilitas jangka panjang

Deploy Update

Pelajari cara deploy update dari dashboard Capgo

Tipe Update

Referensi semua jenis update OTA: waktu apply, kondisi delay, pemblokiran versi, dan pengiriman

Integrasi CI/CD

Otomatiskan deployment update Anda dengan CI/CD

Channel

Kelola beberapa stream update dengan channel

Enkripsi

Amankan update Anda dengan enkripsi end-to-end

Perilaku Update

Sesuaikan kapan dan bagaimana update diterapkan (direct, delta, dll.)

Butuh bantuan

Jika Anda menemui masalah selama onboarding:

• Cek Panduan Troubleshooting
• Gabung ke Komunitas Discord
• Tinjau FAQ
• Kontak Dukungan

Lanjutkan dari CLI Onboarding Guide

Jika Anda menggunakan Panduan Onboarding CLI untuk merencanakan operasi dashboard dan API, hubungkan dengan Ringkasan API untuk detail implementasi di API Overview, Pendahuluan untuk detail implementasi di Introduction, Kunci API untuk detail implementasi di API Keys, Perangkat untuk detail implementasi di Devices, dan Bundle untuk detail implementasi di Bundles.