Panduan Memulai

Instalasi

Anda bisa menggunakan AI-Assisted Setup kami untuk menginstal plugin ini. Tambahkan skill Capgo ke tool AI Anda dengan command berikut:

bunx skills add https://github.com/Cap-go/capgo-skills --skill capacitor-plugins

Lalu gunakan prompt berikut:

Use the `capacitor-plugins` skill from `Cap-go/capgo-skills` to install the `@capgo/capacitor-watch` plugin in my project.

Jika Anda lebih memilih Manual Setup, instal plugin dengan menjalankan perintah berikut dan ikuti petunjuk khusus platform di bawah ini:

1. Instal package

   bun add @capgo/capacitor-watch

2. Sync dengan proyek native

   bunx cap sync

3. Konfigurasi plugin

   Contoh Penggunaan Dasar:

   import { CapgoWatch } from '@capgo/capacitor-watch';
   
   // Check watch connectivity status
   const info = await CapgoWatch.getInfo();
   console.log('Watch paired:', info.isPaired);
   console.log('Watch reachable:', info.isReachable);
   
   // Listen for messages from watch
   await CapgoWatch.addListener('messageReceived', (event) => {
     console.log('Message from watch:', event.message);
   });

   Kirim Pesan ke Watch:

   // Check if watch is reachable first
   const info = await CapgoWatch.getInfo();
   if (info.isReachable) {
     await CapgoWatch.sendMessage({
       data: { action: 'refresh', timestamp: Date.now() }
     });
   }

   iOS

   Setup iOS yang Diperlukan:

   1. Tambahkan capability WatchConnectivity ke aplikasi iOS Anda di Xcode
   2. Buat target aplikasi watchOS di proyek Xcode Anda
   3. Implementasikan WatchConnectivity di aplikasi watchOS Anda (lihat Implementasi Watch App di bawah)

   Plugin otomatis mengaktifkan WCSession saat plugin dimuat.

   Android

   Setup Wear OS yang diperlukan:

   1. Tambahkan modul Wear OS ke proyek Android Anda (dengan applicationId package name dan signing yang sama dengan aplikasi ponsel).
   2. Deklarasikan capgo_watch capability di modul wear (lihat Membuat aplikasi Wear OS).
   3. Implementasikan listener Data Layer di watch menggunakan path plugin (/capgo/message, /capgo/context, dan lainnya).

   Plugin ponsel akan mendaftarkan listener Wearable API saat dimuat. Gunakan getInfo() untuk mengecek node yang terhubung dan apakah aplikasi watch terdeteksi.

   Langkah lengkap: Membuat aplikasi Wear OS.

4. Tangani pesan yang butuh balasan

   // Listen for messages that need a response
   await CapgoWatch.addListener('messageReceivedWithReply', async (event) => {
     console.log('Request from watch:', event.message);
   
     // Process the request
     const result = await processWatchRequest(event.message);
   
     // Send reply back to watch (include requestId for Wear OS correlation)
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: {
         requestId: event.message.requestId,
         result,
       },
     });
   });

5. Sinkronisasi state aplikasi

   // Update application context (latest value only)
   await CapgoWatch.updateApplicationContext({
     context: {
       theme: 'dark',
       userId: '123',
       lastSync: Date.now()
     }
   });
   
   // Listen for context updates from watch
   await CapgoWatch.addListener('applicationContextReceived', (event) => {
     console.log('Context from watch:', event.context);
   });

6. Transfer info user dengan andal

   // Queue data for reliable delivery (even when watch is offline)
   await CapgoWatch.transferUserInfo({
     userInfo: {
       recordId: '456',
       action: 'created',
       data: { name: 'Item 1' }
     }
   });
   
   // Listen for user info transfers
   await CapgoWatch.addListener('userInfoReceived', (event) => {
     console.log('User info from watch:', event.userInfo);
   });

7. Pantau konektivitas

   // Track reachability changes
   await CapgoWatch.addListener('reachabilityChanged', (event) => {
     console.log('Watch reachable:', event.isReachable);
     if (event.isReachable) {
       // Watch is now available for interactive messaging
     }
   });
   
   // Track session activation state
   await CapgoWatch.addListener('activationStateChanged', (event) => {
     // 0 = notActivated, 1 = inactive, 2 = activated
     console.log('Session state:', event.state);
   });

Mulai cepat

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

await CapgoWatch.sendMessage({
  data: { action: 'refresh', timestamp: Date.now() }
});

Contoh: updateApplicationContext

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

await CapgoWatch.updateApplicationContext({
  context: { theme: 'dark', lastSync: Date.now() }
});

Contoh: transferUserInfo

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

await CapgoWatch.transferUserInfo({
  userInfo: { recordId: '123', action: 'created' }
});

Kesalahan umum

• Listeners: hapus handle saat screen unmount.
• Sinkronisasi Native: jalankan bunx cap sync setelah upgrade plugin.
• Sumber kebenaran tunggal: percayai src/definitions.ts di repo GitHub.

Implementasi Watch App

Aplikasi watchOS Anda perlu mengimplementasikan WatchConnectivity. Berikut adalah contoh SwiftUI:

import SwiftUI
import WatchConnectivity

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

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

class WatchViewModel: NSObject, ObservableObject, WCSessionDelegate {
    static let shared = WatchViewModel()

    @Published var lastMessage: [String: Any] = [:]

    func activate() {
        guard WCSession.isSupported() else { return }
        WCSession.default.delegate = self
        WCSession.default.activate()
    }

    // Send message to iPhone
    func sendToPhone(_ data: [String: Any]) {
        guard WCSession.default.isReachable else {
            print("iPhone not reachable")
            return
        }
        WCSession.default.sendMessage(data, replyHandler: nil)
    }

    // Send message with reply
    func sendToPhoneWithReply(_ data: [String: Any], completion: @escaping ([String: Any]) -> Void) {
        guard WCSession.default.isReachable else { return }
        WCSession.default.sendMessage(data, replyHandler: completion)
    }

    // Receive message from iPhone
    func session(_ session: WCSession, didReceiveMessage message: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = message
        }
    }

    // Receive application context
    func session(_ session: WCSession, didReceiveApplicationContext applicationContext: [String: Any]) {
        DispatchQueue.main.async {
            self.lastMessage = applicationContext
        }
    }

    // Required delegate methods
    func session(_ session: WCSession, activationDidCompleteWith activationState: WCSessionActivationState, error: Error?) {
        print("Watch session activated: \(activationState.rawValue)")
    }
}

Referensi API

Metode

sendMessage(options: SendMessageOptions)

Kirim pesan interaktif ke watch. Watch harus dapat dijangkau.

Parameter:

• data: Object - Data yang akan dikirim ke watch

updateApplicationContext(options: UpdateContextOptions)

Perbarui context aplikasi. Hanya nilai terbaru yang disimpan.

Parameter:

• context: Object - Data context yang akan disinkronkan

transferUserInfo(options: TransferUserInfoOptions)

Antrekan info user untuk pengiriman yang andal.

Parameter:

• userInfo: Object - Info user yang akan ditransfer

replyToMessage(options: ReplyMessageOptions)

Balas pesan yang meminta respons.

Parameter:

• callbackId: string - Callback ID dari event messageReceivedWithReply
• data: Object - Data balasan

getInfo()

Dapatkan status konektivitas watch.

Mengembalikan: WatchInfo object dengan:

• isSupported: boolean - Apakah watch API tersedia di platform ini
• isPaired: boolean - Apple Watch dipasangkan (iOS) atau setidaknya satu node Wear OS terhubung (Android)
• isWatchAppInstalled: boolean - Aplikasi companion watch terinstal (iOS) atau capgo_watch kapabilitas terdeteksi (Android)
• isReachable: boolean - Apakah watch dapat dijangkau untuk pengiriman pesan instan
• activationState: number - Status sesi (iOS WCSession; Android 2 jika node terhubung, 0 jika tidak)

getPluginVersion()

Dapatkan versi plugin native.

Event

Event	Deskripsi
messageReceived	Pesan sederhana dari watch
messageReceivedWithReply	Pesan yang menunggu balasan (termasuk callbackId)
applicationContextReceived	Update konteks dari watch
userInfoReceived	Transfer info user dari watch
reachabilityChanged	Konektivitas watch berubah (khusus iOS)
activationStateChanged	Status aktivasi sesi berubah (khusus iOS)

Communication Patterns

Messaging Instan (sendMessage)

• Watch harus dapat dijangkau
• Terbaik untuk komunikasi interaktif yang sensitif waktu
• Gagal langsung jika watch tidak tersedia

Konteks Aplikasi (updateApplicationContext)

• Hanya nilai terbaru - nilai sebelumnya ditimpa
• Terbaik untuk menyinkronkan state aplikasi saat ini
• Dikirim saat watch kembali tersedia

Transfer Info Pengguna (transferUserInfo)

• Diantrekan dan dikirim sesuai urutan
• Terbaik untuk data penting yang wajib terkirim
• Tetap berfungsi meski watch sedang tidak terjangkau

Catatan Platform

Lihat tabel dukungan platform pada ringkasan plugin untuk matriks per metode.

iOS (Apple Watch)

• Membutuhkan iOS 15.0 atau versi terbaru
• Menggunakan framework WatchConnectivity
• Session otomatis aktif saat plugin dimuat
• Mendukung background delivery untuk context dan user info
• Mengeluarkan reachabilityChanged dan activationStateChanged

Android (Wear OS)

• Membutuhkan Google Play services dengan Wear OS Data Layer (play-services-wearable, sudah termasuk dalam plugin)
• APK Phone dan wear harus menggunakan sama applicationId dan signing key
• Aplikasi watch harus mengiklankan capability capgo_watch
• Apakah tidak emit reachabilityChanged atau activationStateChanged; poll getInfo() saat dibutuhkan
• Panduan setup: Membuat aplikasi Wear OS

Web

• Watch messaging tidak didukung di browser
• getInfo() selesai dengan isSupported: false dan field lainnya dengan default yang aman
• getPluginVersion() selesai dengan { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, dan replyToMessage tolak dengan error unavailable
• addListener menyelesaikan handle via Capacitor WebPlugin, tapi watch event tidak didukung di browser (callback tidak akan jalan)

Kasus Penggunaan Umum

1. Sinkronisasi Data: Jaga data watch dan ponsel tetap sinkron
2. Kontrol Jarak Jauh: Kontrol fitur ponsel dari watch
3. Notifikasi: Kirim notifikasi kustom ke watch
4. Data Kesehatan: Bagikan metrik kesehatan dan kebugaran
5. Kontrol Media: Kontrol pemutaran musik dari watch
6. Smart Home: Kontrol perangkat dari pergelangan tangan

Pemecahan Masalah

Watch tidak terjangkau:

• Pastikan watch berada dalam jangkauan Bluetooth
• Pastikan kedua aplikasi sedang berjalan
• Verifikasi WCSession sudah aktif di kedua sisi

Pesan tidak diterima:

• Pastikan listener sudah terdaftar sebelum mengirim
• Verifikasi watch app sudah mengimplementasikan WCSessionDelegate
• Gunakan transferUserInfo untuk pengiriman yang terjamin

Session tidak aktif:

• Pastikan capability WatchConnectivity sudah ditambahkan di Xcode
• Pastikan watch app memiliki companion bundle ID yang sesuai
• Verifikasi kedua app menargetkan versi OS yang kompatibel

Lanjutkan dari Getting Started

Jika Anda menggunakan Panduan Memulai untuk merencanakan pekerjaan plugin native, hubungkan dengan Menggunakan @capgo/capacitor-watch untuk fitur native di Menggunakan @capgo/capacitor-watch, Direktori Plugin Capgo untuk alur kerja produk di Direktori Plugin Capgo, Plugin Capacitor oleh Capgo untuk detail implementasi pada Capacitor Plugins oleh Capgo Menambahkan atau Memperbarui Plugin untuk detail implementasi di Menambahkan atau Memperbarui Plugin, dan Alternatif Plugin Ionic Enterprise untuk alur kerja produk dalam Alternatif Plugin Ionic Enterprise.