Getting Started

Installazione

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

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

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

   Inviare 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 obbligatoria:

   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 si carica.

   Android

   Configurazione obbligatoria Wear OS:

   1. Aggiungi un modulo Wear OS aggiungilo al tuo progetto Android (lo stesso applicationId e firme come l'app del telefono).
   2. Declara la capgo_watch capacità nel modulo Wear (vedi Creazione di un'app Wear OS).
   3. Implementa gli ascoltatori del layer dati sul orologio utilizzando le percorsi del plugin (/capgo/message, /capgo/context, and others).

   Il plugin del telefono registra gli ascoltatori Wearable API quando si carica. Utilizza getInfo() per verificare i nodi connessi e se l'app dell'orologio è rilevata.

   Passaggi completi: Creazione di un'app Wear OS.

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

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

Riferimento API

Metodi

sendMessage(options: SendMessageOptions)

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

Parametri:

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

updateApplicationContext(options: UpdateContextOptions)

Update application context. Only latest value is kept.

Parametri:

• context: Oggetto - I dati di contesto da sincronizzare

transferUserInfo(options: TransferUserInfoOptions)

Informa l'utente in coda 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: stringa - L'ID di callback dal messaggio ricevuto con evento messageReceivedWithReply
• data: Oggetto - I dati di risposta

getInfo()

Otteni lo stato di connettività del watch.

Restituisce: WatchInfo oggetto con:

• isSupported: boolean - Sono disponibili le API watch su questa piattaforma
• isPaired: boolean - Apple Watch pairato (iOS) o almeno un nodo Wear OS collegato (Android)
• isWatchAppInstalled: boolean - Applicazione watch di accompagnamento installata (iOS) o capgo_watch : capacità rilevata (Android)
• isReachable: boolean - Se il watch è raggiungibile per la messaggistica istantanea
• activationState: numero - Stato della sessione (iOS WCSession; Android 2 quando un nodo è collegato, 0 altrimenti)

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 dell'utente dal watch
reachabilityChanged	Connessione Watch modificata (solo iOS)
activationStateChanged	Session activation state changed (iOS only)

Pattini di comunicazione

Invio di messaggi istantaneo (sendMessage)

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

Contexto dell'Applicazione (updateApplicationContext)

• Solo il valore più recente - i precedenti vengono sovrascritti
• Best for syncing current app state
• Deliverato quando il watch diventa disponibile

Trasferimento di Informazioni Utente (transferUserInfo)

• In coda e consegnato in ordine
• Migliore per i dati importanti che devono essere consegnati
• Funziona anche quando il watch è temporaneamente inaccessibile

Note di piattaforma

Vedi la tabella di supporto della piattaforma su la panoramica del plugin per una matrice dei metodi.

IOS (Apple Watch)

• 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
• Emette reachabilityChanged E e activationStateChanged

E Android (Wear OS)

• Richiede Google Play services con Wear OS Data Layer (play-services-wearableIncluso con il plugin)
• APKs per dispositivo devono condividere E lo stesso applicationId E e chiave di firma
• L'app dell'orologio deve pubblicizzare la capacità capgo_watch
• Fa no emit reachabilityChanged o activationStateChangedo quando serve getInfo() quando necessario
• Creare un'app per Wear OS Creazione di un'app per Wear OS

Web

• La messaggistica Watch non è supportata nel browser
• getInfo() risolve con isSupported: false and other fields at safe defaults
• getPluginVersion() risolve con { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfoe replyToMessage rifiuta con un errore non disponibile
• addListener risolve un handle tramite Capacitor WebPluginma gli eventi watch non sono supportati nel browser (le callback non vengono eseguite)

Utilizzo Comune

1. Data SyncMantieni sincronizzati dati di orologio e telefono
2. Controllo remoto: Controlla le funzionalità del telefono dal watch
3. Notifications: Invia notifiche personalizzate al watch
4. Dati di Salute: Condividi metriche di fitness e salute
5. Controllo Media: Controlla la riproduzione musicale dal watch
6. Casa Intelligente: Controlla dispositivi dal polso

Troubleshooting

Impossibile raggiungere il watch:

• Ensure watch is within Bluetooth range
• Controlla che entrambe le app siano in esecuzione
• Verifica che WCSession sia attivato su entrambi i lati

Non ricevuti messaggi:

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

La sessione non si attiva:

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

Continua da Getting Started

Se stai utilizzando Getting Started 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 workflow del prodotto nella directory del plugin Capgo Plugin Capacitor di Capgo per la dettaglio di implementazione in Plugin Capacitor di Capgo Aggiungere o Aggiornare i Plugin per la dettaglio di implementazione in Aggiungere o Aggiornare i Plugin, e Alternative per Plugin Enterprise Ionic per il flusso di lavoro del prodotto in Alternative per Plugin Enterprise Ionic