Inicio rápido

Instalación

Puedes utilizar nuestra configuración asistida por inteligencia artificial para instalar el complemento. Agrega las Capgo habilidades a tu herramienta de inteligencia artificial utilizando el siguiente comando:

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

Luego utiliza 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 complemento ejecutando los siguientes comandos y sigue las instrucciones específicas del plataforma a continuación:

1. Instalar el paquete

   bun add @capgo/capacitor-watch

2. Sync con proyectos nativos

   bunx cap sync

3. Configurar 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 de iOS requerida:

   1. Agregar la capacidad de WatchConnectivity a tu aplicación iOS en Xcode
   2. Crea una aplicación objetivo de reloj en tu proyecto de Xcode
   3. Implementa WatchConnectivity en tu aplicación de reloj (ver Implementación de 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 "Apple Watch is only supported on iOS". getInfo() El método devuelve isSupported: false.

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
     await CapgoWatch.replyToMessage({
       callbackId: event.callbackId,
       data: { result }
     });
   });

5. Sincroniza 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. Transfiere 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. Monitorea 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);
   });

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 Reference

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 a la reloj

updateApplicationContext(options: UpdateContextOptions)

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

Parámetros:

• context: Objeto - Los datos de contexto para sincronizar

transferUserInfo(options: TransferUserInfoOptions)

Cola la información de usuario para una entrega confiable.

Parámetros:

• userInfo: Objeto - La información de usuario para transferir

replyToMessage(options: ReplyMessageOptions)

Contestar a un mensaje que solicitó una respuesta.

Parámetros:

• callbackId: __CAPGO_KEEP_0__ - El ID de llamada de respuesta del evento messageReceivedWithReply
• data: __CAPGO_KEEP_0__ - Los datos de la respuesta

getInfo()

Obtener el estado de conectividad de la reloj.

Devuelve: WatchInfo objeto con:

• isSupported: __CAPGO_KEEP_0__ - Si WatchConnectivity está disponible
• isPaired: __CAPGO_KEEP_0__ - Si se ha pairado una reloj
• isWatchAppInstalled: __CAPGO_KEEP_0__ - Si se ha instalado una aplicación de reloj
• isReachable: __CAPGO_KEEP_0__ - Si la reloj está accesible
• activationState: __CAPGO_KEEP_0__ - 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	Cambio de conectividad del reloj
activationStateChanged	Estado de activación de la sesión cambiado

Patrones de comunicación

Mensajería Inmediata (sendMessage)

• Requerido que el reloj esté disponible
• Mejor para la comunicación interactiva y sensible al tiempo
• Falla inmediatamente si el reloj no está disponible

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 el reloj se vuelva disponible

Transferencia de Información del Usuario (transferUserInfo)

• Programado y entregado en orden
• Mejor para datos importantes que deben ser entregados
• Funciona incluso cuando el reloj 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
• Apoya la entrega de fondo para contexto y información del usuario

Android

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

Web

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

Uso común

1. Sync de datos: Mantén sincronizado los datos de reloj y teléfono
2. Control remoto: Controla las características del teléfono desde el reloj
3. Notificaciones: Envía notificaciones personalizadas al reloj
4. Datos de salud: Comparte métricas de fitness y salud
5. Control de medios: Controla la reproducción de música desde el reloj
6. Casa inteligente: Controla dispositivos desde el antebrazo

Resolución de problemas

No se puede alcanzar el reloj:

• Asegúrese de que el reloj esté dentro del rango de Bluetooth
• Verifique que ambas aplicaciones estén en ejecución
• Verifique que WCSession esté activado en ambos lados

No se reciben mensajes:

• Verifique que los oyentes estén registrados antes de enviar
• Verifique que la aplicación del reloj implemente WCSessionDelegate
• Utilice transferUserInfo para garantizar la entrega

No se activa la sesión:

• Asegúrese de que la capacidad de WatchConnectivity esté agregada en Xcode
• Verifique que la aplicación de reloj tenga el identificador de paquete de compañero
• Verifique que ambas aplicaciones estén dirigidas a versiones de sistema operativo compatibles

Siga adelante desde Getting Started

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, Capgo Directorio de Plugin para el flujo de trabajo del producto en Capgo Directorio de Plugin, Capacitor Plugins by Capgo for the implementation detail in Capacitor Plugins by 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 Alternativas de Plugins de Ionic Enterprise.