Avvio rapido

Istallazione

Puoi utilizzare la nostra configurazione assistita da AI per installare il plugin. Aggiungi le Capgo competenze al tuo strumento AI utilizzando il seguente comando:

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

Poi utilizza la seguente richiesta:

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

Se preferisci l'installazione 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 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 capacità WatchConnectivity al tuo'app iOS in Xcode
   2. Crea un'app target 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 carica.

   Android

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

4. Gestisci 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. Sync 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. Monitora 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

L'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)")
    }
}

Riferimento a API

Metodi

sendMessage(options: SendMessageOptions)

Inviare un messaggio interattivo al watch. Richiede che il watch sia raggiungibile.

Parametri:

• data: Oggetto - I dati da inviare al watch

updateApplicationContext(options: UpdateContextOptions)

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

Parametri:

• context: Oggetto - I dati di contesto da sincronizzare

transferUserInfo(options: TransferUserInfoOptions)

Inoltra informazioni utente per una consegna affidabile.

Parametri:

• userInfo: Oggetto - Le informazioni dell'utente da trasferire

replyToMessage(options: ReplyMessageOptions)

Rispondi a un messaggio che richiede una risposta.

Parametri:

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

getInfo()

Ottenere lo stato di connettività del watch.

Restituisce: WatchInfo oggetto con:

• isSupported: booleano - Se WatchConnectivity è disponibile
• isPaired: boolean - Se il dispositivo è pairato
• isWatchAppInstalled: boolean - Se l'applicazione del dispositivo è installata
• isReachable: boolean - Se il dispositivo è raggiungibile
• activationState: number - Stato della sessione (0/1/2)

getPluginVersion()

Ottieni la versione del plugin nativo.

Eventi

Evento	Descrizione
messageReceived	Messaggio semplice dal dispositivo
messageReceivedWithReply	Messaggio che aspetta una risposta (incluso callbackId)
applicationContextReceived	Aggiornamento del contesto da watch
userInfoReceived	Trasferimento delle informazioni dell'utente da watch
reachabilityChanged	Cambiamento della connettività del watch
activationStateChanged	Cambiamento dello stato di attivazione della sessione

Modelli di comunicazione

Messaggistica immediata (sendMessage)

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

Contexto dell'applicazione (updateApplicationContext)

• Valore più recente solo - i valori precedenti vengono sovrascritti
• Migliore per sincronizzare lo stato dell'applicazione corrente
• Invia quando il watch diventa disponibile

Trasferimento Informazioni Utente (transferUserInfo)

• In coda e inviato in ordine
• Migliore per i dati importanti che devono essere inviati
• Funziona anche quando il watch è 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
• Sostiene la consegna in background per contesto e informazioni utente

Android

• Non supportato (Apple Watch è disponibile solo per iOS)
• Tutti i metodi rifiutano con un errore appropriato
• getInfo() ritorna isSupported: false

Web

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

Uso comune

1. Sincronizzazione dati: Mantieni sincronizzati i dati dell'orologio e del telefono
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. Media Control: Controlla la riproduzione musicale dal watch
6. Smart Home: Controlla dispositivi dal polso

Risoluzione dei problemi

Non è possibile raggiungere il watch:

• Assicurati che il watch sia all'interno della portata Bluetooth
• Verifica che sia in esecuzione entrambi gli app
• Verifica che WCSession sia attivato su entrambi i lati

Non sono stati ricevuti i messaggi:

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

Sessione non attiva:

• Assicurati che la capacità WatchConnectivity sia aggiunta in Xcode
• Controlla che l'app Watch abbia l'ID bundle del companion
• Verifica che entrambe le app siano compatibili con le versioni OS

Continua da Iniziare

Se stai utilizzando Iniziare per pianificare il lavoro di plugin nativo, connettilo con Utilizzare @capgo/capacitor-watch per la capacità nativa in Utilizzare @capgo/capacitor-watch, Directory dei plugin Capgo per il flusso di lavoro del prodotto in Directory dei plugin Capgo, Plugin Capacitor di Capgo per il dettaglio di implementazione in Plugin Capacitor di Capgo, Aggiungere o Aggiornare Plugin per il dettaglio di implementazione in Aggiungere o Aggiornare Plugin, e Alternative per Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Alternative per Plugin Enterprise Ionic.