Inizio

Installazione

Puoi utilizzare la nostra configurazione assistita dall'IA per installare il plugin. Aggiungi le Capgo abilità al tuo strumento di AI utilizzando il seguente comando:

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

Usa poi 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 i seguenti comandi e segui le istruzioni specifiche per la piattaforma riportate di seguito:

1. Installa il pacchetto

   bun add @capgo/capacitor-watch

2. Sincronizza con 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 al 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 obbligatoria:

   1. Aggiungi la capacità WatchConnectivity al tuo'app iOS in Xcode
   2. Crea un obiettivo watchOS nel tuo progetto Xcode
   3. Implementa WatchConnectivity nell'app watchOS (vedi Implementazione dell'app Watch di seguito)

   Il plugin attiva automaticamente la WCSession quando il plugin si carica.

   Android

   L'Apple Watch è supportata solo su iOS. Su Android, tutti i metodi rifiuteranno con l'errore "Apple Watch è supportata solo su iOS". getInfo() il metodo restituisce isSupported: false.

4. Tratta 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
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: { result }
     });
   });

5. Sincronizza 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. Trasferisci informazioni 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 connessione

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

Implementazione dell'app Watch

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

API Reference

Metodi

sendMessage(options: SendMessageOptions)

Invia un messaggio interattivo all'orologio. Richiede che l'orologio sia raggiungibile.

Parametri:

• data: Oggetto - I dati da inviare all'orologio

updateApplicationContext(options: UpdateContextOptions)

Aggiorna il contesto dell'applicazione. Solo l'ultima versione viene conservata.

Parametri:

• context: Oggetto - I dati del contesto da sincronizzare

transferUserInfo(options: TransferUserInfoOptions)

Inoltra le informazioni utente per una consegna affidabile.

Parametri:

• userInfo: Oggetto - Le informazioni utente da trasferire

replyToMessage(options: ReplyMessageOptions)

Rispondi a un messaggio che richiedeva una risposta.

Parametri:

• callbackId: string - L'ID di callback dal messaggio messageReceivedWithReply evento
• data: Oggetto - I dati di risposta

getInfo()

Ottenere lo stato di connettività dell'orologio.

Restituisce: WatchInfo oggetto con:

• isSupported: boolean - Se WatchConnectivity è disponibile
• isPaired: boolean - Se è presente un orologio
• isWatchAppInstalled: boolean - Se è installato l'applicazione dell'orologio
• isReachable: boolean - Se l'orologio è raggiungibile
• activationStateNumero - Stato della sessione (0/1/2)

getPluginVersion()

Ottieni la versione del plugin nativo.

Eventi

Evento	Descrizione
messageReceived	Messaggio semplice dal watch
messageReceivedWithReply	Messaggio che aspetta una risposta (include id di callback)
applicationContextReceived	Aggiornamento del contesto dal watch
userInfoReceived	Trasferimento di informazioni utente dal watch
reachabilityChanged	Modifiche alla connessione del watch
activationStateChanged	Stato di attivazione della sessione modificato

Pattini di comunicazione

Invio messaggi istantanei (sendMessage)

• Richiede che il watch sia raggiungibile
• Ottimo per la comunicazione interattiva e a tempo di reazione
• Fallisce immediatamente se il watch non è disponibile

Contexto dell'applicazione (updateApplicationContext)

• Valore più recente solo - precedenti valori sovrascritti
• Ottimo per sincronizzare lo stato corrente dell'applicazione
• Spedito quando l'orologio diventa disponibile

Trasferimento informazioni utente (transferUserInfo)

• In coda e spedito in ordine
• Migliore per i dati importanti che devono essere spediti
• Funziona anche quando l'orologio è temporaneamente inaccessibile

Note sulla piattaforma

iOS

• Richiede iOS 15.0 o successivo
• Utilizza il framework WatchConnectivity
• La sessione si attiva automaticamente al caricamento del plugin
• Supporta la consegna in background per contesto e informazioni utente

Android

• Non supportato (Apple Watch è iOS-only)
• Tutti i metodi rifiutano con l'errore appropriato
• getInfo() returns isSupported: false

Web

• Non supportato
• Tutti i metodi rifiutano con errore non disponibile
• getInfo() returns isSupported: false

Utilizzo comune

1. Sincronizzazione dati: Mantieni sincronizzati i dati del telefono e dell'orologio
2. Controllo remoto: Controlla le funzionalità del telefono dall'orologio
3. Notifiche: Invia notifiche personalizzate all'orologio
4. Dati di salute: Condividi metriche di fitness e salute
5. Controllo media: Controlla la riproduzione della musica dall'orologio
6. Casa intelligenteControlla dispositivi dal polso

Risoluzione dei problemi

Orologio non raggiungibile:

• Assicurati che l'orologio sia all'interno della portata Bluetooth
• Verifica che entrambe le app siano in esecuzione
• Verifica che WCSession sia attivato su entrambi i lati

Messaggi non ricevuti:

• Verifica che i listener siano registrati prima di inviare
• Verifica che l'app orologio implementi WCSessionDelegate
• Usa transferUserInfo per consegna garantita

Sessione non attiva:

• Assicurati di aggiungere la capacità WatchConnectivity in Xcode
• Controlla che l'app orologio abbia l'ID bundle di accompagnamento
• Verifica che entrambe le app puntino a versioni OS compatibili

Continua da Getting Started

Getting Started per pianificare il lavoro di plugin nativo, connettilo con Utilizzando @__CAPGO_KEEP_0__/__CAPGO_KEEP_1__-orologio per la capacità nativa in Utilizzando @capgo/capacitor-orologio, for the native capability in Using @capgo/capacitor-watch, Capgo Plugin Directory per il workflow del prodotto nella Directory dei plugin Capgo, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by Capgo, Aggiunta o Aggiornamento dei plugin per il dettaglio di implementazione in Aggiunta o Aggiornamento dei plugin, e Alternative plugin Enterprise Ionic per il workflow del prodotto in Alternative plugin Enterprise Ionic.