Crear una app para watchOS
Copia un prompt de configuración con los pasos de instalación y la guía completa en markdown para este plugin.
Esta guía te explica cómo crear un watchOS app de acompañamiento desde cero, incluida la configuración del proyecto en Xcode, la integración de CapgoWatchSDK y la creación de una app de reloj funcional con SwiftUI.
Para Wear OS, usa Crear una app para Wear OS en su lugar.
Requisitos
Sección titulada “Prerrequisitos”Antes de comenzar, asegúrate de tener:
- Xcode 15 o posterior (descárgalo de la Mac App Store)
- macOS Sonoma o posterior (para la última versión de watchOS SDK)
- Un proyecto iOS existente de Capacitor (ejecuta
npx cap add iossi aún no lo has hecho) - Cuenta de Apple Developer (la cuenta gratuita sirve para desarrollo)
Resumen de la estructura del proyecto
Sección titulada “Resumen de la estructura del proyecto”Tras completar esta guía, tu proyecto tendrá esta estructura:
Directorioios/
DirectorioApp/
DirectorioApp/ (tu app principal de iOS)
- …
- App.xcodeproj
- App.xcworkspace (úsalo para abrir el proyecto)
- Podfile
DirectorioMyWatch/ (nueva app de watch)
DirectorioMyWatch/ (fuente de la app de watch)
- MyWatchApp.swift
- ContentView.swift
DirectorioAssets.xcassets/
- …
- MyWatch.xcodeproj
Paso 1: Abre tu proyecto iOS en Xcode
Sección titulada “Paso 1: Abre tu proyecto de iOS en Xcode”- Ve a la carpeta de tu proyecto Capacitor
ios/Appcarpeta - Abrir
App.xcworkspace(no.xcodeproj) haciendo doble clic en él - Espera a que Xcode indexe el proyecto
Paso 2: Añade un target de watchOS
Sección titulada “Paso 2: Agregar un target de watchOS”-
En Xcode, ve a Archivo → Nuevo → Destino…
-
En el selector de plantillas:
- Selecciona watchOS pestaña superior
- Elige app
- Haz clic Siguiente
-
Configura tu app para watchOS:
- Nombre del producto:
MyWatch(o el nombre que prefieras) - Equipo: Selecciona tu equipo de Apple Developer
- Identificador de organización: Debe coincidir con tu app de iOS (p. ej.,
app.capgo) - Identificador del bundle: Se generará automáticamente (p. ej.,
app.capgo.myapp.watchkitapp) - Idioma: Swift
- Interfaz de usuario: SwiftUI
- Tipo de Watch App: App (no App para una app iOS existente)
- Desmarcar Incluir escena de notificación (a menos que lo necesites)
- Desmarcar Incluir complicación (a menos que lo necesites)
- Nombre del producto:
-
Haz clic Finalizar
-
Cuando aparezca el prompt “Activate ‘MyWatch’ scheme?”, haz clic Activar
Paso 3: Configura los ajustes de la Watch App
Sección titulada “Paso 3: Configurar los ajustes de la Watch App”-
En el Project Navigator (barra lateral izquierda), selecciona tu proyecto (el icono azul de arriba)
-
Selecciona tu target de watch (ej. “MyWatch”) de la lista de targets
-
Ve a la pestaña General pestaña:
- Nombre visible: El nombre que aparece debajo del icono de la app (ej. “My App”)
- Identificador del bundle: Debe terminar con
.watchkitapp - Versión: Coincide con la versión de tu app de iOS
- Build: Coincide con el número de build de tu app iOS
-
Ve a Firma y capacidades pestaña:
- Activar Gestionar la firma automáticamente
- Selecciona tu Equipo
- Xcode creará los perfiles de aprovisionamiento automáticamente
-
Configurar Información de despliegue:
- Versiones mínimas: watchOS 9.0 o posterior
Paso 4: Añadir CapgoWatchSDK vía Swift Package Manager
Sección titulada “Paso 4: Añadir CapgoWatchSDK vía Swift Package Manager”El CapgoWatchSDK proporciona una WatchConnector clase para la comunicación.
-
En Xcode, ve a Archivo → Añadir dependencias de paquetes…
-
En el campo de búsqueda, escribe:
https://github.com/Cap-go/capacitor-watch.git -
Pulsa Enter y espera a que Xcode descargue el paquete
-
Configura el paquete:
- Regla de dependencia: “Hasta la próxima versión principal” con “8.0.0”
- Haz clic Añadir paquete
-
Elige qué productos añadir:
- IMPORTANTE: Selecciona solo
CapgoWatchSDK - Asegúrate de que se añada a tu target de watch (p. ej., “MyWatch”), no a la app de iOS
- Haz clic Añadir paquete
- IMPORTANTE: Selecciona solo
Paso 5: Implementar la Watch App
Sección titulada “Paso 5: Implementar la Watch App”Ahora vamos a crear la watch app code. Reemplaza los archivos autogenerados por los siguientes:
5.1 Crear el punto de entrada de la app
Sección titulada “5.1 Crear el punto de entrada de la app”Editar MyWatch/MyWatchApp.swift:
import SwiftUIimport CapgoWatchSDK
@mainstruct MyWatchApp: App { init() { // Activate WatchConnectivity when app launches WatchConnector.shared.activate() }
var body: some Scene { WindowGroup { ContentView() } }}5.2 Crear la vista principal
Sección titulada “5.2 Crear la vista principal”Editar MyWatch/ContentView.swift:
import SwiftUIimport CapgoWatchSDK
struct ContentView: View { // Observe the WatchConnector for automatic UI updates @ObservedObject var connector = WatchConnector.shared
// Local state @State private var messageText = "" @State private var statusMessage = "Ready"
var body: some View { ScrollView { VStack(spacing: 16) { // Connection Status ConnectionStatusView(connector: connector)
Divider()
// Message Input TextField("Message", text: $messageText) .textFieldStyle(.roundedBorder)
// Send Buttons HStack { Button("Send") { sendMessage() } .disabled(!connector.isReachable || messageText.isEmpty)
Button("Request") { sendWithReply() } .disabled(!connector.isReachable || messageText.isEmpty) }
Divider()
// Status Text(statusMessage) .font(.caption) .foregroundColor(.secondary)
// Last Received Message if !connector.lastMessage.isEmpty { VStack(alignment: .leading) { Text("Last Message:") .font(.caption) .foregroundColor(.secondary) Text(formatMessage(connector.lastMessage)) .font(.caption2) } .frame(maxWidth: .infinity, alignment: .leading) } } .padding() } }
private func sendMessage() { connector.sendMessage(["text": messageText, "timestamp": Date().timeIntervalSince1970]) statusMessage = "Message sent" messageText = "" }
private func sendWithReply() { connector.sendMessage(["text": messageText, "needsReply": true]) { reply in DispatchQueue.main.async { statusMessage = "Reply: \(formatMessage(reply))" } } messageText = "" }
private func formatMessage(_ message: [String: Any]) -> String { message.map { "\($0.key): \($0.value)" }.joined(separator: ", ") }}
// Separate view for connection statusstruct ConnectionStatusView: View { @ObservedObject var connector: WatchConnector
var body: some View { HStack { Circle() .fill(connector.isReachable ? Color.green : Color.red) .frame(width: 12, height: 12)
Text(connector.isReachable ? "Connected" : "Disconnected") .font(.headline)
Spacer()
if connector.isActivated { Image(systemName: "checkmark.circle.fill") .foregroundColor(.green) } } }}
#Preview { ContentView()}Paso 6: Configurar la app de iOS para WatchConnectivity
Sección titulada “Paso 6: Configurar la app de iOS para WatchConnectivity”Tu app de iOS también necesita la capacidad WatchConnectivity.
-
En el Project Navigator, selecciona tu proyecto
-
Selecciona tu target de la app iOS (no el target del watch)
-
Ve a Firma y capacidades pestaña
-
Haz clic + Capacidad
-
Buscar y añadir WatchConnectivity (si está disponible) o puede añadirse automáticamente
-
El plugin Capacitor gestiona el lado de iOS automáticamente, pero asegúrate de que tu Info.plist tenga:
<key>WKCompanionAppBundleIdentifier</key><string>app.capgo.myapp.watchkitapp</string>
Paso 7: Compilar y ejecutar
Sección titulada “Paso 7: Compilar y ejecutar”Ejecutar en simulador
Sección titulada “Ejecutar en el simulador”-
Selecciona tu esquema de reloj desde el selector de esquemas (parte superior de la ventana de Xcode)
-
Elige un simulador de reloj:
- Haz clic en el selector de dispositivo junto al esquema
- Selecciona un simulador de Apple Watch (p. ej., “Apple Watch Series 9 (45mm)”)
-
Haz clic en Ejecuta botón (▶️) o presiona
Cmd + R -
El simulador de iOS se lanzará con el iPhone y el Apple Watch
Ejecutar en dispositivo físico
Sección titulada “Ejecutar en dispositivo físico”-
Conecta tu iPhone por USB
-
Asegúrate de que tu Apple Watch esté emparejado con ese iPhone
-
Selecciona el scheme de tu Apple Watch
-
Selecciona tu Apple Watch físico en la lista de dispositivos
-
Haz clic Ejecuta
-
Primera vez: Es posible que debas confiar en tu ordenador en ambos dispositivos
Paso 8: Probar la comunicación
Sección titulada “Paso 8: Probar la comunicación”De iPhone (Capacitor) al Watch
Sección titulada “Del iPhone (Capacitor) al Watch”En tu app de Capacitor:
import { CapgoWatch } from '@capgo/capacitor-watch';
// Check connectionconst info = await CapgoWatch.getInfo();console.log('Watch reachable:', info.isReachable);
// Send a messageif (info.isReachable) { await CapgoWatch.sendMessage({ data: { action: 'update', value: 'Hello from iPhone!' } });}Del Watch al iPhone
Sección titulada “Del Watch al iPhone”La app del Watch usa WatchConnector:
// Send message (fire and forget)WatchConnector.shared.sendMessage(["action": "buttonTapped"])
// Send message with replyWatchConnector.shared.sendMessage(["request": "getData"]) { reply in print("Got reply: \(reply)")}Gestionar mensajes en iPhone
Sección titulada “Gestionar mensajes en el iPhone”// Listen for messages from watchawait CapgoWatch.addListener('messageReceived', (event) => { console.log('Message from watch:', event.message); // { action: 'buttonTapped' }});
// Handle messages that need a replyawait CapgoWatch.addListener('messageReceivedWithReply', async (event) => { console.log('Request from watch:', event.message);
// Send reply back await CapgoWatch.replyToMessage({ callbackId: event.callbackId, data: { status: 'success', items: ['item1', 'item2'] } });});Avanzado: delegate personalizado para más control
Sección titulada “Avanzado: delegate personalizado para más control”Si necesitas más control, implementa WatchConnectorDelegate:
import SwiftUIimport CapgoWatchSDK
class WatchHandler: WatchConnectorDelegate { func didReceiveMessage(_ message: [String: Any]) { print("Received: \(message)") // Handle incoming message }
func didReceiveMessageWithReply(_ message: [String: Any], replyHandler: @escaping ([String: Any]) -> Void) { print("Received request: \(message)") // Process and send reply replyHandler(["status": "processed"]) }
func didReceiveApplicationContext(_ context: [String: Any]) { print("Context updated: \(context)") }
func didReceiveUserInfo(_ userInfo: [String: Any]) { print("User info received: \(userInfo)") }
func reachabilityDidChange(_ isReachable: Bool) { print("Reachability changed: \(isReachable)") }
func activationDidComplete(with state: WCSessionActivationState) { print("Activation completed: \(state.rawValue)") }}
// In your app setup:let handler = WatchHandler()WatchConnector.shared.delegate = handlerWatchConnector.shared.activate()Solución de problemas
Sección titulada “Solución de problemas”La app Watch no aparece en el Watch
Sección titulada “La app Watch no aparece en el Watch”- Asegúrate de que los bundle IDs estén correctamente relacionados (el bundle ID de la app Watch debe ser el bundle ID de la app iOS +
.watchkitapp) - Verifica que ambas apps estén firmadas con el mismo equipo
- En un dispositivo físico: abre la app Watch en el iPhone → Mi Watch → desplázate hasta encontrar tu app → actívala
No se reciben los mensajes
Sección titulada “Mensajes no recibidos”- Verifica que ambas apps tengan WCSession activada
- Verificar
isReachableantes de enviar mensajes - Para garantizar la entrega, usa
transferUserInfoen lugar desendMessage - Asegúrate de que los listeners estén registrados antes de que el otro dispositivo envíe mensajes
Error “Session Not Activated”
Sección titulada “Error “Session Not Activated””- Llama a
WatchConnector.shared.activate()temprano en el ciclo de vida de la app - En iOS, el plugin se activa automáticamente; asegúrate de que esté importado
- Verifica que la capability WatchConnectivity esté añadida al target de iOS
Errores de build con CapgoWatchSDK
Sección titulada “Errores de build con CapgoWatchSDK”- Asegúrate de que el paquete esté añadido al target de watch, no al target de iOS
- Limpia la carpeta de build: Producto → Limpiar carpeta de build (Cmd + Shift + K)
- Restablece las cachés de paquetes: Archivo → Packages → Reset Package Caches
Problemas con el simulador
Sección titulada “Problemas del simulador”- Restablecer los simuladores: Dispositivo → Borrar todo el contenido y los ajustes
- Asegura que los simuladores de iOS y watchOS sean pares compatibles
- Ambos simuladores deben estar en ejecución para que la comunicación funcione
Próximos pasos
Sección titulada “Próximos pasos”- Crear una app para Wear OS para relojes Android
- Referencia de API - Documentación completa de API
- Patrones de comunicación - Cuándo usar cada método
- App de ejemplo - Ejemplo completo funcional
Continuar desde Crear una app para watchOS
Sección titulada “Continuar desde Creating a watchOS App”Si estás usando Crear una app para watchOS 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.