Primeros pasos

Instalación

Puedes usar nuestro setup asistido por IA para instalar el plugin. Añade las skills de Capgo a tu herramienta de IA con el siguiente comando:

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

Luego usa el siguiente prompt:

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

Si prefieres la configuración manual, instala el plugin ejecutando estos comandos y sigue las instrucciones de cada plataforma:

1. Instala el paquete

   bun add @capgo/capacitor-watch

2. Sincroniza con proyectos nativos

   bunx cap sync

3. Configura el plugin

   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 necesaria en iOS:

   1. Añade la capacidad WatchConnectivity a tu app de iOS en Xcode
   2. Crea un target de app watchOS en tu proyecto de Xcode
   3. Implementa WatchConnectivity en tu app de watchOS (ver Implementación de la app del reloj abajo)

   El plugin activa automáticamente la WCSession al cargarse.

   Android

   Configuración necesaria para Wear OS:

   1. Añade una Módulo Wear OS a tu proyecto de Android (el mismo applicationId y la misma firma que la app del teléfono).
   2. Declara la capgo_watch capacidad en el módulo wear (ver Crear una app para Wear OS).
   3. Implementa listeners de Data Layer en el reloj usando las rutas del plugin (/capgo/message, /capgo/context, y otros).

   El plugin de teléfono registra listeners de API para Wearables al cargar. Usa getInfo() para verificar los nodos conectados y si se detecta la app del reloj.

   Pasos completos: Crear una app para Wear OS.

4. Gestionar mensajes que requieren 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 info de usuario de forma 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 la 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);
   });

Inicio rápido

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.sendMessage({
  data: { action: 'refresh', timestamp: Date.now() }
});

Ejemplo: updateApplicationContext

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.updateApplicationContext({
  context: { theme: 'dark', lastSync: Date.now() }
});

Ejemplo: transferUserInfo

import { CapgoWatch } from '@capgo/capacitor-watch';

await CapgoWatch.transferUserInfo({
  userInfo: { recordId: '123', action: 'created' }
});

Errores comunes

• Listeners: elimina los handles cuando se desmonten las pantallas.
• Sync nativo: ejecuta bunx cap sync tras actualizar los plugins.
• Fuente de verdad: confianza src/definitions.ts en el repo de GitHub.

Implementación de la Watch App

Tu app de watchOS debe implementar WatchConnectivity. Aquí tienes un ejemplo en 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)")
    }
}

Referencia de API

Métodos

sendMessage(options: SendMessageOptions)

Envía un mensaje interactivo al watch. Requiere que el watch esté disponible.

Parámetros:

• data: Object - Los datos a enviar al watch

updateApplicationContext(options: UpdateContextOptions)

Actualiza el contexto de la aplicación. Solo se mantiene el último valor.

Parámetros:

• context: Object - Los datos de contexto a sincronizar

transferUserInfo(options: TransferUserInfoOptions)

Encola la info del usuario para un envío fiable.

Parámetros:

• userInfo: Object - La info del usuario a transferir

replyToMessage(options: ReplyMessageOptions)

Responde a un mensaje que solicitó una respuesta.

Parámetros:

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

getInfo()

Obtiene el estado de conectividad del watch.

Devuelve: WatchInfo objeto con:

• isSupported: boolean - Indica si las APIs de watch están disponibles en esta plataforma
• isPaired: boolean - Apple Watch vinculado (iOS) o al menos un nodo Wear OS conectado (Android)
• isWatchAppInstalled: boolean - App de acompañamiento instalada (iOS) o capgo_watch capacidad detectada (Android)
• isReachable: boolean - Si el watch es alcanzable para mensajería inmediata
• activationState: number - Estado de la sesión (iOS WCSession; Android 2 si hay un nodo conectado, 0 si no)

getPluginVersion()

Obtén la versión del plugin nativo.

Eventos

Evento	Descripción
messageReceived	Mensaje simple desde el watch
messageReceivedWithReply	Mensaje que espera respuesta (incluye callbackId)
applicationContextReceived	Actualización de contexto desde el watch
userInfoReceived	Transferencia de info de usuario desde el watch
reachabilityChanged	Cambio en la conectividad del watch (solo iOS)
activationStateChanged	Cambio en el estado de activación de sesión (solo iOS)

Patrones de comunicación

Mensajería inmediata (sendMessage)

• Requiere que el watch esté disponible
• Ideal para comunicación interactiva y urgente
• Falla de inmediato si watch no está disponible

Contexto de la aplicación (updateApplicationContext)

• Solo el último valor; los anteriores se sobrescriben
• Ideal para sincronizar el estado actual de la app
• Se entrega cuando watch está disponible

Transferencia de info de usuario (transferUserInfo)

• En cola y entregado en orden
• Ideal para datos críticos que deben entregarse
• Funciona incluso si watch no es alcanzable temporalmente

Notas de la plataforma

Consulta la tabla de soporte de plataformas en el overview del plugin para una matriz detallada por método.

iOS (Apple Watch)

• Requiere iOS 15.0 o superior
• Usa el framework WatchConnectivity
• La sesión se activa automáticamente al cargar el plugin
• Soporta background delivery para context y user info
• Emite reachabilityChanged y activationStateChanged

Android (Wear OS)

• Requiere Google Play services con Wear OS Data Layer (play-services-wearable, incluido en el plugin)
• Los APKs del teléfono y el reloj deben compartir la mismo applicationId y clave de firma
• La app del reloj debe anunciar la capacidad capgo_watch
• Emitir necesitas emite reachabilityChanged o activationStateChanged; poll getInfo() when needed
• Guía de configuración: Crear una app para Wear OS

Web

• Watch messaging no es compatible en el navegador
• getInfo() se resuelve con isSupported: false and other fields at safe defaults
• getPluginVersion() se resuelve con { version: "web" }
• sendMessage, updateApplicationContext, transferUserInfo, y replyToMessage rechazar con un error de no disponible
• addListener resuelve un handle mediante Capacitor WebPlugin, pero los eventos de watch no son compatibles en el navegador (los callbacks nunca se ejecutan)

Casos de uso comunes

1. Data Sync: Keep watch and phone data in sync
2. Control remoto: Controla funciones del teléfono desde el watch
3. Notificaciones: Envía notificaciones personalizadas al watch
4. Datos de salud: Comparte métricas de salud y fitness
5. Control multimedia: Controla la reproducción de música desde el reloj
6. Hogar inteligente: Controla dispositivos desde tu muñeca

Solución de problemas

Reloj no disponible:

• Asegúrate de que el reloj esté en rango Bluetooth
• Comprueba que ambas apps estén en ejecución
• Verifica que WCSession esté activada en ambos lados

Mensajes no recibidos:

• Verifica que los listeners estén registrados antes de enviar
• Comprueba que la app de Watch implemente WCSessionDelegate
• Usa transferUserInfo para garantizar la entrega

La sesión no se activa:

• Asegúrate de añadir la capability WatchConnectivity en Xcode
• Comprueba que la app de watch tenga el bundle ID correspondiente
• Comprueba que ambas apps apunten a versiones de OS compatibles

Continúa desde Getting Started

Si estás usando Primeros pasos para planificar el trabajo con plugins nativos, conéctalo con Usando @capgo/capacitor-watch para la capacidad nativa en Uso de @capgo/capacitor-watch, Directorio de plugins de Capgo para el flujo de trabajo del producto en Capgo Plugin Directory, Plugins de Capacitor por Capgo para el detalle de implementación en los Plugins de Capacitor por Capgo, Añadir o actualizar plugins para el detalle de implementación en Agregar o actualizar plugins, y Alternativas a plugins de Ionic Enterprise para el flujo de trabajo del producto en Alternativas a plugins de Ionic Enterprise.