Per iniziare

Installazione

Puoi usare il nostro setup assistito dall'IA per installare il plugin. Aggiungi le skill Capgo al tuo strumento di IA usando il seguente comando:

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

Poi usa il seguente prompt:

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

Se preferisci la configurazione manuale, installa il plugin eseguendo questi comandi e segui le istruzioni specifiche per piattaforma qui sotto:

1. Installa il pacchetto

   bun add @capgo/capacitor-watch

2. Sincronizza con i progetti nativi

   bunx cap sync

3. Configura il plugin

   Esempio di utilizzo base:

   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);
   });

   Invia un messaggio a 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

   Configurazione iOS richiesta:

   1. Aggiungi la capability WatchConnectivity alla tua app iOS in Xcode
   2. Crea un target per l'app watchOS nel tuo progetto Xcode
   3. Implementa WatchConnectivity nella tua app watchOS (vedi Implementazione dell'app Watch sotto)

   Il plugin attiva automaticamente la WCSession quando viene caricato.

   Android

   Setup Wear OS richiesto:

   1. Aggiungi un Modulo Wear OS al tuo progetto Android (stesso applicationId e stessa firma dell'app per smartphone).
   2. Dichiara la capgo_watch capability nel modulo wear (vedi Creazione di un'app Wear OS).
   3. Implementa i listener del Data Layer sull'orologio usando i path del plugin (/capgo/message, /capgo/context, e altri).

   Il plugin per telefono registra i listener API Wearable al caricamento. Usa getInfo() per controllare i nodi connessi e se l'app per smartwatch viene rilevata.

   Passaggi completi: Creazione di un'app Wear OS.

4. Gestire i messaggi che richiedono una risposta

   // 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. Sincronizzare lo stato dell'applicazione

   // 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. Trasferire le info utente in modo affidabile

   // 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. Monitorare la connettività

   // 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);
   });

Avvio rapido

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

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

Esempio: updateApplicationContext

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

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

Esempio: transferUserInfo

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

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

Errori comuni

• Listener: rimuovi gli handle quando gli schermi vengono smontati.
• Sync nativo: esegui bunx cap sync dopo gli aggiornamenti dei plugin.
• Fonte di verità: fidati src/definitions.ts nel repo GitHub.

Implementazione Watch App

La tua app watchOS deve implementare WatchConnectivity. Ecco un esempio in 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)")
    }
}

Riferimento API

Metodi

sendMessage(options: SendMessageOptions)

Invia un messaggio interattivo allo smartwatch. Richiede che lo smartwatch sia raggiungibile.

Parametri:

• data: Oggetto - I dati da inviare allo smartwatch

updateApplicationContext(options: UpdateContextOptions)

Aggiorna il contesto dell'applicazione. Viene mantenuto solo l'ultimo valore.

Parametri:

• context: Oggetto - I dati del contesto da sincronizzare

transferUserInfo(options: TransferUserInfoOptions)

Metti in coda le info utente per una consegna affidabile.

Parametri:

• userInfo: Object - Le info utente da trasferire

replyToMessage(options: ReplyMessageOptions)

Rispondi a un messaggio che richiede una risposta.

Parametri:

• callbackId: string - Il callback ID dell'evento messageReceivedWithReply
• data: Object - I dati della risposta

getInfo()

Ottieni lo stato di connettività del watch.

Restituisce: WatchInfo oggetto con:

• isSupported: boolean - Indica se le API watch sono disponibili su questa piattaforma
• isPaired: boolean - Apple Watch associato (iOS) o almeno un nodo Wear OS connesso (Android)
• isWatchAppInstalled: boolean - App companion installata (iOS) o capgo_watch capability rilevata (Android)
• isReachable: boolean - Se lo smartwatch è raggiungibile per l'invio immediato di messaggi
• activationState: number - Stato della sessione (iOS WCSession; Android 2 se un nodo è connesso, altrimenti 0)

getPluginVersion()

Ottieni la versione del plugin nativo.

Eventi

Evento	Descrizione
messageReceived	Messaggio semplice dall'watch
messageReceivedWithReply	Messaggio in attesa di risposta (include callbackId)
applicationContextReceived	Aggiornamento contesto dall'watch
userInfoReceived	Trasferimento info utente dall'watch
reachabilityChanged	Connettività watch cambiata (solo iOS)
activationStateChanged	Stato attivazione sessione cambiato (solo iOS)

Pattern di comunicazione

Messaggistica immediata (sendMessage)

• Richiede che l'watch sia raggiungibile
• Ideale per comunicazioni interattive e urgenti
• Fallisce immediatamente se watch non è disponibile

Contesto dell'applicazione (updateApplicationContext)

• Solo l'ultimo valore - i precedenti vengono sovrascritti
• Ideale per sincronizzare lo stato attuale dell'app
• Inviato quando watch diventa disponibile

Trasferimento info utente (transferUserInfo)

• Messo in coda e consegnato in ordine
• Ideale per dati critici che devono essere consegnati
• Funziona anche se watch è temporaneamente irraggiungibile

Note sulla piattaforma

Guarda il tabella di supporto delle piattaforme nella panoramica del plugin per una matrice metodo per metodo.

iOS (Apple Watch)

• Richiede iOS 15.0 o versioni successive
• Utilizza il framework WatchConnectivity
• La sessione si attiva automaticamente al caricamento del plugin
• Supporta la consegna in background per context e user info
• Emette reachabilityChanged e activationStateChanged

Android (Wear OS)

• Richiede Google Play services con Wear OS Data Layer (play-services-wearable, incluso nel plugin)
• Gli APK di telefono e watch devono condividere la stesso applicationId e chiave di firma
• L'app per watch deve dichiarare la capability capgo_watch
• Emette hai emette reachabilityChanged o activationStateChanged; polling getInfo() quando necessario
• Guida alla configurazione: Creazione di un'app Wear OS

Web

• Il messaging Watch non è supportato nel browser
• getInfo() risolve con isSupported: false e altri campi con valori predefiniti sicuri
• getPluginVersion() risolve con { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, e replyToMessage rifiuta con un errore unavailable
• addListener risolve un handle tramite Capacitor WebPlugin, ma gli eventi watch non sono supportati nel browser (i callback non vengono eseguiti)

Casi d'uso comuni

1. Data Sync: Mantieni sincronizzati watch e smartphone
2. Controllo remoto: Controlla le funzioni del telefono dal watch
3. Notifications: Invia notifiche personalizzate allo smartwatch
4. Dati salute: Condividi metriche di fitness e salute
5. Controllo Media: Controlla la riproduzione musicale dall'orologio
6. Smart Home: Controlla i dispositivi dal polso

Risoluzione problemi

Watch non raggiungibile:

• Assicurati che l'orologio sia nel raggio Bluetooth
• Verifica che entrambe le app siano attive
• Verifica che WCSession sia attivata su entrambi i lati

Messaggi non ricevuti:

• Verifica che i listener siano registrati prima dell'invio
• Verifica che l'app Watch implementi WCSessionDelegate
• Usa transferUserInfo per una consegna garantita

Sessione non attiva:

• Assicurati che la capability WatchConnectivity sia aggiunta in Xcode
• Controlla che l'app Watch abbia il bundle ID del companion
• Verifica che entrambe le app puntino a versioni OS compatibili

Continua da Getting Started

Se stai usando Per iniziare per pianificare il lavoro sui plugin nativi, collegalo a Utilizzo di @capgo/capacitor-watch per la funzionalità nativa in Utilizzo di @capgo/capacitor-watch, Directory dei plugin di Capgo per il workflow del prodotto nella Capgo Plugin Directory, Plugin Capacitor di Capgo per i dettagli di implementazione in Capacitor Plugins di Capgo, Aggiunta o aggiornamento dei plugin per i dettagli su come aggiungere o aggiornare i plugin, e Alternative ai plugin Ionic Enterprise per il workflow del prodotto in Alternative ai plugin Ionic Enterprise.