Inicio

1. Instale el paquete

   bun add @capgo/capacitor-watch

2. Sincronice con proyectos nativos

   bunx cap sync

3. Configurar el complemento

   Ejemplo de uso básico:

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

   Enviar un mensaje 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

   Configuración de iOS requerida:

   1. Agregue la capacidad de WatchConnectivity a su aplicación de iOS en Xcode
   2. Cree una aplicación de objetivo de watchOS en su proyecto de Xcode
   3. Implemente WatchConnectivity en su aplicación de watchOS (consulte la implementación de la aplicación de reloj a continuación)

   El complemento activa automáticamente la sesión WC cuando se carga el complemento.

   Android

   El reloj de Apple solo se admite en iOS. En Android, todos los métodos rechazarán con el error "El reloj de Apple solo se admite en iOS". getInfo() devuelve isSupported: false.

4. Atender mensajes que requieren una respuesta

   // 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. Sincronizar el estado de la aplicación

   // 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. Transferir información de usuario de manera confiable

   // 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. Monitorear conectividad

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

Implementación de la aplicación de reloj

Su aplicación de reloj de Apple Watch necesita implementar WatchConnectivity. Aquí hay un ejemplo de 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 Referencia

Métodos

sendMessage(options: SendMessageOptions)

Enviar un mensaje interactivo al reloj. Requiere que el reloj esté disponible.

Parámetros:

• data: Objeto - Los datos a enviar al reloj

updateApplicationContext(options: UpdateContextOptions)

Actualizar contexto de la aplicación. Solo se mantiene el valor más reciente.

Parámetros:

• context: Objeto - Los datos de contexto para sincronizar

transferUserInfo(options: TransferUserInfoOptions)

Coloque la información del usuario para su entrega confiable.

Parámetros:

• userInfo: Object - La información del usuario a transferir

replyToMessage(options: ReplyMessageOptions)

Responder a un mensaje que solicitó una respuesta.

Parámetros:

• callbackId: string - El ID de llamada de respuesta del evento messageReceivedWithReply
• data: Object - Los datos de respuesta

getInfo()

Obtener el estado de conectividad de la aplicación.

Devuelve: WatchInfo objeto con:

• isSupported: boolean - ¿Se encuentra disponible la conectividad de reloj?
• isPaired: boolean - ¿Está pairado el reloj?
• isWatchAppInstalled: boolean - ¿Está instalado el reloj en la aplicación?
• isReachable: boolean - ¿Está disponible el reloj?
• activationState: número - Estado de la sesión (0/1/2)

getPluginVersion()

Obtenga la versión nativa del plugin.

Eventos

Evento	Descripción
messageReceived	Mensaje simple desde el reloj
messageReceivedWithReply	Mensaje que espera una respuesta (incluye callbackId)
applicationContextReceived	Actualización de contexto desde el reloj
userInfoReceived	Transferencia de información del usuario desde el reloj
reachabilityChanged	Se ha cambiado la conectividad del reloj
activationStateChanged	Se ha cambiado el estado de activación de la sesión

Patrones de comunicación

Mensajería inmediata (sendMessage)sendMessage)

• Requiere que el reloj esté disponible
• Mejor para la comunicación interactiva y sensible al tiempo
• Fallará inmediatamente si no está disponible la función de seguimiento

Contexto de la aplicación (updateApplicationContext)

• Último valor solo - los valores anteriores se sobrescriben
• Mejor para sincronizar el estado actual de la aplicación
• Se entrega cuando se vuelva a conectar la función de seguimiento

Transferencia de información del usuario (transferUserInfo)

• Programado y se entrega en orden
• Mejor para datos importantes que deben ser entregados
• Funciona incluso cuando la función de seguimiento esté temporalmente inalcanzable

Notas de la plataforma

iOS

• Requiere iOS 15.0 o posterior
• Utiliza el marco de trabajo de WatchConnectivity
• La sesión se activa automáticamente al cargar el plugin
• Soporta entrega de fondo para contexto y información del usuario

Android

• No soportado (Apple Watch es solo para iOS)
• Todos los métodos rechazan con el error apropiado
• getInfo() devuelve isSupported: false

Web

• No soportado
• Todos los métodos rechazan con error de no disponible
• getInfo() devuelve isSupported: false

Uso común

1. Sincronización de datos: Mantener sincronizados los datos del teléfono y del reloj
2. Control remoto: Controlar las características del teléfono desde el reloj
3. Notificaciones: Enviar notificaciones personalizadas a la muñeca
4. Datos de Salud: Compartir métricas de fitness y salud
5. Control de Medios: Controlar reproducción de música desde la muñeca
6. Casa Inteligente: Controlar dispositivos desde el antebrazo

Solución de Problemas

La muñeca no está accesible:

• Asegúrese de que la muñeca esté dentro del rango de Bluetooth
• Verifique que ambas aplicaciones estén en ejecución
• Verificar que WCSession está activado en ambos lados

No se recibieron mensajes:

• Compruebe que los oyentes estén registrados antes de enviar
• Verificar que la aplicación de reloj implementa WCSessionDelegate
• Usar transferUserInfo para una entrega garantizada

No se está activando la sesión:

• Asegúrese de que la capacidad de WatchConnectivity esté agregada en Xcode
• Compruebe que la aplicación de reloj tenga el ID de paquete de compañero
• Verificar que ambas aplicaciones tengan versiones de sistema operativo compatibles