Getting Started

Instalación

Puede utilizar nuestra configuración asistida por IA para instalar el plugin. Agregue las Capgo habilidades a su herramienta de IA utilizando el siguiente comando:

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

Luego utilice la siguiente solicitud:

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

Si prefiere la configuración manual, instale el complemento ejecutando los siguientes comandos y siguiendo las instrucciones específicas de la plataforma a continuación:

1. Instalar el paquete

   bun add @capgo/capacitor-watch

2. Sincronizar 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. Agregar la capacidad de WatchConnectivity a tu aplicación de iOS en Xcode
   2. Crear un objetivo de aplicación de watchOS en tu proyecto de Xcode
   3. Implementar WatchConnectivity en tu aplicación de watchOS (ver Implementación de la aplicación de reloj a continuación)

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

   Android

   Configuración de Wear OS requerida:

   1. Agregar un módulo de Wear OS a tu proyecto de Android (igual que applicationId y firmado como la aplicación del teléfono).
   2. Declara la capgo_watch capacidad en el módulo de reloj (ver Crear una aplicación de reloj OS).
   3. Implementa escuchadores de capa de datos en el reloj utilizando las rutas del plugin (/capgo/message, /capgo/context, and others).

   El plugin de teléfono registra escuchadores de reloj Wearable API cuando se carga. Utiliza getInfo() para verificar los nodos conectados y si se detecta la aplicación del reloj.

   Pasos completos: Crear una aplicación de reloj OS.

4. Gestiona 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 (include requestId for Wear OS correlation)
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: {
         requestId: event.message.requestId,
         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 fiable

   // 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 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 el contexto de la aplicación. Solo el último valor se mantiene.

Parámetros:

• context: Objeto - Los datos de contexto para sincronizar

transferUserInfo(options: TransferUserInfoOptions)

Informar datos del usuario para una entrega confiable.

Parámetros:

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

replyToMessage(options: ReplyMessageOptions)

Responder a un mensaje que solicitó una respuesta.

Parámetros:

• callbackId: string - El ID de callback desde el evento messageReceivedWithReply
• data: Object - Los datos de respuesta

getInfo()

Obtener el estado de conectividad de la reloj.

Devuelve: WatchInfo un objeto con:

• isSupported: boolean - ¿Están disponibles las APIs de reloj en esta plataforma
• isPaired: boolean - Reloj Apple conectado (iOS) o al menos un nodo Wear OS conectado (Android)
• isWatchAppInstalled: boolean - Aplicación de reloj de acompañamiento instalada (iOS) o capgo_watch : boolean - Capacidad detectada (Android)
• isReachable: boolean - ¿Está el reloj disponible para mensajería inmediata?
• activationStateNúmero - Estado de sesión (WCSession de iOS; 2 cuando un nodo está conectado, 0 en caso contrario)

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	Cambio de conectividad del reloj (solo iOS)
activationStateChanged	Estado de activación de la sesión cambiado (solo iOS)

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
• Falla inmediatamente si no está disponible el reloj

Contexto de la aplicación (updateApplicationContext)

• Último valor solo - los valores anteriores se sobrescriben
• Best for syncing current app state
• Se entrega cuando el reloj se vuelva disponible

Transferencia de información del usuario (transferUserInfo)

• Pendiente y se entrega en orden
• Mejor para datos importantes que deben ser entregados
• Funciona incluso cuando el reloj esté temporalmente inalcanzable

Notas de la plataforma

Consulte la tabla de soporte de la plataforma en la página de visión general del plugin para una matriz método por método.

iOS (Apple Watch)

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

Android (Wear OS)

• Requiere servicios de Google Play con capa de datos de Wear OS (play-services-wearable, incluido con el complemento)
• Los APKs de teléfono y reloj deben compartir el mismo applicationId y clave de firma
• La aplicación de reloj debe anunciar la capacidad capgo_watch
• ¿ no emite reachabilityChanged o activationStateChanged; encuesta getInfo() when needed
• Guía de configuración: Crear una aplicación de Wear OS

Web

• El mensaje de la reloj no se admite en el navegador
• getInfo() se resuelve con isSupported: false y otros campos en valores predeterminados seguros
• getPluginVersion() se resuelve con { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, y replyToMessage rechaza con un error no disponible
• addListener resuelve un manejador a través de Capacitor WebPluginPero los eventos de watch no están soportados en el navegador (las llamadas de llamada nunca se ejecutan)

Casos de uso comunes

1. Data SyncSincronice datos de reloj y teléfono
2. Control remotoControla características del teléfono desde el reloj
3. Notificaciones: Envíe notificaciones personalizadas al reloj
4. Datos de salud: Compartir métricas de fitness y salud
5. Control de medios: Controlar reproducción de música desde el reloj
6. Hogar inteligente: Controlar dispositivos desde el antebrazo

Solución de problemas

El reloj no está accesible:

• Ensure watch is within Bluetooth range
• Verifique que ambos aplicativos estén en ejecución
• Verifique que WCSession esté activado en ambos lados

Los mensajes no se reciben:

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

No se activa la sesión:

• Asegúrese de que la capacidad de WatchConnectivity esté agregada en Xcode
• Verificar que la aplicación de reloj tenga el ID de paquete de compañero
• Verify both apps target compatible OS versions

Siga adelante desde Inicio

Si está utilizando Getting Started para planificar el trabajo de plugin nativo, conecte con Usando @capgo/capacitor-watch para la capacidad nativa en Usando @capgo/capacitor-watch, Directorio de Plugins Capgo para el flujo de trabajo del producto en Directorio de Plugins Capgo, Plugins de Capacitor por Capgo para el detalle de implementación en Plugins de Capacitor por Capgo, Agregar o Actualizar Plugins para el detalle de implementación en Agregar o Actualizar Plugins, y Alternativas de Plugins de Ionic Enterprise para el flujo de trabajo del producto en Ionic Enterprise Plugin Alternatives.