Cara Membuat Aplikasi Apple Watch untuk Aplikasi Capacitor

Untuk membangun aplikasi jam tangan Apple untuk aplikasi Capacitor, Anda menambahkan target native watchOS ke proyek iOS Anda, menulis UI-nya dalam SwiftUI, dan menghubungkannya ke web code Anda dengan @capgo/capacitor-watch plugin, yang mengelilingi kerangka kerja WatchConnectivity Apple. Aplikasi ponsel tetap memiliki layer web Capacitor, dan aplikasi jam tangan menjadi komponen native kecil yang mengirim dan menerima kamus.

Guid ini mencakup jalur penuh pada Capacitor 8 dan Xcode 26: arsitektur, target Xcode, kode Swift dan TypeScript code di setiap sisi, metode transfer yang digunakan, pengujian pada simulator dan perangkat, dan bagaimana aplikasi jam tangan dikirim.

Why UI jamannya native dan ponsel tetap Capacitor

watchOS tidak mengirimkan WebView. Tidak ada WKWebView di jam tangan, jadi aplikasi Capacitor tidak bisa dijalankan di sana, dan tidak ada perubahan plugin. Yang bisa kamu lakukan adalah membagi tanggung jawab:

Dalam Praktik, Aplikasi Jam Tangan Adalah “Tergantung”: Aplikasi Ini Mendapatkan Data dari Telepon. Simpan Logika di Telepon di Mana Logika Sudah Ada di TypeScript, dan Kirim Jam Tangan Hanya Data yang Diperlukan untuk Ditampilkan.

Persyaratan

• Aplikasi Capacitor 8 dengan platform iOS ditambahkan. Jika Anda masih menggunakan versi yang lebih lama, ikuti panduan Capacitor 8 upgrade. Capacitor Panduan Upgrade 8 Pertama.
• Xcode 26 di Mac. Apple telah memerlukan Xcode 26 untuk unggah aplikasi ke App Store sejak April 2026, lihat Xcode 26 requirement.
• Akun Pengembang Apple untuk tes perangkat dan distribusi.
• iOS 15 atau lebih baru di ponsel (minimum plugin) dan watchOS 9 atau lebih baru di jam tangan (minimum SDK).
• Idealkan, iPhone asli yang dipasangkan dengan Apple Watch asli. Simulator membantu, tetapi tidak menutupi setiap jenis transfer.

Langkah 1: Pasang plugin di sisi ponsel

bun add @capgo/capacitor-watch
bunx cap sync ios

Plugin diaktifkan WCSession Segera setelah aplikasi dimuat, jadi tidak ada panggilan inisialisasi. Mulailah dengan membaca status koneksi:

import { CapgoWatch } from '@capgo/capacitor-watch';

const info = await CapgoWatch.getInfo();
console.log({
  supported: info.isSupported,          // false on iPad, Android without Wear OS, and web
  paired: info.isPaired,                // an Apple Watch is paired with this iPhone
  installed: info.isWatchAppInstalled,  // your watch app is on that watch
  reachable: info.isReachable,          // live messaging is possible right now
  state: info.activationState,          // 0 notActivated, 1 inactive, 2 activated
});

Referensi lengkap API dapat ditemukan di docs plugin dan halaman plugin.

Langkah 2: Tambahkan target watchOS di Xcode

Klik buka proyek iOS dengan bunx cap open ios. Capacitor 8 proyek dibuat dengan Swift Package Manager terbuka App.xcodeproj; proyek lama CocoaPods terbuka App.xcworkspace. Keduanya berfungsi.

1. Pilih File > Baru > Target, select the watchOS tab, kemudian Aplikasi.
2. Berinama, misalnya MyWatch, dan gunakan SwiftUI sebagai antarmuka.
3. Pastikan aplikasi jam tangan terintegrasi dalam aplikasi yang sudah ada di sheet opsi. App Membuat target sebagai temanannya. Pengaturan tersebutlah yang membuat Xcode mengintegrasikan aplikasi jam tangan ke dalam build iPhone dan menetapkan identifikasi paket temanannya.
4. Matikan notifikasi dan komplikasi kecuali Anda membutuhkannya sekarang. Anda bisa menambahkan widget lainnya nanti.
5. Terima permintaan untuk mengaktifkan skema baru.

Aturan Identifikasi Paket

ID aplikasi jam waktu harus dimulai dengan ID aplikasi iPhone. Jika aplikasi Anda com.example.shopXcode menyarankan com.example.shop.watchkitappJika Anda mengubah ID aplikasi iOS kemudian, ubah juga ID aplikasi jam tangan, atau proses pembangunan akan gagal dan WatchConnectivity tidak akan mempairkan dua aplikasi.

Di bawah Signing & Capabilities, pilih tim yang sama untuk kedua target. Dengan pengaturan otomatis, Xcode mendaftarkan ID aplikasi kedua dan profil pengaturan untuk Anda.

Tambahkan CapgoWatchSDK ke target jam tangan

1. File > Tambahkan Dependensi Paket.
2. Masukkan https://github.com/Cap-go/capacitor-watch.git.
3. Pilih "Hingga Versi Utama Berikutnya" dari 8.0.0.
4. Ketika Xcode bertanya produk mana yang perlu ditambahkan, pilih hanya CapgoWatchSDK dan asingkannya ke jam tangan target, bukan aplikasi iOS. Sisi iOS sudah mendapatkan plugin melalui cap sync.

Langkah 3: Tulis aplikasi jam tangan dengan SwiftUI

The SDK exposes WatchConnector.sharedaplikasi ObservableObject dengan diterbitkan isReachable, isActivated, lastMessagelangkah applicationContext Sifat. Aktifkan saat aplikasi dimulai:

import SwiftUI
import CapgoWatchSDK

@main
struct MyWatchApp: App {
    init() {
        WatchConnector.shared.activate()
    }

    var body: some Scene {
        WindowGroup {
            OrdersView()
        }
    }
}

Tampilan layar kecil yang menampilkan data yang dikirim dari ponsel dan mengirimkan aksi kembali:

import SwiftUI
import CapgoWatchSDK

struct OrdersView: View {
    @ObservedObject private var connector = WatchConnector.shared
    @State private var status = ""

    var openOrders: Int {
        connector.applicationContext["openOrders"] as? Int ?? 0
    }

    var body: some View {
        VStack(spacing: 8) {
            Text("\(openOrders)")
                .font(.system(size: 44, weight: .bold))
            Text("open orders")
                .font(.footnote)
                .foregroundStyle(.secondary)

            Button("Refresh") {
                refresh()
            }
            .disabled(!connector.isReachable)

            if !status.isEmpty {
                Text(status).font(.caption2)
            }
        }
    }

    private func refresh() {
        Task {
            do {
                let reply = try await connector.sendMessage(["action": "refresh"])
                status = "Updated \(reply["count"] as? Int ?? 0)"
            } catch {
                status = "iPhone not reachable"
            }
        }
    }
}

langkah async langkah sendMessage mengirimkan dengan handler balasan, sehingga ponsel menerima sebagai messageReceivedWithReply event. Variannya berbasis callback. sendMessage(_:replyHandler:errorHandler:) Memungkinkan Anda melewatkan jawaban.

Jika Anda lebih suka callback delegasi daripada mengamati properti yang dipublikasikan, patuhi WatchConnectorDelegate dan atur WatchConnector.shared.delegate. Ini memiliki metode untuk pesan, pesan dengan handler jawaban, konteks aplikasi, informasi pengguna, ketersambungan, dan aktivasi.

Langkah 4: Berbicara dengan jam tangan dari TypeScript

Registrasi pemangku jawab awal, misalnya di bootstrap aplikasi Anda, sehingga event yang datang saat peluncuran tidak terlewat.

import { CapgoWatch } from '@capgo/capacitor-watch';

export async function setupWatchBridge(getOpenOrders: () => Promise<number>) {
  // Watch asked for something and is waiting for an answer
  await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
    if (event.message.action === 'refresh') {
      const count = await getOpenOrders();
      await CapgoWatch.replyToMessage({
        callbackId: event.callbackId,
        data: { count },
      });
      await pushStateToWatch(count);
    }
  });

  // Fire-and-forget messages from the watch
  await CapgoWatch.addListener('messageReceived', (event) => {
    console.log('watch says', event.message);
  });

  await CapgoWatch.addListener('reachabilityChanged', (event) => {
    console.log('watch reachable:', event.isReachable);
  });

  await pushStateToWatch(await getOpenOrders());
}

export async function pushStateToWatch(openOrders: number) {
  const info = await CapgoWatch.getInfo();
  if (!info.isSupported || !info.isPaired || !info.isWatchAppInstalled) return;

  // Latest state only, delivered when the watch app next runs
  await CapgoWatch.updateApplicationContext({
    context: { openOrders, updatedAt: Date.now() },
  });
}

Selalu jawab messageReceivedWithReply. Jam tangan menunggu, dan permintaan yang tidak dijawab berakhir dengan kesalahan waktu habis pada sisi jam tangan.

Metode mana yang harus Anda gunakan?

WatchConnectivity memberikan Anda tiga saluran, dan plugin menerjemakannya:

A pola yang efektif: gunakan konteks aplikasi sebagai sumber kebenaran untuk apa yang ditampilkan di jam tangan, gunakan sendMessage hanya untuk interaksi saat aplikasi jam tangan terbuka, dan gunakan transferUserInfo untuk apa pun yang tidak bisa Anda biarkan terjatuh.

Batasan untuk dirancang sekitar

• Ukuran payload. WatchConnectivity menolak payload yang terlalu besar dengan payloadTooLarge, dan Apple tidak menerbitkan byte hitung tetap untuk setiap saluran. Jaga payload kecil: ID, hitungan, string singkat. Ambil konten besar dari API Anda.
• Jenis payload. Data harus kompatibel dengan property-list: string, angka, boolean, tanggal, data, array, dan kamus. null Nilai dari JavaScript tidak valid. Hilangkan mereka sebelum mengirim.
• Telepon harus menjalankan aplikasi Anda untuk menghandle event. Penggunaan hidup ada di runtime JavaScript Capacitor. Jika iOS telah menghentikan aplikasi, event tidak akan mencapai TypeScript Anda sampai aplikasi berjalan lagi. Konteks dan informasi pengguna tetap di antrian oleh sistem, tetapi dirancang UI jam tangan agar berfungsi dari konteks yang dicache.
• Pemrograman. Sebuah jam tangan Apple hanya dapat dipasangkan dengan iPhone. Pengguna Android tidak dapat menggunakannya, dan implementasi plugin Android bertujuan ke Wear OS, yang dibahas dalam panduan kami tentang Wear OS. Panduan Wear OS.
• Kemandirian. Aplikasi kompatibel yang dibangun dengan WatchConnectivity bergantung pada ponsel. Jika jam tangan harus berfungsi jauh dari ponsel, tambahkan sumber data kedua seperti API milik Anda melalui koneksi jaringan jam tangan.

Pengujian pada simulator dan perangkat.

Anda dapat berulang-ulang pada tata letak SwiftUI di simulator jam tangan, tetapi transfer data memerlukan pengaturan yang dipasangkan.

xcrun simctl list devices
xcrun simctl pair <watch-udid> <phone-udid>

Jalankan aplikasi iOS pada simulator iPhone yang dipasangkan, kemudian jalankan skema jam tangan pada simulator jam tangan. Kedua aplikasi harus terinstal sebelum isWatchAppInstalled Apple mencatat bahwa Simulator tidak mendukung transferUserInfoJadi pastikan jalur tersebut pada perangkat nyata.

Untuk perangkat, hubungkan iPhone, pastikan jam tangan memiliki mode pengembang diaktifkan, dan pilih jam tangan sebagai tujuan jalankan untuk skema jam tangan. Gunakan getInfo() sebagai tes asap Anda:

Troubleshooting

isWatchAppInstalled Penyelidikan Masalah Periksa prefix ID paket jam tangan, pastikan target jam tangan sudah diintegrasikan ke App target (Build Phases > Isi Konten Jam Tangan), dan instal ulang kedua aplikasi tersebut.

Pesan dari jam tidak pernah mencapai JavaScript. Pendaftarkanlah pemangku hak sebelum jam mengirim, dan pastikan jam memanggil WatchConnector.shared.activate() on launch. Di ponsel, periksa konsol Xcode untuk log aktivasi plugin.

sendMessage ditolak dengan “Jam tidak dapat dijangkau”. Diperkirakan ketika aplikasi jam ditutup. Jatuh ke updateApplicationContext.

replyToMessage terkesan diabaikan. Passkan nilai yang tepat callbackId dari event dan balaslah dengan cepat. Pengolah jawaban jam memiliki batas waktu.

Build gagal dengan “Identifikasi bundle biner yang diintegrasikan tidak dimulai dengan prefiks”. Identifikasi bundle jam harus dimulai dengan identifikasi bundle iOS.

Unggah arsip ditolak karena kurangnya ikon. Target jam memerlukan ikon aplikasi sendiri di Assets.xcassets.

Menyebarkan aplikasi jam tangan

Aplikasi jam tangan bukanlah produk terpisah. Aplikasi ini diintegrasikan ke dalam arsip iOS, diunggah bersama, dan ditampilkan di rekaman App Store Connect yang sama, di mana Anda menambahkan layar gambar Apple Watch di bawah tab jam tangan. Apa pun yang menghasilkan arsip Anda, Xcode lokal, CI, atau Capgo PembangunanHarus memiliki profil pengembangan untuk kedua ID paket dan harus menggunakan Xcode 26.

Perhatikan satu hal untuk pembaruan. Capgo live updates can ship changes to the phone’s web bundle without a store review, which is handy when the TypeScript side of your watch bridge has a bug. Swift code on the watch, and any change to the native plugin, still goes through the App Store. Version your message format, for example with a v field di setiap kamus, sehingga paket smartphone yang lebih baru tetap berfungsi dengan versi jam tangan yang lebih lama.

Wrap-up

Splitnya sederhana sekali setelah Anda menerima kenyataan: SwiftUI untuk pergelangan tangan, Capacitor untuk semua hal lainnya, dan tiga saluran WatchConnectivity di antara mereka. Pasang @capgo/capacitor-watchTambahkan target jam dengan CapgoWatchSDK, jaga payload kecil, dan tes pada perangkat yang dipasangkan sebelum mengirimkan.